Docs
5

Chyby a katalóg

Problem JSON a všetky kódy katalógu.

  • V sandboxe

Jednoducho povedané

Keď volanie zlyhá, odpoveď uvedie, či je chybná požiadavka, alebo faktúra. Pri faktúre kód pomenuje pole v exporte klienta a uvedie, kto ho opraví. Partner opravuje chybné požiadavky a chybné údaje; my opravujeme vlastné mapovanie a opakujeme pokusy pri zlyhaniach na strane kanála.

Tip

400 sa týka formátu požiadavky na naše API. 422 sa týka faktúry a jej kód z katalógu pomenuje pole v exporte z ERP. Tieto dva prípady rozlišujte.

Problem JSON

Každá chybová odpoveď je vo formáte problem JSON (RFC 9457): type, title a status, s detail, keď je čo dodať. 422 pridáva errors, zoznam zistení. Každé má code z katalógu, kto ho opraví (who_fixes), fix_hint a message, a field, keď sa zistenie týka jedného poľa (pozri stranu 3.2). Zvýraznený riadok je kód.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: order-2026-0051" \
  --data-binary @not-an-invoice.xml
Odpoveď422 Unprocessable Content
{
  "type": "https://eurinvoice.com/problems/validation-failed",
  "title": "The invoice did not pass the checks",
  "errors": [
    {
      "code": "EI-XML-TYPE",
      "fix_hint": "Send the invoice itself, in the format agreed for the route.",
      "who_fixes": "erp",
      "source": "XML-safety",
      "message": "The file is not an invoice in a format this route accepts. Please send the invoice in the agreed format."
    }
  ],
  "status": 422
}
Zaznamenané 7. okt. 2026. Správne utvorené XML, ktoré nie je faktúrou. Celé volanie je na strane 3.3.

Pre cestu, ktorú služba nemá, je odpoveď 404 s obyčajným JSON {"detail": "Not Found"}.

Čo znamená každý stav

StavVýznamČo urobíte
400Požiadavku nemožno prečítať: nie je to JSON, niektoré pole je nesprávne alebo Idempotency-Key chýba či nemá 8 až 100 znakov.Opravte požiadavku.
401Chýba kľúč alebo je neznámy.Opravte kľúč.
403Kľúču chýba oprávnenie, ktoré volanie potrebuje, alebo sa volanie týka údajov iného klienta (forbidden).Použite kľúč s oprávnením alebo správneho klienta.
404Pre tohto klienta taká faktúra, dokument, položka katalógu ani položka zoznamu na riešenie neexistuje.Skontrolujte ID.
409Idempotency-Key bol použitý s iným telom alebo jeho prvá požiadavka ešte beží. Zrušenie prišlo príliš neskoro. Prístupové údaje už existujú alebo boli odvolané.Opravte volanie.
413Telo má viac ako 5 MB (payload-too-large).Pošlite menší súbor.
415Typ obsahu nie je XML ani PDF alebo telo PDF nie je PDF.Opravte typ obsahu.
422Faktúra neprešla kontrolou. Nič sa nezaradilo do frontu.Opravte zistenia označené erp. Tie označené us sú naše.
429Príliš veľa požiadaviek pre kľúč.Počkajte počet sekúnd z Retry-After a skúste znova.
500Faktúru nebolo možné skontrolovať. Niečo zlyhalo na našej strane.Zopakujte to isté volanie s rovnakým kľúčom.
503Služba je zaneprázdnená (busy) alebo volanie pre prístupové údaje prišlo na proces bez nastaveného hlavného kľúča.Zopakujte to isté volanie po Retry-After sekundách.

Každá odpoveď 409 má vlastný type problému pod https://eurinvoice.com/problems/: idempotency-conflict, request-in-progress, already-submitted, send-in-progress, dead-letter, credential-exists a credential-revoked. Na ich rozlíšenie čítajte type, nie title. 413 sa neukladá k Idempotency-Key, takže rovnaký kľúč možno znova použiť s menším telom.

429 prichádza pre každého klienta a oprávnenie s Retry-After (pozri limity). Po 202 už faktúru nikdy znova neposielate. Chyby na strane siete, ktoré sa môžu pominúť, opakujeme podľa nášho plánu a trvalé odmietnutie ide do zoznamu na riešenie.

Kto má konať

Každý kód v katalógu má jednu zodpovednú stranu.

ZodpovedáKto to je
erpPartner: export z ERP alebo jeho kmeňové údaje.
useurinvoice: mapovanie, serializátor alebo konfigurácia.
businessFirma predávajúceho spolu so svojím kupujúcim alebo účtovníkom.
clientKlient, teda predávajúci: registrácia, prístupové údaje alebo autorizácia.
buyerStrana kupujúceho.
routePrevádzkovateľ kanála, teda úrad, prístupový bod alebo platforma: počkajte a skúste znova.

Partner opravuje 400, 401, 403, 409, 413 a 415. 422 obsahuje zistenia a každé uvádza, kto ho opraví: erp je partner, us je eurinvoice.

Katalóg

Katalóg obsahuje kód pre každé zistenie. Táto stránka ukazuje vzorku dvanástich, jeden alebo dva pre každú skupinu pravidiel. Napíšte kód a stlačením klávesu Enter naň prejdete. S kľúčom vysvetlí ľubovoľný kód GET /catalogue/{code} (pozri vyhľadanie v katalógu). Úplný katalóg je pre partnerov: vyžiadajte si ho s prístupom do sandboxu.

