Inviare XML: POST /invoices/xml | Documentazione eurinvoice

In parole semplici

Questa chiamata invia una fattura che esiste già come file XML pronto. Il file riceve un controllo di sicurezza e i validatori propri del canale, e va in coda se li supera.

POST /invoices/xml accetta un file UBL, CII o FA(3) già pronto. Non avviene alcuna mappatura. Il servizio controlla la sicurezza e il tipo del file, esegue i validatori ufficiali del canale, poi lo mette in coda e lo invia senza modifiche. Per FA(3) i controlli sono lo schema più le regole di KSeF sul file e sulle date.

Nota

Un 202 significa che il file ha superato il controllo di sicurezza ed è in coda. Per controllare un file prima di inviarlo, inviare la fattura come JSON a POST /validate.

La richiesta

Parte	Significato
Parametro di query `route`	Obbligatorio. Uno dei cinque canali.
Parametro di query `invoice_ref`	Obbligatorio. L’id del documento nell’ERP, fino a 100 caratteri.
Parametro di query `client`	Facoltativo. La chiave propria di un cliente può ometterlo o indicare il proprio cliente.
Intestazione `Idempotency-Key`	Obbligatoria, da 8 a 100 caratteri.
Intestazione `Content-Type`	`application/xml` o `text/xml`. `application/pdf` viene archiviato e messo in coda allo stesso modo.

Quale file accetta ciascun canale:

Canale	Accetta
`DE-XRECHNUNG`	UBL, CII
`FR-PA`	UBL, CII
`PEPPOL`	UBL
`RO-EFACTURA`	UBL
`PL-KSEF`	FA(3)

Un file accettato

L’esempio è fa3-pl-ksef.xml, un file FA(3) polacco con parti inventate. Lo stato è queued.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PL-KSEF&invoice_ref=INV-2026-0042" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: order-2026-0042" \
  --data-binary @fa3-pl-ksef.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=PL-KSEF&invoice_ref=INV-2026-0042"))
            .header("Authorization", "Bearer <your-api-key>")
            .header("Content-Type", "application/xml")
            .header("Idempotency-Key", "order-2026-0042")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("fa3-pl-ksef.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=PL-KSEF&invoice_ref=INV-2026-0042', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <your-api-key>',
    'Content-Type': 'application/xml',
    'Idempotency-Key': 'order-2026-0042',
  },
  body: await readFile('fa3-pl-ksef.xml'),
});
console.log(response.status);
console.log(await response.text());

Risposta202 Accepted

{
  "links": {
    "self": "/invoices/inv_d249e33382ce2911876b7295",
    "events": "/invoices/inv_d249e33382ce2911876b7295/events"
  },
  "id": "inv_d249e33382ce2911876b7295",
  "state": "queued"
}

Registrato il 7 ott. 2026.

Un file inviato due volte

Lo stesso file inviato di nuovo per lo stesso cliente e lo stesso canale è la fattura già presente. La risposta riporta duplicate_of, l’id della prima fattura, e non viene inviato nulla di nuovo. Un invio terminato come rejected, validation_failed o cancelled non conta, quindi il file può essere inviato di nuovo.

File rifiutati

Un XML ben formato che non è una fattura riceve 422 con EI-XML-TYPE.

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());

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

Registrato il 7 ott. 2026. Il file è [not-an-invoice.xml](/samples/not-an-invoice.xml).

Un file con un DOCTYPE riceve 422 con EI-XML-DTD, prima che un validatore lo legga. Un file non ben formato riceve EI-XML-SYNTAX.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0052" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: order-2026-0052" \
  --data-binary @with-doctype.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-0052"))
            .header("Authorization", "Bearer <your-api-key>")
            .header("Content-Type", "application/xml")
            .header("Idempotency-Key", "order-2026-0052")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("with-doctype.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-0052', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <your-api-key>',
    'Content-Type': 'application/xml',
    'Idempotency-Key': 'order-2026-0052',
  },
  body: await readFile('with-doctype.xml'),
});
console.log(response.status);
console.log(await response.text());

