Errori e catalogo

Problem JSONCopia il link a questa sezione

Ogni risposta di errore è un problem JSON (RFC 9457): type, title e status, con detail quando c’è altro da dire. Un 422 aggiunge errors, un elenco di segnalazioni. Ognuna ha un code del catalogo, chi la corregge (who_fixes), un fix_hint e un message, e un field quando la segnalazione riguarda un solo campo (vedere la pagina 3.2). La riga evidenziata è il codice.

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
}

Per un percorso che il servizio non ha, la risposta è 404 con {"detail": "Not Found"}, in JSON semplice.

Cosa significa ogni statoCopia il link a questa sezione

Ogni 409 ha un proprio type nel problem JSON, sotto https://eurinvoice.com/problems/: idempotency-conflict, request-in-progress, already-submitted, send-in-progress, dead-letter, credential-exists e credential-revoked. Per distinguerli, leggere il type, non il title. Un 413 non viene associato alla Idempotency-Key, quindi la stessa chiave si può riutilizzare con un corpo più piccolo.

Un 429 arriva per cliente e per scope, con Retry-After (vedere limiti). Dopo un 202 non si reinvia mai. Gli errori lato infrastruttura che un nuovo tentativo può superare vengono ritentati secondo il nostro calendario, e uno scarto definitivo va nell’elenco degli scarti.

Chi intervieneCopia il link a questa sezione

Ogni codice del catalogo ha un solo responsabile.

Il partner corregge 400, 401, 403, 409, 413 e 415. Un 422 contiene segnalazioni, e ognuna dice chi la corregge: erp è il partner, us è eurinvoice.

Il catalogoCopia il link a questa sezione

Il catalogo contiene un codice per ogni segnalazione. Questa pagina ne mostra un campione di dodici, uno o due per ogni famiglia di regole. Digitare un codice e premere Invio per raggiungerlo. Con una chiave, GET /catalogue/{code} spiega qualsiasi codice (vedere consultazione del catalogo). Il catalogo completo è riservato ai partner: richiederlo con l’accesso alla sandbox.