Manuale Utente TebeniService 5.0.0

Transcript

1 Società Consortile di Informatica delle Camere di Commercio Italiane per azioni Manuale Utente TebeniService Versione doc: Data Versione: 03/03/15 Descr. modifiche: Motivazioni : Aggiunto parametro per gestione multilingua delle visualizzazioni

2 Indice generale 1.Introduzione al documento Scopo e campo di applicazione del documento Riferimenti Termini e definizioni TebeniService servizio di validazione Descrizione servizio Modalità invocazione Parametri TebeniService servizio di visualizzazione in HTML Descrizione servizio Modalità invocazione Parametri TebeniService servizio di visualizzazione in PDF Descrizione servizio Modalità invocazione Parametri...8 Appendice 1: tabella errori e warning...9 Errori:... 9 Warning:...9 Appendice 2: teberesponse.xsd...11 Appendice 3: esempi di invocazione dei servizi...14 Pagina 2 di 14

3 1. Introduzione al documento 1.1 Scopo e campo di applicazione del documento Il documento ha l'obiettivo di descrivere il servizio TebeniService relativo ai bilanci XBRL comprensivi di nota integrativa rilasciato per le software house e la relativa modalità di invocazione. 1.2 Riferimenti [1] Termini e definizioni In questa sezione si riportano termini e definizioni particolari e specifici del documento. Termine Descrizione XBRL extensible Business Reporting Language Pagina 3 di 14

4 2 TebeniService servizio di validazione 2.1 Descrizione servizio TebeniService provvede alla validazione di un'istanza xbrl restituendo un file di risposta (in formato html o xml) con l'esito della validazione. La validazione è fatta nel rispetto delle regole previste dalla tassonomia e dal Registro Imprese. L'esito complessivo della validazione (returncode) può essere: OK xbrl accettato KO xbrl respinto NA servizio non disponibile Le possibili cause d'errore (error - bloccanti ai fini dell'esito complessivo) e le eventuali segnalazioni (warning non bloccanti ai fini dell'esito complessivo) sono presenti in Appendice Modalità invocazione Il servizio è richiamabile con un'invocazione http method POST all'url sottostante con un enctype di tipo multipart/form-data: L'invocazione con method GET non è supportata Parametri servicerequired specifica il servizio da invocare e per il servizio di validazione va impostato a 'validate' xbrlinstancecompletepath il file XBRL da validare teberesponse specifica il formato della risposta 'xml' o 'html' showwarnings se viene valorizzato a 'true' verranno ritornati oltre agli errori anche i warning mentre se non viene valorizzato o viene valorizzato a 'false' verranno restituiti solamente gli errori (vedi Appendice 1) token parametro per l'autenticazione al servizio Autenticazione: token In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e) Successivamente verrà concordato con ogni cliente un token dedicato Formato risposta: teberesponse.xsd La risposta del servizio è conforme allo schema riportato in Appendice 2. Esempio di risposta con esito positivo: <?xml version="1.0" encoding="utf-8"?> <teberesponse xmlns=" xmlns:xsi=" xsi:schemalocation=" <richiesta> <xbrlinstancename>instance.xbrl</xbrlinstancename> <servicerequired>validate</servicerequired> Pagina 4 di 14