Risposta422 Unprocessable Content

{
  "type": "https://eurinvoice.com/problems/validation-failed",
  "title": "The invoice did not pass the checks",
  "errors": [
    {
      "code": "EI-XML-DTD",
      "fix_hint": "Export the invoice without the DOCTYPE line. If the ERP adds one on purpose, raise it with the ERP vendor: no e-invoicing format uses it.",
      "who_fixes": "erp",
      "source": "XML-safety",
      "message": "The invoice file contains a DOCTYPE declaration, which e-invoices never use, so we refused it for security before reading it. Export it again without the DOCTYPE line."
    }
  ],
  "status": 422
}

Registrato il 7 ott. 2026. Il file è [with-doctype.xml](/samples/with-doctype.xml).

Un tipo di contenuto che non è XML o PDF riceve 415.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0053" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/plain" \
  -H "Idempotency-Key: order-2026-0053" \
  --data-binary @hello.txt
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-0053"))
            .header("Authorization", "Bearer <your-api-key>")
            .header("Content-Type", "text/plain")
            .header("Idempotency-Key", "order-2026-0053")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("hello.txt")))
            .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-0053', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <your-api-key>',
    'Content-Type': 'text/plain',
    'Idempotency-Key': 'order-2026-0053',
  },
  body: await readFile('hello.txt'),
});
console.log(response.status);
console.log(await response.text());

Risposta415 Unsupported Media Type

{
  "type": "https://eurinvoice.com/problems/unsupported-media",
  "title": "Not UBL, CII or FA(3)",
  "status": 415
}

Registrato il 7 ott. 2026.

Una Idempotency-Key mancante o troppo corta riceve 400.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0054" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/xml" \
  --data-binary @ubl-peppol.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-0054"))
            .header("Authorization", "Bearer <your-api-key>")
            .header("Content-Type", "application/xml")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("ubl-peppol.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-0054', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <your-api-key>',
    'Content-Type': 'application/xml',
  },
  body: await readFile('ubl-peppol.xml'),
});
console.log(response.status);
console.log(await response.text());

Risposta400 Bad Request

{
  "detail": "Idempotency-Key must be between 8 and 100 characters.",
  "type": "https://eurinvoice.com/problems/bad-request",
  "title": "The request could not be read",
  "status": 400
}

Registrato il 7 ott. 2026.

Risposte

Stato	Significato
`202`	Accettata e messa in coda. `Location` contiene l’URL della fattura.
`400`	Un parametro di query o la `Idempotency-Key` mancano o sono errati.
`401`	Nessuna chiave, o una chiave sconosciuta.
`403`	La chiave non ha lo scope `submit`, oppure indica un altro cliente (`forbidden`).
`409`	La chiave è stata usata con un corpo diverso (`idempotency-conflict`), oppure la sua prima richiesta è ancora in corso (`request-in-progress`).
`413`	Il corpo supera 5 MB (`payload-too-large`).
`415`	Il tipo di contenuto non è XML o PDF (`unsupported-media`).
`422`	Un file rifiutato: `EI-XML-DTD`, `EI-XML-SYNTAX` o `EI-XML-TYPE`.
`429`	Troppe richieste per la chiave. Attendere `Retry-After` secondi.
`503`	Un’altra richiesta per lo stesso documento è ancora in fase di archiviazione (`busy`). Riprovare dopo `Retry-After` secondi.

La richiestaCopia il link a questa sezione

Un file accettatoCopia il link a questa sezione

Un file inviato due volteCopia il link a questa sezione

File rifiutatiCopia il link a questa sezione

RisposteCopia il link a questa sezione

In questa pagina

La richiesta

Un file accettato

Un file inviato due volte

File rifiutati

Risposte