3 API3.4
3.4
Leggere una fattura, i suoi eventi, i suoi documenti
Leggere una fattura, i suoi eventi e i suoi documenti.
- Nella sandbox
In parole semplici
Queste chiamate mostrano a che punto è una fattura, ogni evento della sua storia e i file archiviati per essa.
Quattro chiamate di lettura seguono una fattura dopo il 202. Tutte richiedono una chiave con lo scope read. Per un id che non esiste, o che appartiene a un altro cliente, la risposta è 404.
La fattura
GET /invoices/{id} restituisce lo stato attuale della fattura.
| Campo | Significato |
|---|---|
id, invoice_ref, invoice_number | Il nostro id, l’id del documento nell’ERP e il numero della fattura. |
route, environment, client | Il canale, l’ambiente e l’identificativo del cliente (local quando non ne è stato indicato nessuno). |
state | queued, submitted, ready, cancelled e così via. Stati elenca entrambi i livelli. |
legal_id | Il riferimento proprio del canale, una volta che l’infrastruttura ha la fattura: il numero KSeF, l’indice di caricamento ANAF, l’id del documento dell’access point o l’id della fattura della piattaforma francese. |
document_sha256 | SHA-256 di ciò che è stato archiviato. |
attempts | Invii precedenti della stessa invoice_ref, per esempio dopo uno scarto e una correzione. |
deadline_at | Una scadenza indicativa, solo per Romania e Polonia, e solo se la fattura riporta una data di emissione. Non è mai anteriore a quella reale e non è una consulenza legale. |
created_at, updated_at | Timestamp RFC 3339 in UTC. |
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"invoice_ref": "CAPTURE-JSON-1790961440",
"environment": "sandbox",
"document_sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc",
"route": "DE-XRECHNUNG",
"updated_at": "2026-10-06T19:49:02.676Z",
"documents": [
{
"sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc",
"kind": "canonical",
"href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/canonical"
},
{
"sha256": "ad122fe72dc6f04b2de6b6bbc01fcb7e46e33116b12e3bbb02a569cde3f10106",
"kind": "manifest",
"href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/manifest"
},
{
"sha256": "941fd5005aa03586a7bf23f3039c6d15e38220879d46690f9199a494e35fdc11",
"kind": "validation-report",
"href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/validation-report"
},
{
"sha256": "251a52fec3bdd44555a7396a1567d62c5ada3e3b7d002bb757d6b50e347c2e90",
"kind": "xrechnung-ubl",
"href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/xrechnung-ubl"
}
],
"client": "acme-srl",
"created_at": "2026-10-06T19:49:01.621Z",
"id": "inv_936a93e38de84e7b0a1d7681",
"state": "ready",
"invoice_number": "DOC-mux3dlqm"
}I suoi eventi
GET /invoices/{id}/events ripercorre ogni evento di stato della fattura, in ordine di sequence. Usarla per mettersi in pari dopo un’interruzione. Gli eventi non scadono finché il contratto è in vigore, e non c’è nulla da confermare.
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681/events" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681/events"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/inv_936a93e38de84e7b0a1d7681/events', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"data": [
{
"occurred_at": "2026-10-06T19:49:01.621Z",
"sequence": 1,
"environment": "sandbox",
"invoice_ref": "CAPTURE-JSON-1790961440",
"document_sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc",
"event_id": "evt_e1b58da963c46e4a63409006",
"country_route": "DE-XRECHNUNG",
"invoice_number": "DOC-mux3dlqm",
"status": "received"
},
{
"occurred_at": "2026-10-06T19:49:02.661Z",
"sequence": 2,
"environment": "sandbox",
"invoice_ref": "CAPTURE-JSON-1790961440",
"document_sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc",
"event_id": "evt_0dcb4d0b797e93185b22c27d",
"country_route": "DE-XRECHNUNG",
"invoice_number": "DOC-mux3dlqm",
"status": "validated"
}
]
}Tutte le fatture
GET /invoices elenca e cerca le fatture di un cliente, dalla più recente, una pagina alla volta. Filtra per q (parte di invoice_ref o del numero), route, state e giorno di ricezione (received_from, received_to). Una riga contiene ciò che contiene GET /invoices/{id}, senza i documenti e senza il contenuto della fattura: nessun acquirente, nessun importo e nessuna data di emissione. GET /invoices/series conta le fatture ricevute e scartate per ogni giorno e canale, per un grafico. Vedere il riferimento.
I suoi documenti
GET /invoices/{id}/documents/{kind} restituisce ciò che il servizio ha archiviato. Il tipo è uno dei seguenti:
| Tipo | Archiviato quando |
|---|---|
canonical | È stato inviato un JSON. Il file è la fattura così come è stata inviata. |
erp-export | È stato inviato un export dell’ERP. Il file è l’export così come l’ERP l’ha inviato. |
ubl, cii, fa3, pdf | Il file così come è stato inviato, oppure il documento costruito dal servizio: xrechnung-ubl per la Germania, ubl o fa3 per gli altri canali. |
validation-report | Cosa ha rilevato ogni controllo. |
manifest | Lo SHA-256 dei byte che vanno al canale e i controlli eseguiti su di essi. |
I tipi JSON vengono serviti come application/json.
ETag è lo SHA-256 del file. I documenti si possono leggere solo con la chiave. Non ci sono link pubblici. Una simulazione non archivia nulla.
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_1721a979f65d8ff80ef5f64b/documents/ubl" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/inv_1721a979f65d8ff80ef5f64b/documents/ubl"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/inv_1721a979f65d8ff80ef5f64b/documents/ubl', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"><cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID><cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID><cbc:ID>RE-2026-0142</cbc:ID><cbc:IssueDate>2026-09-26</cbc:IssueDate><cbc:DueDate>2026-10-10</cbc:DueDate><cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode><cbc:Note>Vielen Dank für Ihren Auftrag.</cbc:Note><cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode><cbc:BuyerReference>PO-88731</cbc:BuyerReference><cac:InvoicePeriod><cbc:StartDate>2026-09-01</cbc:StartDate><cbc:EndDate>2026-09-30</cbc:EndDate></cac:InvoicePeriod><cac:AccountingSupplierParty><cac:Party><cbc:EndpointID schemeID="9930">DE123456789</cbc:EndpointID><cac:PostalAddress><cbc:StreetName>Hafenstraße 12</cbc:StreetName><cbc:CityName>Hamburg</cbc:CityName><cbc:PostalZone>20457</cbc:PostalZone><cac:Country><cbc:IdentificationCode>DE</cbc:IdentificationCode></cac:Country></cac:PostalAddress><cac:PartyTaxScheme><cbc:CompanyID>DE123456789</cbc:CompanyID><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:PartyTaxScheme><cac:PartyLegalEntity><cbc:RegistrationName>Nordlicht Software GmbH</cbc:RegistrationName><cbc:CompanyID>HRB 123456</cbc:CompanyID><cbc:CompanyLegalForm>GmbH</cbc:CompanyLegalForm></cac:PartyLegalEntity><cac:Contact><cbc:Name>Jana Petersen</cbc:Name><cbc:Telephone>+49 40 1234567</cbc:Telephone><cbc:ElectronicMail>rechnung@nordlicht.example</cbc:ElectronicMail></cac:Contact></cac:Party></cac:AccountingSupplierParty><cac:AccountingCustomerParty><cac:Party><cbc:EndpointID schemeID="9930">DE987654321</cbc:EndpointID><cac:PostalAddress><cbc:StreetName>Marienplatz 4</cbc:StreetName><cbc:CityName>München</cbc:CityName><cbc:PostalZone>80331</cbc:PostalZone><cac:Country><cbc:IdentificationCode>DE</cbc:IdentificationCode></cac:Country></cac:PostalAddress><cac:PartyTaxScheme><cbc:CompanyID>DE987654321</cbc:CompanyID><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:PartyTaxScheme><cac:PartyLegalEntity><cbc:RegistrationName>Brauhaus Weber AG</cbc:RegistrationName></cac:PartyLegalEntity></cac:Party></cac:AccountingCustomerParty><cac:PaymentMeans><cbc:PaymentMeansCode>58</cbc:PaymentMeansCode><cbc:PaymentID>RE-2026-0142</cbc:PaymentID><cac:PayeeFinancialAccount><cbc:ID>DE89370400440532013000</cbc:ID><cbc:Name>Nordlicht Software GmbH</cbc:Name><cac:FinancialInstitutionBranch><cbc:ID>COBADEFFXXX</cbc:ID></cac:FinancialInstitutionBranch></cac:PayeeFinancialAccount></cac:PaymentMeans><cac:PaymentTerms><cbc:Note>Zahlbar innerhalb von 14 Tagen ohne Abzug.</cbc:Note></cac:PaymentTerms><cac:TaxTotal><cbc:TaxAmount currencyID="EUR">1255.71</cbc:TaxAmount><cac:TaxSubtotal><cbc:TaxableAmount currencyID="EUR">6609.00</cbc:TaxableAmount><cbc:TaxAmount currencyID="EUR">1255.71</cbc:TaxAmount><cac:TaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19.00</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:TaxCategory></cac:TaxSubtotal></cac:TaxTotal><cac:LegalMonetaryTotal><cbc:LineExtensionAmount currencyID="EUR">6609.00</cbc:LineExtensionAmount><cbc:TaxExclusiveAmount currencyID="EUR">6609.00</cbc:TaxExclusiveAmount><cbc:TaxInclusiveAmount currencyID="EUR">7864.71</cbc:TaxInclusiveAmount><cbc:PayableAmount currencyID="EUR">7864.71</cbc:PayableAmount></cac:LegalMonetaryTotal><cac:InvoiceLine><cbc:ID>1</cbc:ID><cbc:InvoicedQuantity unitCode="LS">1</cbc:InvoicedQuantity><cbc:LineExtensionAmount currencyID="EUR">5900.00</cbc:LineExtensionAmount><cac:Item><cbc:Description>Mapping Business Central → EN 16931, Validierung XRechnung, Test im Peppol-Testnetz</cbc:Description><cbc:Name>E-Rechnung Einführung (Festpreis)</cbc:Name><cac:ClassifiedTaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19.00</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:ClassifiedTaxCategory></cac:Item><cac:Price><cbc:PriceAmount currencyID="EUR">5900.00</cbc:PriceAmount></cac:Price></cac:InvoiceLine><cac:InvoiceLine><cbc:ID>2</cbc:ID><cbc:InvoicedQuantity unitCode="MON">1</cbc:InvoicedQuantity><cbc:LineExtensionAmount currencyID="EUR">349.00</cbc:LineExtensionAmount><cac:Item><cbc:Description>Care Plus, September 2026</cbc:Description><cbc:Name>Betreuung abgelehnter Rechnungen</cbc:Name><cac:ClassifiedTaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19.00</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:ClassifiedTaxCategory></cac:Item><cac:Price><cbc:PriceAmount currencyID="EUR">349.00</cbc:PriceAmount></cac:Price></cac:InvoiceLine><cac:InvoiceLine><cbc:ID>3</cbc:ID><cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity><cbc:LineExtensionAmount currencyID="EUR">360.00</cbc:LineExtensionAmount><cac:Item><cbc:Description>Remote, Buchhaltungsteam</cbc:Description><cbc:Name>Zusätzliche Schulung</cbc:Name><cac:ClassifiedTaxCategory><cbc:ID>S</cbc:ID><cbc:Percent>19.00</cbc:Percent><cac:TaxScheme><cbc:ID>VAT</cbc:ID></cac:TaxScheme></cac:ClassifiedTaxCategory></cac:Item><cac:Price><cbc:PriceAmount currencyID="EUR">120.00</cbc:PriceAmount></cac:Price></cac:InvoiceLine></Invoice>
<!-- shortened for these docs -->Risposte
| Stato | Significato |
|---|---|
200 | La fattura, i suoi eventi o il file. |
401 | Nessuna chiave, o una chiave sconosciuta. |
403 | La chiave non ha lo scope read. |
404 | Questa fattura non esiste per questo cliente, oppure non ha un documento di quel tipo. |
429 | Troppe richieste per la chiave. Attendere Retry-After secondi. |
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"type": "https://eurinvoice.com/problems/not-found",
"title": "No such resource for this client",
"status": 404
}