Transmiteți o factură sau o notă de credit ca JSON canonic
- În sandbox
În cuvinte simple
Serviciul verifică imediat documentul față de modelul canonic și verificările preliminare și răspunde cu 422 dacă oricare eșuează. Tot ce urmează rulează asincron (generare, validare oficială, transmiterea pe canal, stări) și este raportat prin evenimente de stare.
O retransmitere corectată a unei facturi respinse folosește același invoice_ref și un Idempotency-Key nou;
serviciul leagă încercările.
În producție, un export ERP este citit doar când setările conectorului clientului conțin propriul vânzător și
propria plată, nu exemplul din mapare: altfel 422 connector-settings-missing, cu indicarea a ceea ce lipsește. Un sandbox îl citește
cu exemplul, ca până acum.
apiKeyAuthorizationBearer <token>Trimiteți cheia ca token de tip bearer: Authorization: Bearer <your-api-key>. Starea serviciului este singurul apel care nu necesită cheie.
Idempotency-Key*stringO cheie unică pentru fiecare cerere logică (un UUID este suficient). Se păstrează cât timp se păstrează datele clientului. Cu cheia operatorului nu poate începe cu client: (400), forma sub care sunt stocate cheile clienților.
8 <= length <= 100application/json- body
Trimiteți fie document (o factură canonică), fie connector cu export (un document ERP așa cum îl returnează ERP-ul),
nu ambele (400). Un export este mapat cu versiunea activă a mapării conectorului sau cu mapping_version, apoi
tratat exact ca factura canonică în care este mapat; exportul însuși este păstrat împreună cu factura
(erp-export). Profilul XRechnung al conectorului se aplică doar pe DE-XRECHNUNG și când routerul alege pentru
un cumpărător german. O constatare a mapării (o unitate necunoscută, un câmp ERP lipsă) primește 422, cu numele câmpului ERP.
connector?connectorDe la ce ERP provine exportul. business-central: o factură de vânzare Business Central API v2.0. Un alt obiect SAP, cum ar fi o comandă sau o ciornă, primește 400.
"business-central""sap-b1"export?Documentul ERP așa cum îl returnează ERP-ul. Câmpurile pe care maparea nu le citește sunt ignorate.
mapping_version?mapping_versionO versiune de mapare a acelui conector. Cea activă, când lipsește; una necunoscută primește 400.
^v[0-9]+$client?stringClientul căruia îi aparține factura. Cheia operatorului îl numește (dacă lipsește, factura aparține propriului client local al operatorului). O cheie de client poate să îl omită sau să îl numească pe al său; orice alt client primește 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringID-ul propriu al documentului în ERP. Reluat în fiecare eveniment de stare.
length <= 100route?|Dacă lipsește sau este null, routerul îl alege din document: country al vânzătorului, buyer.address.country al cumpărătorului, profile, datele de autentificare stocate ale clientului și, când o regulă
are nevoie, înregistrarea cumpărătorului în Peppol. Când nicio regulă nu se potrivește, răspunsul este 422 cu EI-ROUTE-UNDECIDED sau
EI-ROUTE-PEPPOL-UNKNOWN (sursa router). POST /validate îl cere în continuare.
environment?stringTrebuie să corespundă mediului cheii API; dat explicit ca măsură de siguranță.
"sandbox""production"document*O factură în modelul canonic. Semnificația câmpurilor urmează modelul semantic EN 16931. Totalurile nu fac parte din model: serviciul le calculează din linii.
formats?array<>Ce documente se produc acolo unde canalul permite o alegere (Germania: xrechnung-ubl,
xrechnung-cii sau zugferd; Franța: ubl, cii sau facturx). Valorile implicite pe canal se stabilesc la integrare.
La POST /invoices numiți cel mult unul: este documentul care este generat, verificat și trimis (primul din fiecare
listă de mai sus, când lipsește). Peppol și România primesc ubl, Polonia fa3. O altă valoare sau mai mult de una
primește 400. Factur-X și ZUGFeRD sunt verificate de două ori: CII-ul din interior cu regulile canalului, apoi PDF-ul.
Pe canalul german, un document fără profile este generat ca XRechnung.
erp_totals?Totalurile calculate de ERP. Serviciul le calculează pe ale sale din linii și refuză factura (422, EI-TOTALS-MISMATCH, cu numele câmpului ERP) dacă diferă, în loc să trimită un document cu care ERP-ul nu este de acord. Un conector le citește chiar din export; totalurile numite aici au prioritate.
Acceptată pentru procesare. Urmăriți-o cu legăturile returnate sau așteptați evenimentele de stare.
application/json- response
id*stringstate*InvoiceStateStarea proprie a serviciului pentru o factură. Evenimentele de stare raportează ciclul de viață vizibil partenerului;
queued și submitting sunt pași interni între validated și submitted. validation_failed înseamnă că regulile oficiale au refuzat documentul; începând cu
0.18.4, o verificare care nu a rulat (KOSIT-RUN, EI-PDF-CHECK) se reîncearcă, apoi se încheie ca dead_letter cu acel
cod. Un dead_letter își păstrează documentul reținut, deci același fișier primește răspuns cu duplicate_of; începând cu 0.18.6, operatorul
poate anula una pentru care nu s-a făcut niciun apel către canal, iar apoi fișierul poate fi trimis din nou.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Setat când același document a fost deja acceptat pentru acest client și canal; nu se trimite nimic nou. O transmitere care s-a încheiat ca rejected, validation_failed sau cancelled nu contează, deci fișierul poate fi trimis din nou. Începând cu 0.18.5 acest lucru este valabil și pentru două cereri trimise în același moment, sub chei diferite; una creează factura, iar cealaltă răspunde cu duplicate_of.
links*route?RouteDoar când routerul a ales canalul.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Doar când cererea a omis canalul.
"router"route_rule?stringRegula routerului care a ales canalul; scrisă și în jurnalul de audit ca 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"}Enumerați și căutați facturi GET
O cheie de client vede facturile propriului client; operatorul le vede pe ale tuturor clienților sau pe ale unui client, cu client. Rândurile conțin ce conține GET /invoices/{id}, fără documents, și niciun conținut al facturii: fără cumpărător sau sume, și fără data emiterii (pentru România și Polonia, deadline_at rezultă din ea, cu o abatere de câteva zile). Un parametru necunoscut primește 400.
Transmiteți un document UBL sau CII finalizat (transmitere directă) POST
Pentru ERP-urile care scriu deja UBL sau CII, sau FA(3) pentru canalul KSeF. Nu are loc nicio mapare: serviciul rulează validatoarele oficiale ale canalului (pentru FA(3): XSD plus regulile KSeF pentru fișier și dată) și trimite fișierul neschimbat. Un PDF Factur-X sau ZUGFeRD trece prin același punct final ca application/pdf. XML-ul este analizat cu entitățile, DTD-urile și accesul la rețea dezactivate, iar un fișier cu DOCTYPE este refuzat (EI-XML-DTD) înainte ca vreun validator să îl citească, la fel ca un fișier care nu este bine format (EI-XML-SYNTAX) sau nu este o factură pe care canalul o cunoaște (EI-XML-TYPE). Începând cu 0.18.4, același fișier trimis din nou pentru același client și canal este factura deja păstrată (duplicate_of), ca la POST /invoices; nu se trimite nimic nou.