Società Consortile di Informatica
delle Camere di Commercio Italiane per azioni
Manuale Utente
TebeniService 5.0.0
Versione doc:
Descr. modifiche:
Motivazioni :
05.00.00
Data Versione: 03/03/15
Aggiunto parametro per gestione multilingua delle visualizzazioni
TebeniService
Indice generale
1.Introduzione al documento........................................................................................................ 3
1.1 Scopo e campo di applicazione del documento.....................................................................3
1.2 Riferimenti............................................................................................................................. 3
1.3 Termini e definizioni............................................................................................................... 3
2 TebeniService – servizio di validazione...................................................................................4
2.1 Descrizione servizio............................................................................................................... 4
2.2 Modalità invocazione............................................................................................................. 4
2.2.1 Parametri......................................................................................................................... 4
3 TebeniService – servizio di visualizzazione in HTML..............................................................7
3.1 Descrizione servizio............................................................................................................... 7
3.2 Modalità invocazione............................................................................................................. 7
3.2.1 Parametri......................................................................................................................... 7
4 TebeniService – servizio di visualizzazione in PDF.................................................................8
4.1 Descrizione servizio............................................................................................................... 8
4.2 Modalità invocazione............................................................................................................. 8
4.2.1 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
TebeniService
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]
http://tebeni.infocamere.it/
1.3 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
TebeniService
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 1
2.2 Modalità invocazione
Il servizio è richiamabile con un'invocazione http – method POST all'url sottostante con un enctype
di tipo multipart/form-data:
•
http://tebeni.infocamere.it/teniWeb/TebeServiceValidateRequest
L'invocazione con method GET non è supportata.
2.2.1 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
2.2.1.1 Autenticazione: token
In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e)
Successivamente verrà concordato con ogni cliente un token dedicato.
2.2.1.2 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="http://tebe.infocamere.it/2009/teberesponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tebe.infocamere.it/2009/teberesponse
http://tebeni.intra.infocamere.it/client_TEBEplus/teberesponse.xsd">
<richiesta>
<xbrlInstanceName>instance.xbrl</xbrlInstanceName>
<serviceRequired>validate</serviceRequired>
Pagina 4 di 14
TebeniService
<serviceDetails>base</serviceDetails>
</richiesta>
<esito>
<returnCode>OK</returnCode>
<returnMessage>L'istanza è valida secondo il profilo richiesto</returnMessage>
<msec>4396</msec>
</esito>
<xbrlData>
<xbrlCodFisc>012345678901</xbrlCodFisc>
<xbrlDenom>PROVA SPA</xbrlDenom>
</xbrlData>
</tebeResponse>
Esempio di risposta con esito positivo e segnalazioni:
<?xml version="1.0" encoding="UTF-8"?>
<tebeResponse
xmlns="http://tebe.infocamere.it/2009/teberesponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tebe.infocamere.it/2009/teberesponse
http://tebeni.intra.infocamere.it/client_TEBEplus/teberesponse.xsd">
<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>012345678901</xbrlCodFisc>
<xbrlDenom>PROVA SPA</xbrlDenom>
</xbrlData>
</tebeResponse>
Esempio di risposta con esito negativo:
<?xml version="1.0" encoding="UTF-8"?>
<tebeResponse
xmlns="http://tebe.infocamere.it/2009/teberesponse"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tebe.infocamere.it/2009/teberesponse
http://tebeni.intra.infocamere.it/client_TEBEplus/teberesponse.xsd">
<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
TebeniService
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
TebeniService
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:
•
http://tebenitra.infocamere.it/teniWeb/TebeServiceTransformRequest
L'invocazione con method GET non è supportata.
3.2.1 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
3.2.1.1 Autenticazione: token
In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e)
Successivamente verrà concordato con ogni cliente un token dedicato.
3.2.1.2 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
TebeniService
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:
•
http://tebenitra.infocamere.it/teniWeb/TebeServiceTransformRequest
L'invocazione con method GET non è supportata.
4.2.1 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
4.2.1.1 Autenticazione: token
In prima battuta si tratta di una stringa di test (TebeniService_d6452f0e)
Successivamente verrà concordato con ogni cliente un token dedicato.
4.2.1.2 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
TebeniService
Appendice 1: tabella errori e warning
Errori:
Codice
Controllo
Descrizione
XX
Errore nell'estrazione del file firmato
X0
Il file non è un XBRL oppure è mal firmato
XU
L'istanza o l'html escaped in essa contenuto non sono ben formati (well formed)
X1
L'istanza non è conforme alla tassonomia ufficiale 2014-11-17, la tassonomia <tassonomia_file_xbrl>
referenziata è in vigore solo per depositi di bilancio con data del verbale di approvazione inferiore al 3
marzo 2015
XV
Errore in fase di validazione dell'istanza rispetto alla tassonomia di riferimento
X3
Impossibile identificare il Codice Fiscale (<DatiAnagraficiCodiceFiscale>)
XF
Il Codice Fiscale dichiarato nell'istanza non ha superato il controllo formale
X6
Non è presente alcun campo di tipo numerico per l'annualità di esercizio più recente
X7
Non esiste almeno un campo numerico con valore diverso da zero per l'annualità di esercizio più
recente
X8
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
X9
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
Descrizione
W1
Uno o più dei tag: <ValoreProduzioneRicaviVenditePrestazioni>, <TotaleValoreProduzione>,
<UtilePerditaEsercizio> non sono stati valorizzati per l'annualità di esercizio più recente
WA
I tag <context> dichiarati nell'istanza non consentono di identificare correttamente 1 (o 2) annualità
WC
Errore di validazione nei calcoli
WD
Assenza del tag relativo alla Denominazione (<DatiAnagraficiDenominazione>) per l'annualità di
esercizio più recente
WX
Non è presente l'annualità precedente
WT
Istanza conforme a precedenti versioni della tassonomia
WJ
Possibile incompletezza relativa alle voci Totale crediti, Crediti esigibili oltre, Crediti esigibili entro
WK
La somma Crediti esigibili oltre e Crediti esigibili entro non coincide con il TotaleCrediti
WW
Possibile incompletezza relativa alle voci Totale debiti, Debiti esigibili oltre, Debiti esigibili entro
WS
La somma Debiti esigibili oltre e Debiti esigibili entro non coincide con il Totale Debiti
WY
Possibile incompletezza relativa al Patrimonio Terzi
WZ
La differenza tra data di inizio e fine esercizio è superiore a 14 mesi
Pagina 9 di 14
TebeniService
Codice
Controllo
Descrizione
WN
Anomalie riscontrate nei contesti
WI
L’istanza non contiene nessun valore nella nota integrativa
Pagina 10 di 14
TebeniService
Appendice 2: teberesponse.xsd
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://tebe.infocamere.it/2009/teberesponse"
xmlns="http://tebe.infocamere.it/2009/teberesponse"
version="20141218-A" elementFormDefault="qualified">
<xs:element name="tebeResponse">
<xs:complexType>
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
</xs:complexType>
</xs:element>
ref="richiesta" minOccurs="0" />
ref="esito" />
ref="invioXBRL" minOccurs="0" />
ref="details" minOccurs="0" />
ref="outputTF" minOccurs="0" />
ref="xbrlData" minOccurs="0" />
ref="xbrlSchema" minOccurs="0" />
ref="xbrlContent" minOccurs="0"/>
ref="outputContent" minOccurs="0"/>
<xs:element name="richiesta">
<xs:complexType>
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
</xs:complexType>
</xs:element>
ref="xbrlInstanceName" minOccurs="0" />
ref="serviceRequired" minOccurs="0" />
ref="serviceDetails" minOccurs="0" />
ref="requestedContent" minOccurs="0" />
<xs:element
<xs:element
<xs:element
<xs:element
name="xbrlInstanceName" type="xs:string" />
name="serviceRequired" type="xs:string" />
name="serviceDetails" type="xs:string" />
name="requestedContent" type="xs:string" />
<xs:element name="esito">
<xs:complexType>
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
</xs:complexType>
</xs:element>
ref="returnCode" />
ref="returnMessage" />
ref="msec" minOccurs="0" />
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>
<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>
<xs:element name="teniVersion" type="xs:string" />
<xs:element name="invioXBRL">
Pagina 11 di 14
TebeniService
<xs:complexType>
<xs:sequence>
<xs:element name="ixReturnCode" type="xs:string" />
<xs:element name="ixReturnMessage" type="xs:string" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="details">
<xs:complexType>
<xs:sequence>
<xs:element ref="warnings" minOccurs="0" maxOccurs="1" />
<xs:element ref="errors" minOccurs="0" maxOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="warnings">
<xs:complexType>
<xs:sequence>
<xs:element ref="warning" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="errors">
<xs:complexType>
<xs:sequence>
<xs:element ref="error" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="error">
<xs:complexType>
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
</xs:complexType>
</xs:element>
ref="code" />
ref="description" />
ref="elements" minOccurs="0" />
ref="hints" minOccurs="0" />
<xs:element name="warning">
<xs:complexType>
<xs:sequence>
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
</xs:complexType>
</xs:element>
ref="code" />
ref="description" />
ref="elements" minOccurs="0" />
ref="hints" minOccurs="0" />
<xs:element name="code" type="xs:string" />
<xs:element name="description" type="xs:string" />
<xs:element name="elements">
<xs:complexType>
<xs:sequence>
<xs:element ref="element" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="element" type="xs:string" />
<xs:element name="hints">
<xs:complexType>
<xs:sequence>
<xs:element ref="hint" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="hint" type="xs:string" />
Pagina 12 di 14
TebeniService
<xs:element name="outputTF">
<xs:complexType>
<xs:sequence>
<xs:element ref="completePath" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="completePath" type="xs:string" />
<xs:element name="xbrlData">
<xs:complexType>
<xs:sequence>
<xs:element ref="xbrlCodFisc" minOccurs="0" />
<xs:element ref="xbrlDenom" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<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>
/>
/>
/>
/>
<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:element>
</xs:schema>
/>
/>
/>
/>
Pagina 13 di 14
TebeniService
Appendice 3: esempi di invocazione dei servizi
Servizio di visualizzazione:
<html>
<head>
<title>Form</title>
</head>
<body>
<form name="tebe" action="http://tebeni.infocamere.it/teniWeb/TebeServiceTransformRequest"
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="http://tebeni.infocamere.it/teniWeb/TebeServiceValidateRequest"
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