KódKto konáČo je zleČo robiť
EI-ID-IBANNaše kontroly, kontrola identifikátoraPartnerIBAN neprejde kontrolou mod-97.Opravte bankový účet v nastaveniach spoločnosti.
EI-SCHEMANaše kontroly, schémaeurinvoiceJSON faktúry nezodpovedá kanonickému modelu: chýbajúce alebo neznáme pole, nesprávny typ alebo kód, prípadne pravidlo kanála týkajúce sa štruktúry.Prečítajte si cestu JSON v chybe a opravte mapovanie klienta.
EI-TOTALS-MISMATCHNaše kontroly, predbežná kontrolaPartnerSúčty, ktoré poslal ERP (erp_totals), sa líšia od súčtov vypočítaných z riadkov, takže dokument by nezodpovedal vlastnému účtovníctvu ERP.Nájdite rozdiel (zvyčajne zaokrúhľovanie po riadkoch oproti zaokrúhľovaniu za celý doklad alebo riadok so zľavou, ktorý export vynechal) a opravte export alebo mapovanie.
BR-CO-16EN 16931 a syntax, validátor kanálaeurinvoiceSuma na úhradu (BT-115) sa nerovná celkovej sume s DPH (BT-112) mínus uhradená suma (BT-113) plus zaokrúhlenie (BT-114).Súčty počítame z riadkov, takže toto sa objaví, len keď súčty prišli zvonka (súbor odovzdaný bez úprav) alebo boli upravené. Prepočítajte súčty z riadkov a faktúru odošlite znova.
EI-XML-DTDEN 16931 a syntax, validátor kanálaPartnerXML deklaruje DOCTYPE. UBL, CII ani FA(3) ho nikdy nepoužívajú a práve cez DOCTYPE sa do súboru dostávajú externé entity, načítanie vzdialených DTD a rozvíjanie entít (XXE). Súbor sa odmietne skôr, než ho prečíta akýkoľvek validátor alebo kanál.Exportujte faktúru bez riadka DOCTYPE. Ak ho ERP pridáva zámerne, riešte to s dodávateľom ERP: žiadny formát elektronickej fakturácie ho nepoužíva.
EI-XML-SYNTAXEN 16931 a syntax, validátor kanálaPartnerSúbor nie je správne utvorené XML: je napríklad useknutý, jeho kódovanie nezodpovedá deklarácii alebo znak ako & nie je escapovaný. Žiadny validátor ho nedokáže prečítať.Exportujte súbor znova a otvorte ho v ľubovoľnom prehliadači XML. Hľadajte useknutý súbor, kódovanie, ktoré sa líši od deklarácie, alebo neescapovaný znak &.
EI-XML-TYPEEN 16931 a syntax, validátor kanálaPartnerXML je správne utvorené, ale nie je faktúrou, ktorú validujeme: nie je to UBL Invoice ani CreditNote, faktúra UN/CEFACT CII ani faktúra KSeF FA(3) (napríklad UBL Order alebo starší súbor FA(2)).Pošlite samotnú faktúru vo formáte dohodnutom pre kanál.
EI-PEPPOL-NO-ROUTEPeppol, odpoveď siete, vyžaduje volanie sietePartnerPrístupový bod nenašiel pre identifikátor kupujúceho žiadneho príjemcu: kupujúci nie je v sieti Peppol registrovaný pre tento typ dokumentu. Pre toto odoslanie je to konečný stav.Porovnajte Peppol ID kupujúceho v zázname zákazníka v ERP s adresárom Peppol; ak kupujúci nie je v sieti Peppol, dohodnite si s ním iný spôsob doručenia.
PEPPOL-EN16931-R001Peppol, validátor kanálaeurinvoiceObchodný proces (BT-23) by mal byť uvedený. Mustang to nahlásil ako oznámenie pri našom súbore ZUGFeRD EN 16931, ktorý nie je dokumentom Peppol.Pri ZUGFeRD netreba nič robiť; naše Peppol UBL proces vždy zapisuje.
BR-DE-5Nemecko, validátor kanálaPartnerChýba meno kontaktnej osoby predávajúceho (BT-41).Doplňte do nastavení spoločnosti kontaktnú osobu alebo oddelenie pre fakturáciu.
KSEF-440Poľsko, odpoveď siete, vyžaduje volanie sieteeurinvoiceKSeF už má faktúru s rovnakým NIP predávajúceho, typom faktúry (RodzajFaktury) a číslom (P_2); tento kľúč uchováva 10 rokov. Kľúčom je číslo, nie súbor: v prostredí TEST dostal 440 aj iný súbor pod už akceptovaným číslom. Odpoveď uvádza číslo KSeF a reláciu kópie, ktorú akceptoval ako prvú. Číslo, ktoré KSeF odmietol (430 alebo 450), sa neuchováva a možno ho použiť znova.Neodosielajte znova. Zaznamenajte pôvodné číslo KSeF z odpovede a vykážte faktúru ako akceptovanú pod týmto číslom.
BR-RO-001Rumunsko, validátor kanálaeurinvoiceIdentifikátor špecifikácie (BT-24) nemá hodnotu CIUS-RO.Nastavte profil ro-cius, ktorý zapíše identifikátor CIUS-RO 1.0.1.

Na tejto stránke