3 API3.1
3.1
Probna provjera: POST /validate
Izvodi iste provjere kao predaja. Ništa ne sprema i ništa ne šalje.
- U sandboxu
Jednostavnim riječima
Probna provjera provjerava račun jednako kao stvarna predaja i ništa ne šalje, pa partner može pronaći svaki problem prije nego što račun klijenta ikamo ode.
POST /validate izvodi iste provjere kao predaja i odgovara izvješćem. Ništa ne stavlja u red čekanja i ništa ne šalje. Za poziv je potreban ključ s opsegom submit. Tijelo je JSON, do 5 MB.
Savjet
Počnite ovdje kad mapirate novog klijenta.
Zahtjev
| Polje | Značenje |
|---|---|
invoice_ref | Obavezno. Vlastiti ID dokumenta u ERP-u, do 100 znakova. Ponavlja se u svakom statusnom događaju. |
route | Obavezno. DE-XRECHNUNG, PEPPOL, FR-PA, PL-KSEF ili RO-EFACTURA. |
document | Jedan račun u kanonskom modelu. Pošaljite ovo polje ili export, ali ne oba. |
export, connector | Izvoz iz ERP-a onakav kakav ga je ERP napisao, uz connector postavljen na business-central ili sap-b1. Pošaljite ovo ili document, ali ne oba. Za kanal koji nije njemački izvješće počinje slojem mapping. mapping_version odabire verziju koja nije aktivna (pogledajte verzije mapiranja). |
formats | Dokumenti koje treba izraditi kad kanal dopušta izbor. Njemačka: bilo koji od formata xrechnung-ubl (zadano), xrechnung-cii i zugferd; KoSIT se pokreće jednom po formatu, a za PDF se pokreću i Mustang i veraPDF. Francuska: ubl, cii ili facturx. |
environment | Neobavezno. Mora odgovarati okruženju vašeg ključa. |
erp_totals | Ukupni iznosi koje je izračunao vaš ERP: payable_amount, currency i po želji tax_amount, kao nizovi znakova. Ako se razlikuju od ukupnih iznosa koje usluga izračuna iz stavki, izvješće sadrži nalaz EI-TOTALS-MISMATCH na polju erp_totals.payable_amount. |
Potpuni popis polja nalazi se u referenci.
Račun koji prolazi
Ogledni zahtjev je validate-de-ok.json, izmišljeni njemački račun. Izvješće sadrži valid: true, jedan dokument s njegovim SHA-256 i četiri sloja koja su prošla.
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @validate-de-ok.jsonimport 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/validate"))
.header("Authorization", "Bearer <your-api-key>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofFile(Path.of("validate-de-ok.json")))
.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/validate', {
method: 'POST',
headers: {
Authorization: 'Bearer <your-api-key>',
'Content-Type': 'application/json',
},
body: await readFile('validate-de-ok.json'),
});
console.log(response.status);
console.log(await response.text());{
"valid": true,
"route": "DE-XRECHNUNG",
"documents": [
{
"sha256": "e21ab9d5097022bea30bfa9f9fe0a4c7ca9afdbd672b0ce2f9150461db773625",
"kind": "xrechnung-ubl",
"content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi... (7,092 characters, shortened for these docs)"
}
],
"layers": [
{
"findings": [],
"passed": true,
"layer": "schema"
},
{
"findings": [],
"passed": true,
"layer": "mapping"
},
{
"findings": [],
"passed": true,
"layer": "pre-check"
},
{
"findings": [],
"passed": true,
"layer": "kosit"
}
]
}Račun koji ne prolazi
Isti račun bez naziva prodavatelja, validate-de-missing-seller-name.json. Probna provjera i dalje odgovara 200. valid je false, a svaki nalaz navodi polje i tko ga ispravlja. Pogledajte dva istaknuta retka: code iz kataloga i field u podacima klijenta.
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @validate-de-missing-seller-name.jsonimport 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/validate"))
.header("Authorization", "Bearer <your-api-key>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofFile(Path.of("validate-de-missing-seller-name.json")))
.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/validate', {
method: 'POST',
headers: {
Authorization: 'Bearer <your-api-key>',
'Content-Type': 'application/json',
},
body: await readFile('validate-de-missing-seller-name.json'),
});
console.log(response.status);
console.log(await response.text());{
"valid": false,
"route": "DE-XRECHNUNG",
"layers": [
{
"findings": [
{
"code": "EI-SCHEMA",
"field": "seller.name",
"related": [
{
"code": "Art.226(5)",
"source": "pre-check"
}
],
"fix_hint": "Read the JSON path in the error and correct the client mapping.",
"who_fixes": "us",
"source": "schema",
"message": "We could not read this invoice from your export. We are correcting our mapping; if a field is missing in the ERP we will tell you which one."
}
],
"passed": false,
"layer": "schema"
},
{
"findings": [],
"passed": true,
"layer": "mapping"
},
{
"findings": [
{
"code": "Art.226(5)",
"field": "seller.name",
"related": [
{
"code": "EI-SCHEMA",
"source": "schema"
}
],
"fix_hint": "Complete the party's name and address in the master data.",
"who_fixes": "erp",
"source": "pre-check",
"message": "A company name or street address is missing. Complete the company or customer record in the ERP."
}
],
"passed": false,
"layer": "pre-check"
}
]
}Čitanje izvješća
validjetruesamo kad su prošli svi slojevi.layersse izvode redom:schema,mapping,pre-check, zatim vlastiti validatori kanala, nazvani prema onome što se pokrenulo (na primjerKoSIT-XRechnung-3.0.2).- Svaki nalaz ima
codeiz kataloga,field,who_fixes(usilierp),fix_hint,messagei slojsource. Stranica Pogreške i katalog navodi sve šifre. documentsnavodi što je izrađeno, s pripadajućim SHA-256 i, za datoteku do 2 MiB, njezinim bajtovima ucontent_base64. Prisutno je kad je račun valjan.
Drugi odgovori
| Status | Značenje |
|---|---|
200 | Izvješće, valjano ili ne. |
400 | Zahtjev se ne može pročitati: nije JSON, neko polje nije ispravno ili su prisutni i document i export. |
401 | Nema ključa ili je ključ nepoznat. |
403 | Ključ nema opseg submit. |
413 | Tijelo je veće od 5 MB (payload-too-large). |
422 | Broj izvan ograničenja, na primjer dulji od 40 znakova (EI-SCHEMA, uz navod polja). Svi ostali nalazi dolaze u izvješću s odgovorom 200. |
429 | Previše zahtjeva za ključ. Pričekajte onoliko sekundi koliko navodi Retry-After. |
503 | Svi su validatori zauzeti (busy). Pokušajte ponovno nakon onoliko sekundi koliko navodi Retry-After. |
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @not-json.txtimport 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/validate"))
.header("Authorization", "Bearer <your-api-key>")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofFile(Path.of("not-json.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/validate', {
method: 'POST',
headers: {
Authorization: 'Bearer <your-api-key>',
'Content-Type': 'application/json',
},
body: await readFile('not-json.txt'),
});
console.log(response.status);
console.log(await response.text());{
"detail": "The request is not valid JSON.",
"type": "https://eurinvoice.com/problems/bad-request",
"title": "The request could not be read",
"status": 400
}