Verzie mapovania
Ako sa názvy polí ERP menia na našu faktúru a ako sa menia verzie.
- V sandboxe
Jednoducho povedané
Mapovanie prekladá názvy polí jedného ERP do nášho modelu faktúry, a preto chyba dokáže pomenovať pole vo vlastnom exporte klienta. Keď sa názvy polí klienta zmenia, pridáme novú verziu a starú ponecháme, aby sme sa mohli vrátiť. Business Central a SAP Business One sú namapované, každý podľa zverejneného tvaru ERP a zatiaľ nie podľa exportu klienta.
Mapovanie premení jeden export z ERP na našu kanonickú faktúru. Keď sa názvy polí klienta zmenia, pridáme novú verziu a presunieme aktívny ukazovateľ. Stará verzia zostáva, takže ukazovateľ sa môže presunúť späť.
Čo existuje dnes
Namapované sú dva ERP: Business Central (predajná faktúra API v2.0) a SAP Business One (faktúra alebo dobropis tak, ako ich vráti Service Layer). Každý má aktívnu verziu a staršie verzie zostávajú.
Poznámka
Obe mapovania boli napísané podľa zverejneného tvaru ERP a otestované na vymyslených exportoch, pretože zatiaľ neexistuje žiadny export klienta. Klient, ktorého export používa iné názvy, dostane novú verziu. Nič z toho od klienta nevyžaduje, aby menil ERP.
Export ide na POST /validate alebo POST /invoices, s connector a export namiesto document.
Odoslanie exportu
POST /validate prijíma connector (business-central alebo sap-b1) a export (objekt exportu) namiesto document; POST /invoices prijíma tie isté dve polia. Polia, ktoré mapovanie nepozná, sa ignorujú. Protokol v mapping_version uvádza, ktorá verzia bežala. Požiadavka je validate-export-ok.json, export s vymyslenými stranami.
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @validate-export-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-export-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-export-ok.json'),
});
console.log(response.status);
console.log(await response.text());{
"valid": true,
"route": "DE-XRECHNUNG",
"documents": [
{
"sha256": "3e7f648bdc6c6d6f5ad78cd356b39c3020595bb7f0896b78a8510ec6969db317",
"kind": "xrechnung-ubl",
"content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi... (5,900 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"
}
],
"mapping_version": "v2"
}Vyskúšanie inej verzie
mapping_version v požiadavke zvolí verziu pre dané volanie. Ukazovateľ sa nepresunie. Pre verziu, ktorá neexistuje, je odpoveď 400. Požiadavka je validate-export-bad-version.json, ten istý export s "mapping_version": "v9".
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @validate-export-bad-version.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-export-bad-version.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-export-bad-version.json'),
});
console.log(response.status);
console.log(await response.text());{
"detail": "That mapping version does not exist. The live pointer was left unchanged.",
"type": "https://eurinvoice.com/problems/bad-request",
"title": "The request could not be read",
"status": 400
}Nájdenie poľa v ERP
Zistenie pomenuje pole ERP, nie naše kanonické pole. Jednotku, ktorú mapovanie nepozná, opravujeme my: pridáme ju do tabuľky jednotiek a vydáme novú verziu. Požiadavka je validate-export-bad-unit.json, v ktorej Kiste nie je v tabuľke.
curl -X POST "https://api-sandbox-eu.eurinvoice.com/validate" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
--data-binary @validate-export-bad-unit.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-export-bad-unit.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-export-bad-unit.json'),
});
console.log(response.status);
console.log(await response.text());{
"valid": false,
"route": "DE-XRECHNUNG",
"layers": [
{
"findings": [],
"passed": true,
"layer": "schema"
},
{
"findings": [
{
"code": "BR-CL-23",
"field": "salesInvoiceLines[0].unitOfMeasureCode",
"fix_hint": "Add the ERP's unit to the client's unit mapping table (for example 'Std.' to HUR).",
"who_fixes": "us",
"source": "mapping",
"message": "A unit of measure on a line is not recognised. We are adding it to your mapping."
}
],
"passed": false,
"layer": "mapping"
},
{
"findings": [],
"passed": true,
"layer": "pre-check"
}
],
"mapping_version": "v2"
}Chýbajúce údaje opravuje partner. Ich zistenie má who_fixes nastavené na erp a pomenuje pole ERP, ktoré treba doplniť.
Ako sa zmena nasadzuje
- Aktívnu verziu skopírujeme do novej verzie a zmeníme ju. Stará zostáva.
- Vzorové exporty klienta pošleme s
mapping_versionnastaveným na novú verziu, kým stará zostáva aktívna. - Aktívny ukazovateľ presunieme na novú verziu.
- Ak je niečo zle, presunieme ho späť.