Soumettre un document UBL ou CII fini (transmission directe)
- Dans le bac à sable
En termes simples
Pour les ERP qui écrivent déjà de l’UBL ou du CII, ou du FA(3) pour le canal KSeF. Aucun mapping n’a lieu : le service exécute
les validateurs officiels du canal (pour FA(3) : le XSD plus les règles de fichier et de date de KSeF) et envoie le
fichier tel quel. Un PDF Factur-X ou ZUGFeRD passe par le même point d’accès
comme application/pdf. Le XML est analysé sans entités, sans DTD et sans accès réseau, et un fichier avec un
DOCTYPE est refusé (EI-XML-DTD) avant qu’un validateur ne le lise, tout comme un fichier mal formé
(EI-XML-SYNTAX) ou qui n’est pas une facture connue du canal (EI-XML-TYPE). Depuis la 0.18.4, le même fichier renvoyé
pour le client et le canal est la facture déjà détenue (duplicate_of), comme sur POST /invoices ; rien de nouveau n’est envoyé.
apiKeyAuthorizationBearer <token>Envoyez votre clé sous forme de jeton bearer : Authorization: Bearer <your-api-key>. L’état du service est le seul appel qui ne nécessite pas de clé.
route*stringLe canal du pays. Les mêmes valeurs que country_route dans les événements de statut.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringL’identifiant du document propre à l’ERP.
length <= 100Idempotency-Key*stringUne clé unique par requête logique (un UUID convient). Conservée aussi longtemps que les données du client. Avec la clé de l’opérateur, elle ne peut pas commencer par client: (400), la forme sous laquelle les clés de client sont stockées.
8 <= length <= 100body*stringAcceptée pour traitement.
application/json- response
id*stringstate*InvoiceStateL’état propre au service pour une facture. Les événements de statut rapportent le cycle de vie visible du partenaire ;
queued et submitting sont des étapes internes entre validated et submitted. validation_failed signifie que les règles officielles ont refusé le document ; depuis la
0.18.4, un contrôle qui n’a pas pu s’exécuter (KOSIT-RUN, EI-PDF-CHECK) est retenté, puis finit en dead_letter avec ce
code. Une dead_letter garde son document, de sorte que le même fichier répond avec duplicate_of ; depuis la 0.18.6, l’
opérateur peut annuler celle pour laquelle aucun appel au canal n’a été fait, et le fichier peut alors repartir.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Renseigné quand le même document a déjà été accepté pour ce client et ce canal ; rien de nouveau n’est envoyé. Une soumission qui s’est terminée en rejected, validation_failed ou cancelled ne compte pas, donc le fichier peut être renvoyé. Depuis la 0.18.5, cela vaut aussi pour deux requêtes envoyées au même moment, sous des clés différentes ; l’une crée la facture et l’autre répond avec duplicate_of.
links*route?RouteSeulement quand le routeur a choisi le canal.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Seulement quand la requête a omis le canal.
"router"route_rule?stringLa règle du routeur qui a choisi le canal ; également écrite dans le journal d’audit sous 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/xml?route=PL-KSEF&invoice_ref=INV-2026-0042" \ -H "Authorization: Bearer <your-api-key>" \ -H "Idempotency-Key: order-2026-0001" \ -H "Content-Type: application/xml" \ -d '<?xml version="1.0" encoding="UTF-8"?><Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/"><Naglowek><KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-10-01T05:44:07Z</DataWytworzeniaFa><SystemInfo>eurinvoice</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>1234567890</NIP><Nazwa>Wisła Systemy sp. z o.o.</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Floriańska 22</AdresL1><AdresL2>31-019 Kraków</AdresL2></Adres><DaneKontaktowe><Email>[email protected]</Email><Telefon>+48 12 345 67 89</Telefon></DaneKontaktowe></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>5213000000</NIP><Nazwa>Mazowiecka Hurtownia S.A.</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>al. Jerozolimskie 100</AdresL1><AdresL2>00-807 Warszawa</AdresL2></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-09-26</P_1><P_1M>Kraków</P_1M><P_2>FV/2026/09/057</P_2><P_6>2026-09-25</P_6><P_13_1>25450.00</P_13_1><P_14_1>5853.50</P_14_1><P_15>31303.50</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Wdrożenie KSeF 2.0</P_7><P_8A>LS</P_8A><P_8B>1</P_8B><P_9A>24000.00</P_9A><P_11>24000.00</P_11><P_12>23</P_12></FaWiersz><FaWiersz><NrWierszaFa>2</NrWierszaFa><P_7>Obsługa odrzuconych faktur</P_7><P_8A>MON</P_8A><P_8B>1</P_8B><P_9A>1450.00</P_9A><P_11>1450.00</P_11><P_12>23</P_12></FaWiersz><Platnosc><TerminPlatnosci><Termin>2026-10-10</Termin></TerminPlatnosci><FormaPlatnosci>6</FormaPlatnosci><RachunekBankowy><NrRB>61109010140000071219812874</NrRB><SWIFT>WBKPPLPP</SWIFT></RachunekBankowy></Platnosc><WarunkiTransakcji><Zamowienia><DataZamowienia>2026-09-26</DataZamowienia><NrZamowienia>ZAM-2026-311</NrZamowienia></Zamowienia></WarunkiTransakcji></Fa><Stopka><Rejestry><PelnaNazwa>Wisła Systemy sp. z o.o.</PelnaNazwa><KRS>0000123456</KRS></Rejestry></Stopka></Faktura>'{ "links": { "self": "/invoices/inv_d249e33382ce2911876b7295", "events": "/invoices/inv_d249e33382ce2911876b7295/events" }, "id": "inv_d249e33382ce2911876b7295", "state": "queued"}Soumettre une facture ou un avoir en JSON canonique POST
Le service contrôle d’emblée le document par rapport au modèle canonique et aux pré-contrôles, et répond 422 si l’un des deux échoue. Tout le reste s’exécute de façon asynchrone (construction, validation officielle, transmission au canal, statuts) et est signalé par des événements de statut. Une nouvelle soumission corrigée d’une facture rejetée utilise le même invoice_ref et une nouvelle Idempotency-Key ; le service relie les tentatives. En production, un export ERP n’est lu que si les paramètres du connecteur du client contiennent ses propres données de vendeur et de paiement, et non l’exemple du mapping : sinon 422 connector-settings-missing, qui indique ce qui manque. Un bac à sable le lit avec l’exemple, comme avant.
Consulter un code d’erreur ou de motif GET
Renvoie l’entrée du catalogue pour un identifiant de règle, un code d’erreur du canal ou un code de motif français (identifiants et alias).