5 <servicedetails>base</servicedetails> </richiesta> <esito> <returncode>ok</returncode> <returnmessage>l'istanza è valida secondo il profilo richiesto</returnmessage> <msec>4396</msec> </esito> <xbrldata> <xbrlcodfisc> </xbrlcodfisc> <xbrldenom>prova SPA</xbrlDenom> </xbrldata> </teberesponse> Esempio di risposta con esito positivo e segnalazioni: <?xml version="1.0" encoding="utf-8"?> <teberesponse xmlns=" xmlns:xsi=" xsi:schemalocation=" <richiesta> <xbrlinstancename>instance.xbrl</xbrlinstancename> <servicerequired>validate</servicerequired> <servicedetails>base</servicedetails> </richiesta> <esito> <returncode>ok</returncode> <returnmessage>l'istanza è valida secondo il profilo richiesto</returnmessage> <msec>5361</msec> </esito> <details> <warnings> <warning> <code>wk</code> <description>squadratura relativa alle voci Totale crediti, Crediti esigibili oltre, Crediti esigibili entro.</description> </warning> <warning> <code>ws</code> <description>squadratura relativa alle voci Totale debiti, Debiti esigibili oltre, Debiti esigibili entro.</description> </warning> </warnings> </details> <xbrldata> <xbrlcodfisc> </xbrlcodfisc> <xbrldenom>prova SPA</xbrlDenom> </xbrldata> </teberesponse> Esempio di risposta con esito negativo: <?xml version="1.0" encoding="utf-8"?> <teberesponse xmlns=" xmlns:xsi=" xsi:schemalocation=" <richiesta> <xbrlinstancename>instance.xbrl</xbrlinstancename> <servicerequired>validate</servicerequired> <servicedetails>base</servicedetails> </richiesta> <esito> <returncode>ko</returncode> <returnmessage>l'istanza NON è valida secondo il profilo richiesto</returnmessage> <msec>3980</msec> </esito> <details> <errors> <error> <code>xv</code> <description>errore in fase di validazione dell'istanza rispetto alla tassonomia di riferimento</description> <elements> <element>there has been a schema validation error in "mem:" on line number 91, Pagina 5 di 14

6 column number 105. Error message: cvc-datatype-valid.1.2.1: 'aaa' is not a valid value for 'decimal'.</element> <element>there has been a schema validation error in "mem:" on line number 91, column number 105. Error message: cvc-complex-type.2.2: Element 'itcc-ci:totalerimanenze' must have no element [children], and the value must be valid.</element> </elements> </error> </errors> </details> </teberesponse> Pagina 6 di 14

7 3 TebeniService servizio di visualizzazione in HTML 3.1 Descrizione servizio TebeniService provvede alla trasformazione in formato HTML di un bilancio XBRL in modo da renderlo facilmente consultabile ad un utente. 3.2 Modalità invocazione Il servizio è richiamabile con un'invocazione http method POST all'url sottostante con un enctype di tipo multipart/form-data: L'invocazione con method GET non è supportata Parametri servicerequired specifica il servizio da invocare e per il servizio di visualizzazione va impostata a 'view' xbrlinstancecompletepath il file XBRL da validare outputtf specifica il formato della trasformazione e per ottenere il bilancio trasformato in HTML va impostato a 'html' tflanguage specifica la lingua in cui visualizzare il bilancio XBRL. Di default è 'it' (italiano) ma può essere valorizzato con 'en' (inglese), 'fr' (francese) e 'de' (tedesco). token parametro per l'autenticazione al servizio Autenticazione: token In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e) Successivamente verrà concordato con ogni cliente un token dedicato Formato risposta L'output del servizio è direttamente il file trasformato in HTML oppure, nel caso si sia verificato un errore, un file HTML dato dalla trasformazione del teberesponse.xml con un foglio di stile. Pagina 7 di 14

8 4 TebeniService servizio di visualizzazione in PDF 4.1 Descrizione servizio TebeniService provvede alla trasformazione in formato PDF di un bilancio XBRL in modo da renderlo facilmente consultabile ad un utente. 4.2 Modalità invocazione Il servizio è richiamabile con un'invocazione http method POST all'url sottostante con un enctype di tipo multipart/form-data: L'invocazione con method GET non è supportata Parametri servicerequired specifica il servizio da invocare e per il servizio di visualizzazione va impostata a 'view' xbrlinstancecompletepath il file XBRL da validare outputtf specifica il formato della trasformazione e per ottenere il bilancio trasformato in PDF va impostato a 'pdf' tflanguage specifica la lingua in cui visualizzare il bilancio XBRL. Di default è 'it' (italiano) ma può essere valorizzato con 'en' (inglese), 'fr' (francese) e 'de' (tedesco). token parametro per l'autenticazione al servizio Autenticazione: token In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e) Successivamente verrà concordato con ogni cliente un token dedicato Formato risposta L'output del servizio è direttamente il file trasformato in PDF oppure, nel caso si sia verificato un errore, un file HTML dato dalla trasformazione del teberesponse.xml con un foglio di stile. Pagina 8 di 14

