Inviare una fattura o una nota di credito come JSON canonico
- Nella sandbox
In parole semplici
Il servizio controlla subito il documento rispetto al modello canonico e ai controlli preliminari, e risponde 422 se uno dei due fallisce. Tutto il resto avviene in modo asincrono (generazione, validazione ufficiale, invio al canale, stati) e viene riportato con gli eventi di stato.
L’invio corretto di una fattura scartata usa lo stesso invoice_ref e una nuova
Idempotency-Key; il servizio collega i tentativi.
In produzione un export dell’ERP viene letto solo quando le impostazioni del connettore del cliente contengono
il suo venditore e i suoi dati di pagamento, non l’esempio della mappatura: altrimenti 422 connector-settings-missing,
con l’indicazione di ciò che manca. Una sandbox lo legge con l’esempio, come prima.
apiKeyAuthorizationBearer <token>Inviare la chiave come token bearer: Authorization: Bearer <your-api-key>. Lo stato del servizio è l’unica chiamata che non richiede una chiave.
Idempotency-Key*stringUna chiave unica per ogni richiesta logica (va bene un UUID). Conservata finché si conservano i dati del cliente. Con la chiave dell’operatore non può iniziare con client: (400), la forma con cui si conservano le chiavi dei clienti.
8 <= length <= 100application/json- body
Inviare document (una fattura canonica) oppure connector con export (un documento dell’ERP come l’ERP lo
restituisce), non entrambi (400). Un export viene mappato dalla versione di mappatura attiva del connettore, o da mapping_version, e
poi trattato esattamente come la fattura canonica a cui corrisponde; l’export stesso viene conservato con la fattura
(erp-export). Il profilo XRechnung del connettore vale solo su DE-XRECHNUNG, e quando il router sceglie per
un acquirente tedesco. Un risultato della mappatura (un’unità sconosciuta, un campo ERP mancante) risponde 422 con il nome del campo ERP.
connector?connectorDa quale ERP proviene l’export. business-central: una fattura di vendita di Business Central API v2.0. Un altro oggetto SAP, come un ordine o una bozza, risponde 400.
"business-central""sap-b1"export?Il documento dell’ERP come l’ERP lo restituisce. I campi che la mappatura non legge vengono ignorati.
mapping_version?mapping_versionUna versione di mappatura di quel connettore. Quella attiva se omessa; una sconosciuta risponde 400.
^v[0-9]+$client?stringIl cliente a cui appartiene la fattura. La chiave dell’operatore lo indica (se omesso, la fattura appartiene al cliente local dell’operatore). La chiave di un cliente può ometterlo o indicare il proprio cliente; ogni altro cliente risponde 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringL’ID del documento proprio dell’ERP. Riportato in ogni evento di stato.
length <= 100route?|Se omesso o null, il router lo sceglie dal documento: il country del venditore,
il buyer.address.country dell’acquirente, profile, le credenziali conservate del cliente e, quando una regola
lo richiede, la registrazione Peppol dell’acquirente. Quando nessuna regola corrisponde, la risposta è 422 con EI-ROUTE-UNDECIDED o
EI-ROUTE-PEPPOL-UNKNOWN (source router). POST /validate lo richiede ancora.
environment?stringDeve corrispondere all’ambiente della chiave API; indicato esplicitamente come protezione.
"sandbox""production"document*Una fattura nel modello canonico. Il significato dei campi segue il modello semantico EN 16931. I totali non fanno parte del modello: il servizio li calcola dalle righe.
formats?array<>Quali documenti produrre dove il canale lascia una scelta (Germania: xrechnung-ubl,
xrechnung-cii o zugferd; Francia: ubl, cii o facturx). I valori predefiniti per canale si fissano all’avvio.
Su POST /invoices indicarne al massimo uno: è il documento che viene generato, controllato e inviato (il primo di ogni
elenco sopra, se omesso). Peppol e Romania usano ubl, la Polonia fa3. Un altro valore, o più di uno,
risponde 400. Factur-X e ZUGFeRD vengono controllati due volte: il CII interno con le regole del canale, poi il PDF.
Sul canale tedesco un documento senza profile viene generato come XRechnung.
erp_totals?I totali calcolati dall’ERP. Il servizio calcola i propri dalle righe e rifiuta la fattura (422, EI-TOTALS-MISMATCH, con il nome del campo ERP) se differiscono, invece di inviare un documento con cui l’ERP non concorda. Un connettore li legge dall’export stesso; i totali indicati qui prevalgono.
Accettata per l’elaborazione. Seguirla con i link restituiti oppure attendere gli eventi di stato.
application/json- response
id*stringstate*InvoiceStateLo stato proprio del servizio per una fattura. Gli eventi di stato riportano il ciclo di vita visibile al partner;
queued e submitting sono passaggi interni tra validated e submitted. validation_failed significa che le regole ufficiali hanno rifiutato il documento; dalla
0.18.4 un controllo che non è stato eseguito (KOSIT-RUN, EI-PDF-CHECK) viene ritentato, poi termina in dead_letter con quel
codice. Una dead_letter tiene il documento, quindi lo stesso file risponde con duplicate_of; dalla 0.18.6
l’operatore può annullarne una per cui non è stata fatta alcuna chiamata al canale, e allora il file può partire di nuovo.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Impostato quando lo stesso documento era già stato accettato per questo cliente e canale; non viene inviato nulla di nuovo. Un invio terminato in rejected, validation_failed o cancelled non conta, quindi il file può essere inviato di nuovo. Dalla 0.18.5 vale anche per due richieste inviate nello stesso momento con chiavi diverse; una crea la fattura e l’altra risponde con duplicate_of.
links*route?RouteSolo quando il router ha scelto il canale.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Solo quando la richiesta ha omesso il canale.
"router"route_rule?stringLa regola del router che ha scelto il canale; scritta anche nel registro di audit come route_chosen.
"fr-domestic""fr-cross-border""pl-domestic""ro-domestic""be-domestic""de-domestic-peppol""de-domestic""cross-border-peppol"curl -X POST "https://example.com/invoices" \ -H "Authorization: Bearer <your-api-key>" \ -H "Idempotency-Key: order-2026-0001" \ -H "Content-Type: application/json" \ -d '{ "invoice_ref": "CAPTURE-JSON-1790961440", "route": "DE-XRECHNUNG", "environment": "sandbox", "document": { "lang": "de", "country": "DE", "invoice": { "number": "DOC-mux3dlqm", "issue_date": "2026-09-26", "due_date": "2026-10-10", "type_code": 380, "currency": "EUR", "buyer_reference": "PO-88731", "period": { "start": "2026-09-01", "end": "2026-09-30" }, "notes": [ "Vielen Dank für Ihren Auftrag." ] }, "seller": { "name": "Nordlicht Software GmbH", "address": { "street": "Hafenstraße 12", "city": "Hamburg", "postcode": "20457", "country": "DE" }, "vat_id": "DE938296582", "tax_number": "27/123/45678", "company_id": "HRB 123456", "register": "Amtsgericht Hamburg HRB 123456", "managing_directors": "Geschäftsführer: Jana Petersen", "legal_info": "GmbH", "endpoint": { "id": "DE938296582", "scheme": "9930" }, "contact": { "name": "Jana Petersen", "email": "[email protected]", "phone": "+49 40 1234567" }, "brand_color": "#1160FF", "accent_color": "#FF9021" }, "buyer": { "name": "Brauhaus Weber AG", "address": { "street": "Marienplatz 4", "city": "München", "postcode": "80331", "country": "DE" }, "vat_id": "DE965003781", "endpoint": { "id": "DE965003781", "scheme": "9930" } }, "lines": [ { "name": "E-Rechnung Einführung (Festpreis)", "description": "Mapping Business Central → EN 16931, Validierung XRechnung, Test im Peppol-Testnetz", "quantity": 1, "unit": "LS", "unit_price": 5900, "vat_category": "S", "vat_rate": 19 }, { "name": "Betreuung abgelehnter Rechnungen", "description": "Care Plus, September 2026", "quantity": 1, "unit": "MON", "unit_price": 349, "vat_category": "S", "vat_rate": 19 }, { "name": "Zusätzliche Schulung", "description": "Remote, Buchhaltungsteam", "quantity": 3, "unit": "HUR", "unit_price": 120, "vat_category": "S", "vat_rate": 19 } ], "payment": { "means_code": 58, "iban": "DE89 3704 0044 0532 0130 00", "bic": "COBADEFFXXX", "reference": "RE-2026-0143", "terms": "Zahlbar innerhalb von 14 Tagen ohne Abzug." }, "profile": "xrechnung" } }'{ "links": { "self": "/invoices/inv_936a93e38de84e7b0a1d7681", "events": "/invoices/inv_936a93e38de84e7b0a1d7681/events" }, "id": "inv_936a93e38de84e7b0a1d7681", "state": "queued"}Elencare e cercare le fatture GET
La chiave di un cliente vede le fatture del proprio cliente; l’operatore vede quelle di ogni cliente, oppure quelle di un cliente con client. Le righe contengono ciò che contiene GET /invoices/{id}, senza documents, e nessun contenuto della fattura: né acquirente né importi, e nessuna data di emissione (per la Romania e la Polonia la deadline_at ne deriva, con un’approssimazione di pochi giorni). Un parametro sconosciuto risponde 400.
Inviare un documento UBL o CII già pronto (pass-through) POST
Per gli ERP che già scrivono UBL o CII, oppure FA(3) per il canale KSeF. Non avviene alcuna mappatura: il servizio esegue i validatori ufficiali del canale (per FA(3): l’XSD più le regole di KSeF sul file e sulle date) e invia il file senza modificarlo. Un PDF Factur-X o ZUGFeRD passa dallo stesso endpoint come application/pdf. L’XML viene letto con entità, DTD e accesso alla rete disattivati, e un file con un DOCTYPE viene rifiutato (EI-XML-DTD) prima che un validatore lo legga, così come un file non ben formato (EI-XML-SYNTAX) o che non è una fattura che il canale conosce (EI-XML-TYPE). Dalla 0.18.4 lo stesso file inviato di nuovo per lo stesso cliente e canale è la fattura già conservata (duplicate_of), come su POST /invoices; non viene inviato nulla di nuovo.