3 API3.4
3.4
Čítanie faktúry, jej udalostí a dokumentov
Čítanie faktúry, jej udalostí a dokumentov.
- V sandboxe
Jednoducho povedané
Tieto volania ukážu, v akom stave je faktúra, každú udalosť v jej histórii a súbory, ktoré sú k nej uložené.
Po 202 sledujú faktúru štyri čítania. Všetky vyžadujú kľúč s oprávnením read. Pre ID, ktoré neexistuje alebo patrí inému klientovi, je odpoveď 404.
Faktúra
GET /invoices/{id} vráti aktuálny stav faktúry.
| Pole | Význam |
|---|---|
id, invoice_ref, invoice_number | Naše ID, ID dokladu v ERP a číslo faktúry. |
route, environment, client | Kanál, prostredie a identifikátor klienta (local, ak žiadny nebol uvedený). |
state | queued, submitted, ready, cancelled a podobne. Stránka Stavy uvádza obe vrstvy. |
legal_id | Vlastná referencia kanála, keď už sieť faktúru má: číslo KSeF, index nahratia ANAF, ID dokumentu prístupového bodu alebo ID faktúry francúzskej platformy. |
document_sha256 | SHA-256 toho, čo bolo uložené. |
attempts | Skoršie podania tej istej invoice_ref, napríklad po zamietnutí a oprave. |
deadline_at | Orientačná lehota, len pre Rumunsko a Poľsko a len keď faktúra nesie dátum vystavenia. Nikdy nie je skôr ako skutočná a nie je to právna rada. |
created_at, updated_at | Časové pečiatky RFC 3339 v 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"
}Jej udalosti
GET /invoices/{id}/events znova prehrá každú stavovú udalosť faktúry v poradí podľa sequence. Použite ho na dobehnutie zmien po výpadku. Udalosti počas trvania zmluvy nevypršia a nič sa nemusí potvrdzovať.
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"
}
]
}Všetky faktúry
GET /invoices vypíše a vyhľadá faktúry klienta, od najnovších, po stránkach. Filtruje podľa q (časť invoice_ref alebo čísla), route, state a dňa prijatia (received_from, received_to). Riadok obsahuje to, čo GET /invoices/{id}, bez dokumentov a bez obsahu faktúry: bez kupujúceho, bez súm a bez dátumu vystavenia. GET /invoices/series spočíta prijaté a zamietnuté faktúry za každý deň a kanál, pre graf. Pozri referenčnú dokumentáciu.
Jej dokumenty
GET /invoices/{id}/documents/{kind} vráti to, čo služba uložila. Druh je jeden z týchto:
| Druh | Kedy sa ukladá |
|---|---|
canonical | Keď ste podali JSON. Súbor je faktúra tak, ako ste ju poslali. |
erp-export | Keď ste podali export z ERP. Súbor je export tak, ako ho ERP poslalo. |
ubl, cii, fa3, pdf | Súbor tak, ako bol poslaný, alebo dokument, ktorý služba zostavila: xrechnung-ubl pre Nemecko, ubl alebo fa3 pre ostatné kanály. |
validation-report | Čo našla každá kontrola. |
manifest | SHA-256 bajtov, ktoré idú do kanála, a kontroly, ktoré nad nimi prebehli. |
Druhy JSON sa vracajú ako application/json.
ETag je SHA-256 súboru. Dokumenty sa dajú čítať len s kľúčom. Neexistujú žiadne verejné odkazy. Skúšobný beh nič neukladá.
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 -->Odpovede
| Stav | Význam |
|---|---|
200 | Faktúra, jej udalosti alebo súbor. |
401 | Chýba kľúč alebo je neznámy. |
403 | Kľúču chýba oprávnenie read. |
404 | Pre tohto klienta taká faktúra neexistuje alebo pri nej neexistuje taký druh dokumentu. |
429 | Príliš veľa požiadaviek pre kľúč. Počkajte Retry-After sekúnd. |
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
}