9 Appendice 1: tabella errori e warning Errori: Codice Controllo XX X0 XU X1 XV X3 XF X6 X7 X8 X9 Errore nell'estrazione del file firmato Il file non è un XBRL oppure è mal firmato Descrizione L'istanza o l'html escaped in essa contenuto non sono ben formati (well formed) L'istanza non è conforme alla tassonomia ufficiale , la tassonomia <tassonomia_file_xbrl> referenziata è in vigore solo per depositi di bilancio con data del verbale di approvazione inferiore al 3 marzo 2015 Errore in fase di validazione dell'istanza rispetto alla tassonomia di riferimento Impossibile identificare il Codice Fiscale (<DatiAnagraficiCodiceFiscale>) Il Codice Fiscale dichiarato nell'istanza non ha superato il controllo formale Non è presente alcun campo di tipo numerico per l'annualità di esercizio più recente Non esiste almeno un campo numerico con valore diverso da zero per l'annualità di esercizio più recente L'Utile (perdita) Residua del Patrimonio Netto non coincide con l'utile (perdita) dell'esercizio del Conto Economico per l'annualità di esercizio più recente Il Totale Attivo dello Stato Patrimoniale non coincide con il Totale Passivo dello Stato Patrimoniale per l'annualità di esercizio più recente, oppure sono entrambi assenti Warning: Codice Controllo W1 WA WC WD WX WT WJ WK WW WS WY WZ Descrizione Uno o più dei tag: <ValoreProduzioneRicaviVenditePrestazioni>, <TotaleValoreProduzione>, <UtilePerditaEsercizio> non sono stati valorizzati per l'annualità di esercizio più recente I tag <context> dichiarati nell'istanza non consentono di identificare correttamente 1 (o 2) annualità Errore di validazione nei calcoli Assenza del tag relativo alla Denominazione (<DatiAnagraficiDenominazione>) per l'annualità di esercizio più recente Non è presente l'annualità precedente Istanza conforme a precedenti versioni della tassonomia Possibile incompletezza relativa alle voci Totale crediti, Crediti esigibili oltre, Crediti esigibili entro La somma Crediti esigibili oltre e Crediti esigibili entro non coincide con il TotaleCrediti Possibile incompletezza relativa alle voci Totale debiti, Debiti esigibili oltre, Debiti esigibili entro La somma Debiti esigibili oltre e Debiti esigibili entro non coincide con il Totale Debiti Possibile incompletezza relativa al Patrimonio Terzi La differenza tra data di inizio e fine esercizio è superiore a 14 mesi Pagina 9 di 14

10 Codice Controllo WN WI Anomalie riscontrate nei contesti Descrizione L istanza non contiene nessun valore nella nota integrativa Pagina 10 di 14

11 Appendice 2: teberesponse.xsd <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs=" targetnamespace=" xmlns=" version=" a" elementformdefault="qualified"> <xs:element name="teberesponse"> <xs:element ref="richiesta" minoccurs="0" /> <xs:element ref="esito" /> <xs:element ref="invioxbrl" minoccurs="0" /> <xs:element ref="details" minoccurs="0" /> <xs:element ref="outputtf" minoccurs="0" /> <xs:element ref="xbrldata" minoccurs="0" /> <xs:element ref="xbrlschema" minoccurs="0" /> <xs:element ref="xbrlcontent" minoccurs="0"/> <xs:element ref="outputcontent" minoccurs="0"/> <xs:element name="richiesta"> <xs:element ref="xbrlinstancename" minoccurs="0" /> <xs:element ref="servicerequired" minoccurs="0" /> <xs:element ref="servicedetails" minoccurs="0" /> <xs:element ref="requestedcontent" minoccurs="0" /> <xs:element name="xbrlinstancename" type="xs:string" /> <xs:element name="servicerequired" type="xs:string" /> <xs:element name="servicedetails" type="xs:string" /> <xs:element name="requestedcontent" type="xs:string" /> <xs:element name="esito"> <xs:element ref="returncode" /> <xs:element ref="returnmessage" /> <xs:element ref="msec" minoccurs="0" /> <xs:element ref="teniversion" /> <xs:element name="returncode"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="ok" /> <xs:enumeration value="ko" /> <xs:enumeration value="na" /> </xs:restriction> </xs:simpletype> <xs:element name="returnmessage" type="xs:string" /> <xs:element name="msec"> <xs:simpletype> <xs:restriction base="xs:integer"> <xs:mininclusive value="0" /> </xs:restriction> </xs:simpletype> <xs:element name="teniversion" type="xs:string" /> <xs:element name="invioxbrl"> Pagina 11 di 14

