Błędy i katalog

Problem JSONKopiuj link do tej sekcji

Każda odpowiedź z błędem ma format problem JSON (RFC 9457): type, title i status, oraz detail, gdy są dodatkowe informacje. 422 dodaje errors, listę ustaleń. Każde z nich ma code z katalogu, informację, kto ma dokonać poprawki (who_fixes), fix_hint i message, a także field, gdy ustalenie dotyczy jednego pola (zob. stronę 3.2). Wyróżniony wiersz to kod.

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

import 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
}

Dla ścieżki, której usługa nie obsługuje, odpowiedzią jest 404 z {"detail": "Not Found"} w postaci zwykłego JSON.

Co oznacza każdy statusKopiuj link do tej sekcji

Każda odpowiedź 409 ma własny type problemu, pod https://eurinvoice.com/problems/: idempotency-conflict, request-in-progress, already-submitted, send-in-progress, dead-letter, credential-exists i credential-revoked. Aby je rozróżnić, należy czytać type, a nie title. Odpowiedź 413 nie jest zapisywana pod danym Idempotency-Key, więc tego samego klucza można użyć ponownie z mniejszą treścią.

Odpowiedź 429 jest udzielana osobno dla każdego klienta i zakresu, z nagłówkiem Retry-After (zob. limity). Po 202 nigdy nie wysyła się faktury ponownie. Przy błędach po stronie sieci, które mogą ustąpić, ponawiamy wysyłkę według naszego harmonogramu, a trwałe odrzucenie trafia na listę do obsługi.

Kto reagujeKopiuj link do tej sekcji

Każdy kod z katalogu ma przypisany jeden podmiot.

Błędy 400, 401, 403, 409, 413 i 415 poprawia partner. 422 zawiera ustalenia, a każde z nich podaje, kto ma dokonać poprawki: erp to partner, us to eurinvoice.

KatalogKopiuj link do tej sekcji

Katalog zawiera kod dla każdego ustalenia. Ta strona pokazuje próbkę dwunastu, po jednym lub dwa dla każdej rodziny reguł. Aby przejść do kodu, należy go wpisać i nacisnąć Enter. Z kluczem GET /catalogue/{code} wyjaśnia dowolny kod (zob. wyszukiwanie w katalogu). Pełny katalog jest przeznaczony dla partnerów: można o niego poprosić przez dostęp do sandboxa.