Podanie faktúry alebo dobropisu ako kanonického JSON
- V sandboxe
Jednoducho povedané
Služba hneď skontroluje dokument voči kanonickému modelu a predbežným kontrolám a pri zlyhaní ktorejkoľvek odpovie 422. Všetko ďalšie prebieha asynchrónne (zostavenie, oficiálna validácia, podanie na kanál, stavy) a oznamuje sa stavovými udalosťami.
Opravené opätovné podanie odmietnutej faktúry používa rovnaký invoice_ref a nový
Idempotency-Key; služba pokusy prepojí.
V produkcii sa export z ERP prečíta len vtedy, keď nastavenia konektora klienta obsahujú vlastného predávajúceho a platbu,
nie príklad z mapovania: inak odpovie 422 connector-settings-missing s uvedením, čo chýba. Sandbox ho číta
s príkladom, ako predtým.
apiKeyAuthorizationBearer <token>Kľúč posielajte ako token typu Bearer: Authorization: Bearer <your-api-key>. Stav služby je jediné volanie, ktoré nevyžaduje kľúč.
Idempotency-Key*stringJedinečný kľúč pre každú logickú požiadavku (postačí UUID). Uchováva sa tak dlho, ako sa uchovávajú údaje klienta. S kľúčom operátora nesmie začínať na client: (400), v takom tvare sa ukladajú kľúče klientov.
8 <= length <= 100application/json- body
Pošlite buď document (kanonická faktúra), alebo connector s export (jeden doklad ERP tak, ako ho vráti ERP),
nie oboje (400). Export sa mapuje živou verziou mapovania konektora alebo mapping_version a
potom sa spracuje presne ako kanonická faktúra, na ktorú sa premapuje; samotný export sa uchováva s faktúrou
(erp-export). Profil XRechnung konektora sa uplatní len na DE-XRECHNUNG a keď smerovač vyberá
pre nemeckého kupujúceho. Zistenie z mapovania (neznáma jednotka, chýbajúce pole ERP) odpovie 422 s uvedením poľa ERP.
connector?connectorZ ktorého ERP export pochádza. business-central: jedna predajná faktúra Business Central API v2.0. Iný objekt SAP, napríklad objednávka alebo koncept, odpovie 400.
"business-central""sap-b1"export?Doklad ERP tak, ako ho vráti ERP. Polia, ktoré mapovanie nečíta, sa ignorujú.
mapping_version?mapping_versionVerzia mapovania tohto konektora. Ak sa vynechá, živá; neznáma odpovie 400.
^v[0-9]+$client?stringKlient, ktorému faktúra patrí. Uvádza ho kľúč operátora (ak sa vynechá, faktúra patrí vlastnému klientovi operátora local). Kľúč klienta ho môže vynechať alebo uviesť vlastného klienta; každý iný klient odpovie 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringVlastné ID dokladu v ERP. Opakuje sa v každej stavovej udalosti.
length <= 100route?|Ak sa vynechá alebo je null, smerovač ho vyberie z dokumentu: z country predávajúceho,
buyer.address.country kupujúceho, profile, uložených prístupových údajov klienta a, ak to
pravidlo potrebuje, z registrácie kupujúceho v Peppole. Keď nesedí žiadne pravidlo, odpoveďou je 422 s EI-ROUTE-UNDECIDED alebo
EI-ROUTE-PEPPOL-UNKNOWN (zdroj router). POST /validate ho stále potrebuje.
environment?stringMusí zodpovedať prostrediu kľúča API; uvedené výslovne ako poistka.
"sandbox""production"document*Jedna faktúra v kanonickom modeli. Význam polí vychádza zo sémantického modelu EN 16931. Súčty nie sú súčasťou modelu: služba ich vypočíta z riadkov.
formats?array<>Ktoré dokumenty vytvoriť tam, kde kanál dovoľuje výber (Nemecko: xrechnung-ubl,
xrechnung-cii alebo zugferd; Francúzsko: ubl, cii alebo facturx). Predvolené hodnoty pre kanál sa nastavujú pri zaškolení.
Pri POST /invoices uveďte najviac jeden: je to dokument, ktorý sa zostaví, skontroluje a odošle (ak sa vynechá, prvý
z uvedených zoznamov). Peppol a Rumunsko berú ubl, Poľsko fa3. Iná hodnota alebo viac ako jedna
odpovie 400. Factur-X a ZUGFeRD sa kontrolujú dvakrát: najprv CII vo vnútri podľa pravidiel kanála, potom PDF.
Na nemeckom kanáli sa dokument bez profile zostaví ako XRechnung.
erp_totals?Súčty, ktoré vypočítalo ERP. Služba počíta vlastné z riadkov a faktúru odmietne (422, EI-TOTALS-MISMATCH s uvedením poľa ERP), ak sa líšia, namiesto odoslania dokumentu, s ktorým ERP nesúhlasí. Konektor ich číta zo samotného exportu; súčty uvedené tu majú prednosť.
Prijaté na spracovanie. Sledujte ho podľa vrátených odkazov alebo počkajte na stavové udalosti.
application/json- response
id*stringstate*InvoiceStateVlastný stav služby pre faktúru. Stavové udalosti hlásia životný cyklus viditeľný pre partnera;
queued a submitting sú vnútorné kroky medzi validated a submitted. validation_failed znamená, že oficiálne pravidlá dokument odmietli; od
0.18.4 sa kontrola, ktorá sa nespustila (KOSIT-RUN, EI-PDF-CHECK), opakuje a potom skončí ako dead_letter s týmto
kódom. dead_letter drží svoj dokument, takže ten istý súbor odpovie s duplicate_of; od 0.18.6 môže
operátor zrušiť faktúru, pre ktorú sa neuskutočnilo žiadne volanie kanála, a potom môže súbor ísť znova.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Nastavené, keď sa ten istý dokument pre tohto klienta a kanál už prijal; nič nové sa neodošle. Podanie, ktoré skončilo ako rejected, validation_failed alebo cancelled, sa nepočíta, takže súbor možno poslať znova. Od 0.18.5 to platí aj pre dve požiadavky poslané v tom istom okamihu pod rôznymi kľúčmi; jedna faktúru vytvorí a druhá odpovie s duplicate_of.
links*route?RouteLen keď kanál vybral smerovač.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Len keď požiadavka kanál vynechala.
"router"route_rule?stringPravidlo smerovača, ktoré kanál vybralo; zapisuje sa aj do auditného záznamu ako 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"}Zobrazenie a vyhľadávanie faktúr GET
Kľúč klienta vidí faktúry vlastného klienta; operátor vidí faktúry všetkých klientov alebo jedného klienta cez client. Riadky nesú to, čo nesie GET /invoices/{id}, bez documents, a žiadny obsah faktúry: bez kupujúceho a súm a bez dátumu vystavenia (pre Rumunsko a Poľsko z neho vyplýva deadline_at, s presnosťou na niekoľko dní). Neznámy parameter odpovie 400.
Podanie hotového dokumentu UBL alebo CII (priame odovzdanie) POST
Pre ERP, ktoré už zapisujú UBL alebo CII, alebo FA(3) pre kanál KSeF. Nič sa nemapuje: služba spustí oficiálne validátory kanála (pre FA(3): XSD plus pravidlá súboru a dátumu KSeF) a odošle súbor nezmenený. PDF Factur-X alebo ZUGFeRD prejde tým istým koncovým bodom ako application/pdf. XML sa číta s vypnutými entitami, DTD a prístupom do siete, a súbor s DOCTYPE sa odmietne (EI-XML-DTD) skôr, než ho prečíta ktorýkoľvek validátor, rovnako ako súbor, ktorý nie je správne utvorený (EI-XML-SYNTAX) alebo nie je faktúrou, ktorú kanál pozná (EI-XML-TYPE). Od 0.18.4 je ten istý súbor poslaný znova pre klienta a kanál už držanou faktúrou (duplicate_of), ako pri POST /invoices; nič nové sa neodošle.