Wersje mapowania
Jak nazwy pól z ERP stają się naszą fakturą i jak zmieniają się wersje.
- W sandboxie
Prostymi słowami
Mapowanie przekłada nazwy pól jednego ERP na nasz model faktury i dzięki temu błąd może wskazać pole we własnym eksporcie klienta. Gdy nazwy pól klienta się zmieniają, dodajemy nową wersję i zachowujemy starą, aby można było do niej wrócić. Zmapowane są Business Central i SAP Business One, każde na podstawie opublikowanej struktury ERP, a jeszcze nie na podstawie własnego eksportu klienta.
Mapowanie zamienia eksport z jednego ERP na naszą fakturę kanoniczną. Gdy nazwy pól klienta się zmieniają, dodajemy nową wersję i przestawiamy wskaźnik aktywnej wersji. Stara wersja pozostaje, więc wskaźnik można przestawić z powrotem.
Co istnieje dziś
Zmapowane są dwa ERP: Business Central (faktura sprzedaży z API v2.0) i SAP Business One (faktura lub nota kredytowa w postaci, w jakiej zwraca ją Service Layer). Każde ma wersję aktywną, a starsze wersje pozostają.
Uwaga
Oba mapowania napisano na podstawie opublikowanej struktury ERP i przetestowano na fikcyjnych eksportach, bo eksport klienta jeszcze nie istnieje. Klient, którego eksport używa innych nazw, otrzymuje nową wersję. Nic tutaj nie wymaga od klienta zmiany w ERP.
Eksport trafia do POST /validate lub POST /invoices, z connector i export zamiast document.
Wysłanie eksportu
POST /validate przyjmuje connector (business-central lub sap-b1) i export (obiekt eksportu) zamiast document; POST /invoices przyjmuje te same dwa pola. Pola, których mapowanie nie zna, są pomijane. Raport podaje w mapping_version, która wersja została użyta. Przykładowe żądanie to validate-export-ok.json, eksport z fikcyjnymi stronami transakcji.
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"
}Wypróbowanie innej wersji
mapping_version w żądaniu wybiera wersję dla tego wywołania. Wskaźnik się nie przesuwa. Dla wersji, która nie istnieje, odpowiedzią jest 400. Przykładowe żądanie to validate-export-bad-version.json, ten sam eksport z "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
}Jak znaleźć pole w ERP
Ustalenie wskazuje pole ERP, a nie nasze pole kanoniczne. Jednostkę, której mapowanie nie zna, poprawiamy my: dodajemy ją do tabeli jednostek i tworzymy nową wersję. Przykładowe żądanie to validate-export-bad-unit.json, w którym Kiste nie występuje w tabeli.
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"
}Brakujące dane uzupełnia partner. Takie ustalenie ma who_fixes ustawione na erp i wskazuje pole ERP do uzupełnienia.
Jak wdrażana jest zmiana
- Kopiujemy wersję aktywną do nowej wersji i ją zmieniamy. Stara pozostaje.
- Wysyłamy przykładowe eksporty klienta z
mapping_versionustawionym na nową wersję, a stara pozostaje aktywna. - Przestawiamy wskaźnik aktywnej wersji na nową wersję.
- Jeśli coś jest nie tak, przestawiamy go z powrotem.