Przesłanie faktury lub noty kredytowej jako kanonicznego JSON
- W sandboxie
Prostymi słowami
Usługa od razu sprawdza dokument z modelem kanonicznym i kontrolami wstępnymi i odpowiada 422, jeśli któraś z nich się nie powiedzie. Wszystko, co dzieje się potem, przebiega asynchronicznie (budowanie, oficjalna walidacja, przesłanie do kanału, statusy) i jest zgłaszane zdarzeniami statusu.
Poprawione ponowne przesłanie odrzuconej faktury używa tego samego invoice_ref i nowego
Idempotency-Key; usługa łączy te próby.
Na produkcji eksport z ERP jest odczytywany tylko wtedy, gdy ustawienia konektora klienta zawierają jego własnego sprzedawcę i płatność,
a nie przykład z mapowania: w przeciwnym razie 422 connector-settings-missing ze wskazaniem, czego brakuje. Sandbox odczytuje go
z przykładem, jak dotąd.
apiKeyAuthorizationBearer <token>Klucz należy wysyłać jako token typu bearer: Authorization: Bearer <your-api-key>. Wywołanie stanu usługi jest jedynym, które nie wymaga klucza.
Idempotency-Key*stringUnikalny klucz dla każdego logicznego żądania (może to być UUID). Przechowywany tak długo, jak dane klienta. Klucz operatora nie może zaczynać się od client: (400), czyli od postaci, pod którą zapisywane są klucze klientów.
8 <= length <= 100application/json- body
Należy wysłać document (fakturę kanoniczną) albo connector z export (jeden dokument ERP w postaci zwróconej
przez ERP), nie oba naraz (400). Eksport jest mapowany według aktywnej wersji mapowania konektora lub mapping_version, a
potem obsługiwany dokładnie jak faktura kanoniczna, na którą jest mapowany; sam eksport jest przechowywany razem z fakturą
(erp-export). Profil XRechnung konektora obowiązuje tylko na DE-XRECHNUNG i wtedy, gdy router wybiera
dla niemieckiego nabywcy. Ustalenie z mapowania (nieznana jednostka, brakujące pole ERP) daje odpowiedź 422 ze wskazaniem pola ERP.
connector?connectorZ którego ERP pochodzi eksport. business-central: jedna faktura sprzedaży Business Central API v2.0. Inny obiekt SAP, na przykład zamówienie lub wersja robocza, daje odpowiedź 400.
"business-central""sap-b1"export?Dokument ERP w postaci zwróconej przez ERP. Pola, których mapowanie nie odczytuje, są pomijane.
mapping_version?mapping_versionWersja mapowania tego konektora. Aktywna, gdy pominięto; nieznana daje odpowiedź 400.
^v[0-9]+$client?stringKlient, do którego należy faktura. Podaje go klucz operatora (po pominięciu faktura należy do własnego klienta operatora local). Klucz klienta może go pominąć albo podać własnego klienta; każdy inny klient daje odpowiedź 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringWłasny identyfikator dokumentu w ERP. Powtarzany w każdym zdarzeniu statusu.
length <= 100route?|Pominięty lub null: router wybiera go na podstawie dokumentu: country sprzedawcy,
buyer.address.country nabywcy, profile, zapisanych danych dostępowych klienta oraz, gdy reguła
tego wymaga, rejestracji nabywcy w Peppol. Gdy żadna reguła nie pasuje, odpowiedzią jest 422 z EI-ROUTE-UNDECIDED lub
EI-ROUTE-PEPPOL-UNKNOWN (źródło router). POST /validate nadal go wymaga.
environment?stringMusi zgadzać się ze środowiskiem klucza API; podawane jawnie jako zabezpieczenie.
"sandbox""production"document*Jedna faktura w modelu kanonicznym. Znaczenie pól odpowiada modelowi semantycznemu EN 16931. Sumy nie są częścią modelu: usługa oblicza je z pozycji.
formats?array<>Które dokumenty wytworzyć tam, gdzie kanał pozwala na wybór (Niemcy: xrechnung-ubl,
xrechnung-cii lub zugferd; Francja: ubl, cii lub facturx). Wartości domyślne dla kanału są ustawiane przy wdrożeniu.
W POST /invoices należy podać najwyżej jeden: to jest dokument, który jest budowany, sprawdzany i wysyłany (pierwszy z każdej
powyższej listy, gdy pominięto). Peppol i Rumunia przyjmują ubl, Polska fa3. Inna wartość lub więcej niż jedna
daje odpowiedź 400. Factur-X i ZUGFeRD są sprawdzane dwukrotnie: najpierw CII w środku według reguł kanału, potem PDF.
W kanale niemieckim dokument bez profile jest budowany jako XRechnung.
erp_totals?Sumy obliczone przez ERP. Usługa oblicza własne z pozycji i odrzuca fakturę (422, EI-TOTALS-MISMATCH, ze wskazaniem pola ERP), jeśli się różnią, zamiast wysyłać dokument, z którym ERP się nie zgadza. Konektor odczytuje je z samego eksportu; sumy podane tutaj mają pierwszeństwo.
Przyjęte do przetworzenia. Należy śledzić je za pomocą zwróconych linków albo czekać na zdarzenia statusu.
application/json- response
id*stringstate*InvoiceStateWłasny stan usługi dla faktury. Zdarzenia statusu zgłaszają cykl życia widoczny dla partnera;
queued i submitting to kroki wewnętrzne między validated a submitted. validation_failed oznacza, że oficjalne reguły odrzuciły dokument; od
0.18.4 kontrola, która się nie uruchomiła (KOSIT-RUN, EI-PDF-CHECK), jest ponawiana, a potem kończy jako dead_letter z tym
kodem. dead_letter zatrzymuje swój dokument, więc ten sam plik dostaje odpowiedź z duplicate_of; od 0.18.6
operator może anulować taką fakturę, dla której nie wykonano wywołania do kanału, i wtedy plik może zostać wysłany ponownie.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Ustawione, gdy ten sam dokument został już przyjęty dla tego klienta i kanału; nic nowego nie jest wysyłane. Przesłanie, które zakończyło się jako rejected, validation_failed lub cancelled, nie liczy się, więc plik można wysłać ponownie. Od 0.18.5 dotyczy to także dwóch żądań wysłanych w tej samej chwili pod różnymi kluczami; jedno tworzy fakturę, a drugie odpowiada z duplicate_of.
links*route?RouteTylko gdy kanał wybrał router.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Tylko gdy żądanie pomijało kanał.
"router"route_rule?stringReguła routera, która wybrała kanał; zapisywana także w dzienniku audytu jako 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"}Lista i wyszukiwanie faktur GET
Klucz klienta widzi faktury własnego klienta; operator widzi faktury wszystkich klientów albo jednego klienta po podaniu client. Wiersze zawierają to, co GET /invoices/{id}, bez documents, i nie zawierają treści faktury: nie ma nabywcy ani kwot, ani daty wystawienia (dla Rumunii i Polski wynika z niej deadline_at, z dokładnością do kilku dni). Nieznany parametr daje odpowiedź 400.
Przesłanie gotowego dokumentu UBL lub CII (przekazanie bez zmian) POST
Dla ERP, które już zapisują UBL lub CII albo FA(3) dla kanału KSeF. Nie ma mapowania: usługa uruchamia oficjalne walidatory kanału (dla FA(3): XSD oraz reguły KSeF dotyczące pliku i dat) i wysyła plik bez zmian. PDF Factur-X lub ZUGFeRD trafia przez ten sam punkt końcowy jako application/pdf. XML jest parsowany z wyłączonymi encjami, DTD i dostępem do sieci, a plik z DOCTYPE jest odrzucany (EI-XML-DTD), zanim odczyta go jakikolwiek walidator, tak samo jak plik, który nie jest poprawnie sformułowany (EI-XML-SYNTAX) lub nie jest fakturą znaną kanałowi (EI-XML-TYPE). Od 0.18.4 ten sam plik wysłany ponownie dla tego samego klienta i kanału to faktura już przechowywana (duplicate_of), jak w POST /invoices; nic nowego nie jest wysyłane.