Verzije mapiranja
Kako nazivi polja iz ERP-a postaju naš račun i kako se mijenjaju verzije.
- U sandboxu
Jednostavnim riječima
Mapiranje prevodi nazive polja jednog ERP-a u naš model računa, zahvaljujući čemu pogreška može navesti polje u klijentovu vlastitom izvozu. Kad se klijentovi nazivi polja promijene, dodajemo novu verziju i zadržavamo staru, kako bismo se mogli vratiti. Business Central i SAP Business One su mapirani, svaki prema objavljenom obliku ERP-a, a još ne prema klijentovu vlastitom izvozu.
Mapiranje pretvara jedan izvoz iz ERP-a u naš kanonski račun. Kad se klijentovi nazivi polja promijene, dodajemo novu verziju i pomičemo aktivni pokazivač. Stara verzija ostaje, pa se pokazivač može vratiti.
Što postoji danas
Mapirana su dva ERP-a: Business Central (prodajni račun API-ja v2.0) i SAP Business One (račun ili odobrenje onakvo kakvo ga vraća Service Layer). Svaki ima aktivnu verziju, a starije verzije ostaju.
Napomena
Oba mapiranja napisana su prema objavljenom obliku ERP-a i testirana na izmišljenim izvozima, jer još ne postoji nijedan izvoz klijenta. Klijent čiji izvoz koristi druge nazive dobiva novu verziju. Ništa ovdje ne traži od klijenta da mijenja ERP.
Izvoz se šalje na POST /validate ili POST /invoices, s connector i export umjesto document.
Slanje izvoza
POST /validate umjesto document prima connector (business-central ili sap-b1) i export (objekt izvoza); POST /invoices prima ista dva polja. Polja koja mapiranje ne poznaje zanemaruju se. Izvješće u polju mapping_version navodi koja se verzija pokrenula. Zahtjev je validate-export-ok.json, izvoz s izmišljenim stranama.
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"
}Isprobavanje druge verzije
mapping_version u zahtjevu odabire verziju za taj poziv. Pokazivač se ne pomiče. Verzija koja ne postoji daje odgovor 400. Zahtjev je validate-export-bad-version.json, isti izvoz 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
}Pronalaženje polja u ERP-u
Nalaz navodi polje iz ERP-a, a ne naše kanonsko polje. Mjernu jedinicu koju mapiranje ne poznaje ispravljamo mi: dodajemo je u tablicu jedinica i izrađujemo novu verziju. Zahtjev je validate-export-bad-unit.json, u kojem Kiste nije u tablici.
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"
}Podatke koji nedostaju ispravlja partner. Takav nalaz ima who_fixes postavljen na erp i navodi polje u ERP-u koje treba popuniti.
Kako se uvodi promjena
- Aktivnu verziju kopiramo u novu verziju i mijenjamo je. Stara ostaje.
- Ogledne izvoze klijenta šaljemo s
mapping_versionpostavljenim na novu verziju, dok stara ostaje aktivna. - Aktivni pokazivač pomičemo na novu verziju.
- Ako nešto nije u redu, vraćamo ga.