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.xmlimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051"))
.header("Authorization", "Bearer <your-api-key>")
.header("Content-Type", "application/xml")
.header("Idempotency-Key", "order-2026-0051")
.POST(HttpRequest.BodyPublishers.ofFile(Path.of("not-an-invoice.xml")))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}import { readFile } from 'node:fs/promises';
const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051', {
method: 'POST',
headers: {
Authorization: 'Bearer <your-api-key>',
'Content-Type': 'application/xml',
'Idempotency-Key': 'order-2026-0051',
},
body: await readFile('not-an-invoice.xml'),
});
console.log(response.status);
console.log(await response.text());{
"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
}Pre cestu, ktorú služba nemá, je odpoveď 404 s obyčajným JSON {"detail": "Not Found"}.
Čo znamená každý stav
| Stav | Význam | Čo urobíte |
|---|---|---|
400 | Pož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. |
401 | Chýba kľúč alebo je neznámy. | Opravte kľúč. |
403 | Kľúč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. |
404 | Pre tohto klienta taká faktúra, dokument, položka katalógu ani položka zoznamu na riešenie neexistuje. | Skontrolujte ID. |
409 | Idempotency-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. |
413 | Telo má viac ako 5 MB (payload-too-large). | Pošlite menší súbor. |
415 | Typ obsahu nie je XML ani PDF alebo telo PDF nie je PDF. | Opravte typ obsahu. |
422 | Faktúra neprešla kontrolou. Nič sa nezaradilo do frontu. | Opravte zistenia označené erp. Tie označené us sú naše. |
429 | Príliš veľa požiadaviek pre kľúč. | Počkajte počet sekúnd z Retry-After a skúste znova. |
500 | Faktúru nebolo možné skontrolovať. Niečo zlyhalo na našej strane. | Zopakujte to isté volanie s rovnakým kľúčom. |
503 | Služ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 |
|---|---|
erp | Partner: export z ERP alebo jeho kmeňové údaje. |
us | eurinvoice: mapovanie, serializátor alebo konfigurácia. |
business | Firma predávajúceho spolu so svojím kupujúcim alebo účtovníkom. |
client | Klient, teda predávajúci: registrácia, prístupové údaje alebo autorizácia. |
buyer | Strana kupujúceho. |
route | Prevá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.
12 kódov
| Kód | Kto koná | Čo je zle | Čo robiť |
|---|---|---|---|
EI-ID-IBANNaše kontroly, kontrola identifikátora | Partner | IBAN neprejde kontrolou mod-97. | Opravte bankový účet v nastaveniach spoločnosti. |
EI-SCHEMANaše kontroly, schéma | eurinvoice | JSON 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á kontrola | Partner | Súč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ála | eurinvoice | Suma 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ála | Partner | XML 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ála | Partner | Sú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ála | Partner | XML 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 siete | Partner | Prí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ála | eurinvoice | Obchodný 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ála | Partner | Chý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 siete | eurinvoice | KSeF 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ála | eurinvoice | Identifikátor špecifikácie (BT-24) nemá hodnotu CIUS-RO. | Nastavte profil ro-cius, ktorý zapíše identifikátor CIUS-RO 1.0.1. |