3 API3.1
3.1
Skúšobný beh: POST /validate
Spustí rovnaké kontroly ako podanie. Nič neukladá ani neodosiela.
- V sandboxe
Jednoducho povedané
Skúšobný beh skontroluje faktúru tak, ako by to urobilo skutočné podanie, a nič neodošle, takže partner môže nájsť každý problém skôr, než faktúra klienta niekam odíde.
POST /validate spustí rovnaké kontroly ako podanie a odpovie protokolom. Nič nezaradí do frontu a nič neodošle. Volanie vyžaduje kľúč s oprávnením submit. Telo je JSON s veľkosťou najviac 5 MB.
Tip
Začnite tu, keď mapujete nového klienta.
Požiadavka
| Pole | Význam |
|---|---|
invoice_ref | Povinné. Vlastné ID dokladu v ERP, najviac 100 znakov. Vracia sa v každej stavovej udalosti. |
route | Povinné. DE-XRECHNUNG, PEPPOL, FR-PA, PL-KSEF alebo RO-EFACTURA. |
document | Jedna faktúra v kanonickom modeli. Pošlite buď toto, alebo export, nie oboje. |
export, connector | Export z ERP tak, ako ho ERP napísalo, s connector nastaveným na business-central alebo sap-b1. Pošlite buď toto, alebo document, nie oboje. Pri inom kanáli než nemeckom začína protokol vrstvou mapping. mapping_version zvolí inú verziu, než je aktívna (pozri verzie mapovania). |
formats | Dokumenty, ktoré sa majú zostaviť, kde kanál dovoľuje výber. Nemecko: ľubovoľné z xrechnung-ubl (predvolené), xrechnung-cii a zugferd; KoSIT sa spustí raz pre každý formát a pri PDF sa navyše spustia Mustang a veraPDF. Francúzsko: ubl, cii alebo facturx. |
environment | Voliteľné. Musí zodpovedať prostrediu vášho kľúča. |
erp_totals | Súčty, ktoré vypočítal váš ERP: payable_amount, currency a voliteľne tax_amount, ako reťazce. Ak sa líšia od súčtov, ktoré služba vypočíta z riadkov, protokol obsahuje zistenie EI-TOTALS-MISMATCH pre erp_totals.payable_amount. |
Úplný zoznam polí je v referenčnej dokumentácii.
Faktúra, ktorá prejde
Vzorová požiadavka je validate-de-ok.json, vymyslená nemecká faktúra. Protokol obsahuje valid: true, jeden dokument s jeho SHA-256 a štyri vrstvy, ktoré prešli.
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"
}
]
}Faktúra, ktorá neprejde
Tá istá faktúra bez názvu predávajúceho, validate-de-missing-seller-name.json. Skúšobný beh aj tak odpovie 200. valid je false a každé zistenie pomenuje pole a uvedie, kto ho opraví. Pozrite sa na dva zvýraznené riadky: code z katalógu a field v údajoch klienta.
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"
}
]
}Ako čítať protokol
validjetruelen vtedy, keď prešli všetky vrstvy.layerssa spúšťajú v poradí:schema,mapping,pre-checka potom vlastné validátory kanála, pomenované podľa toho, čo bežalo (napríkladKoSIT-XRechnung-3.0.2).- Každé zistenie má
codez katalógu,field,who_fixes(usaleboerp),fix_hint,messagea vrstvusource. Stránka Chyby a katalóg uvádza všetky kódy. documentsuvádza, čo sa vytvorilo, spolu s jeho SHA-256 a pri súbore do 2 MiB aj s jeho bajtmi vcontent_base64. Je prítomné, keď je faktúra platná.
Ďalšie odpovede
| Stav | Význam |
|---|---|
200 | Protokol, či už platný, alebo nie. |
400 | Požiadavku nemožno prečítať: nie je to JSON, niektoré pole je nesprávne alebo sú prítomné document aj export. |
401 | Chýba kľúč alebo je neznámy. |
403 | Kľúč nemá oprávnenie submit. |
413 | Telo má viac ako 5 MB (payload-too-large). |
422 | Číslo mimo limitov, napríklad dlhšie ako 40 znakov (EI-SCHEMA s pomenovaním poľa). Každé ďalšie zistenie príde v protokole s 200. |
429 | Príliš veľa požiadaviek pre kľúč. Počkajte Retry-After sekúnd. |
503 | Všetky validátory sú zaneprázdnené (busy). Skúste znova po Retry-After sekundách. |
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
}