Predaj račun ili odobrenje kao kanonski JSON
- U sandboxu
Jednostavnim riječima
Usluga odmah provjerava dokument prema kanonskom modelu i preliminarnim provjerama te odgovara 422 ako jedna od njih ne prođe. Sve nakon toga radi asinkrono (izrada, službena validacija, predaja kanalu, statusi) i prijavljuje se statusnim događajima.
Ispravljeno ponovno slanje odbijenog računa koristi isti invoice_ref i novi
Idempotency-Key; usluga povezuje pokušaje.
U produkciji se izvoz iz ERP-a čita samo kada postavke konektora klijenta sadrže vlastitog prodavatelja i plaćanje,
a ne primjer iz mapiranja: inače 422 connector-settings-missing, uz navod što nedostaje. Sandbox ga čita
s primjerom, kao i prije.
apiKeyAuthorizationBearer <token>Ključ pošaljite kao bearer token: Authorization: Bearer <your-api-key>. Poziv za stanje usluge jedini je poziv za koji nije potreban ključ.
Idempotency-Key*stringJedinstveni ključ za svaki logički zahtjev (UUID je dovoljan). Čuva se onoliko dugo koliko se čuvaju podaci klijenta. S ključem operatera ne smije počinjati s client: (400), oblikom pod kojim se spremaju ključevi klijenata.
8 <= length <= 100application/json- body
Pošaljite ili document (kanonski račun) ili connector s export (jedan ERP dokument onako kako ga ERP vraća),
ne oboje (400). Izvoz se mapira aktivnom verzijom mapiranja konektora ili mapping_version, a
zatim se obrađuje točno kao kanonski račun u koji se mapira; sam izvoz pohranjuje se uz račun
(erp-export). XRechnung profil konektora primjenjuje se samo na DE-XRECHNUNG, i kada usmjerivač bira za
njemačkog kupca. Nalaz mapiranja (nepoznata jedinica, nedostajuće ERP polje) vraća 422 uz naziv ERP polja.
connector?connectorIz kojeg ERP-a izvoz dolazi. business-central: jedan prodajni račun Business Central API-ja v2.0. Drugi SAP objekt, poput narudžbe ili nacrta, vraća 400.
"business-central""sap-b1"export?ERP dokument onako kako ga ERP vraća. Polja koja mapiranje ne čita zanemaruju se.
mapping_version?mapping_versionVerzija mapiranja tog konektora. Aktivna kada je izostavljena; nepoznata vraća 400.
^v[0-9]+$client?stringKlijent kojemu račun pripada. Navodi ga ključ operatera (ako je izostavljen, račun pripada operaterovu vlastitom klijentu local). Ključ klijenta može ga izostaviti ili navesti svojeg klijenta; svaki drugi klijent vraća 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringVlastiti ID dokumenta u ERP-u. Ponavlja se u svakom statusnom događaju.
length <= 100route?|Ako je izostavljen ili null, kanal bira usmjerivač iz dokumenta: country prodavatelja,
buyer.address.country kupca, profile, pohranjeni pristupni podaci klijenta i, kada ga pravilo
treba, Peppol registracija kupca. Kada nijedno pravilo ne odgovara, odgovor je 422 s EI-ROUTE-UNDECIDED ili
EI-ROUTE-PEPPOL-UNKNOWN (izvor router). POST /validate ga i dalje traži.
environment?stringMora odgovarati okruženju API ključa; navodi se izričito kao zaštita.
"sandbox""production"document*Jedan račun u kanonskom modelu. Značenja polja slijede semantički model EN 16931. Ukupni iznosi nisu dio modela: usluga ih izračunava iz stavki.
formats?array<>Koje dokumente izraditi gdje kanal dopušta izbor (Njemačka: xrechnung-ubl,
xrechnung-cii ili zugferd; Francuska: ubl, cii ili facturx). Zadane vrijednosti po kanalu postavljaju se pri uvođenju.
Na POST /invoices navedite najviše jedan: to je dokument koji se izrađuje, provjerava i šalje (prvi na svakom
popisu gore kada je izostavljen). Peppol i Rumunjska uzimaju ubl, Poljska fa3. Druga vrijednost ili više njih
vraća 400. Factur-X i ZUGFeRD provjeravaju se dvaput: CII unutra prema pravilima kanala, zatim PDF.
Na njemačkom kanalu dokument bez profile izrađuje se kao XRechnung.
erp_totals?Ukupni iznosi koje je izračunao ERP. Usluga izračunava vlastite iz stavki i odbija račun (422, EI-TOTALS-MISMATCH, uz naziv ERP polja) ako se razlikuju, umjesto da pošalje dokument s kojim se ERP ne slaže. Konektor ih čita iz samog izvoza; ovdje navedeni iznosi imaju prednost.
Prihvaćeno na obradu. Pratite ga vraćenim poveznicama ili pričekajte statusne događaje.
application/json- response
id*stringstate*InvoiceStateVlastito stanje usluge za račun. Statusni događaji prijavljuju životni ciklus vidljiv partneru;
queued i submitting unutarnji su koraci između validated i submitted. validation_failed znači da su službena pravila odbila dokument; od
0.18.4 provjera koja nije pokrenuta (KOSIT-RUN, EI-PDF-CHECK) ponavlja se, a zatim završava kao dead_letter s tom
šifrom. dead_letter zadržava svoj dokument, pa ista datoteka dobiva odgovor s duplicate_of; od 0.18.6
operater može otkazati onaj za koji nije upućen nijedan poziv kanalu, i tada datoteka može ponovno ići.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Postavljeno kada je isti dokument već prihvaćen za ovog klijenta i kanal; ništa novo se ne šalje. Predaja koja je završila kao rejected, validation_failed ili cancelled ne računa se, pa se datoteka može ponovno poslati. Od 0.18.5 to vrijedi i za dva zahtjeva poslana u isti trenutak, pod različitim ključevima; jedan izrađuje račun, a drugi odgovara s duplicate_of.
links*route?RouteSamo kada je kanal odabrao usmjerivač.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Samo kada je zahtjev izostavio kanal.
"router"route_rule?stringPravilo usmjerivača koje je odabralo kanal; zapisuje se i u revizijski dnevnik kao 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": "rechnung@nordlicht.example", "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"}Popis i pretraga računa GET
Ključ klijenta vidi račune svojeg klijenta; operater vidi račune svih klijenata ili jednog klijenta pomoću client. Retci nose ono što nosi GET /invoices/{id}, bez documents, i bez sadržaja računa: bez kupca ili iznosa, i bez datuma izdavanja (za Rumunjsku i Poljsku iz njega proizlazi deadline_at, s točnošću od nekoliko dana). Nepoznati parametar vraća 400.
Predaj gotov UBL ili CII dokument (prosljeđivanje) POST
Za ERP-ove koji već pišu UBL ili CII, ili FA(3) za kanal KSeF. Mapiranja nema: usluga pokreće službene validatore kanala (za FA(3): XSD plus KSeF-ova pravila o datoteci i datumu) i šalje datoteku nepromijenjenu. PDF Factur-X ili ZUGFeRD ide kroz istu krajnju točku kao application/pdf. XML se obrađuje s isključenim entitetima, DTD-ovima i pristupom mreži, a datoteka s DOCTYPE-om odbija se (EI-XML-DTD) prije nego je pročita bilo koji validator, kao i datoteka koja nije ispravno oblikovana (EI-XML-SYNTAX) ili nije račun koji kanal poznaje (EI-XML-TYPE). Od 0.18.4 ista datoteka poslana ponovno za klijenta i kanal jest račun koji već postoji (duplicate_of), kao na POST /invoices; ništa se novo ne šalje.