12 <xs:element name="ixreturncode" type="xs:string" /> <xs:element name="ixreturnmessage" type="xs:string" /> <xs:element name="details"> <xs:element ref="warnings" minoccurs="0" maxoccurs="1" /> <xs:element ref="errors" minoccurs="0" maxoccurs="1" /> <xs:element name="warnings"> <xs:element ref="warning" minoccurs="1" maxoccurs="unbounded" /> <xs:element name="errors"> <xs:element ref="error" minoccurs="1" maxoccurs="unbounded" /> <xs:element name="error"> <xs:element ref="code" /> <xs:element ref="description" /> <xs:element ref="elements" minoccurs="0" /> <xs:element ref="hints" minoccurs="0" /> <xs:element name="warning"> <xs:element ref="code" /> <xs:element ref="description" /> <xs:element ref="elements" minoccurs="0" /> <xs:element ref="hints" minoccurs="0" /> <xs:element name="code" type="xs:string" /> <xs:element name="description" type="xs:string" /> <xs:element name="elements"> <xs:element ref="element" minoccurs="1" maxoccurs="unbounded" /> <xs:element name="element" type="xs:string" /> <xs:element name="hints"> <xs:element ref="hint" minoccurs="1" maxoccurs="unbounded" /> <xs:element name="hint" type="xs:string" /> Pagina 12 di 14

13 <xs:element name="outputtf"> <xs:element ref="completepath" /> <xs:element name="completepath" type="xs:string" /> <xs:element name="xbrldata"> <xs:element ref="xbrlcodfisc" minoccurs="0" /> <xs:element ref="xbrldenom" minoccurs="0" /> <xs:element name="xbrlcodfisc" type="xs:string" /> <xs:element name="xbrldenom" type="xs:string" /> <xs:element name="xbrlschema" type="xs:string" /> <xs:element name="xbrlcontent"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="ni" /> <xs:enumeration value="pc" /> <xs:enumeration value="bi" /> <xs:enumeration value="na" /> </xs:restriction> </xs:simpletype> <xs:element name="outputcontent"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="ni" /> <xs:enumeration value="pc" /> <xs:enumeration value="bi" /> <xs:enumeration value="na" /> </xs:restriction> </xs:simpletype> </xs:schema> Pagina 13 di 14

14 Appendice 3: esempi di invocazione dei servizi Servizio di visualizzazione: <html> <head> <title>form</title> </head> <body> <form name="tebe" action=" method="post" enctype="multipart/form-data"> Servizio (servicerequired): <input name="servicerequired" type="text" value="view" /><br /> File xbrl (xbrlinstancecompletepath): <input name="xbrlinstancecompletepath" type="file" /><br /> Formato trasformazione [html/pdf] (outputtf): <input name="outputtf" type="text" value="html" /><br /> Token (token): <input name="token" type="text" value="tebeniservice_d6452f0e" size="30" /><br /> <input type="submit" value="invia" /> </form> </body> </html> Servizio di validazione: <html> <head> <title>form</title> </head> <body> <form name="tebe" action=" method="post" enctype="multipart/form-data"> Servizio (servicerequired): <input name="servicerequired" type="text" value="validate" /><br /> File xbrl (xbrlinstancecompletepath): <input name="xbrlinstancecompletepath" type="file" /><br /> Visualizza warning [true/false] (showwarnings): <input name="showwarnings" type="text" value="true" /><br /> Token (token): <input name="token" type="text" value="tebeniservice_d6452f0e" size="30" /><br /> <input type="submit" value="invia" /> </form> </body> </html> Pagina 14 di 14