Scarti (fatture in errore)
Gli scarti definitivi e chi interviene.
- Nella sandbox
In parole semplici
L’elenco degli scarti contiene le fatture che un canale di trasmissione ha scartato in via definitiva o che hanno esaurito tutti i tentativi, con cosa non va e chi interviene. È lì che lavora il servizio mensile Gestione degli scarti (Rejection Care). Non inviamo mai di nuovo un file scartato così com’è: il cliente o il partner corregge i dati nell’ERP e viene inviata una fattura corretta.
Una fattura finisce nell’elenco degli scarti quando il canale la scarta in via definitiva, o quando gli errori temporanei esauriscono i tentativi. L’elenco dice cosa non va e chi interviene. Non inviamo mai di nuovo un file scartato così com’è: correggere i dati nell’ERP e inviare una fattura corretta. La Gestione degli scarti, il servizio mensile a canone, lavora a partire da queste tre chiamate. Il livello di servizio è nel contratto, non qui.
La chiave di un cliente con lo scope read legge le righe del proprio cliente. Contrassegnare una riga come gestita è compito della Gestione degli scarti, quindi la chiave di un cliente riceve 403 su quella chiamata.
L’elenco
GET /care restituisce una riga per fattura.
| Campo | Significato |
|---|---|
invoice_id | L’id della fattura. |
invoice_ref | Il riferimento proprio del partner. |
client, route | Il cliente e il canale della fattura. |
catalogue_code | Il codice che spiega lo scarto (vedere errori). |
who_acts | Il responsabile del codice: erp, us, business, client, buyer o route. |
field | Un punto del modello canonico, come invoice.buyer_reference. Mai un valore. |
fix_hint | Cosa modificare, tratto dallo scarto o dalla voce del catalogo. |
age_seconds | Da quanto tempo la fattura è nell’elenco. |
deadline_at | La scadenza indicativa della fattura, quando ne ha una (vedere leggere una fattura). |
handled | Se qualcuno l’ha contrassegnata come gestita. |
handled_at | Quando è stata contrassegnata. Presente solo quando handled vale true. |
Il parametro di query status sceglie open, handled o all (il predefinito). La chiave di un cliente riceve al massimo le 200 righe più recenti, e truncated: true indica quando ce ne sono altre. Può richiedere l’elenco 30 volte al minuto.
Nota
L’elenco non contiene il corpo della fattura, e nemmeno il log.
curl "https://api-sandbox-eu.eurinvoice.com/care" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/care"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/care', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"data": []
}Contrassegnare come gestita
POST /care/{id}/handled contrassegna una riga come gestita e risponde con quella riga. Chiamarla di nuovo mantiene il primo handled_at. Per una fattura che non è nell’elenco, la risposta è 404. Solo la chiave dell’operatore può chiamarla.
curl -X POST "https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/handled" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/handled"))
.header("Authorization", "Bearer <your-api-key>")
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/handled', {
method: 'POST',
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"type": "https://eurinvoice.com/problems/not-found",
"title": "This invoice is not on the care list",
"status": 404
}Esportare le evidenze
GET /care/{id}/evidence restituisce i file archiviati per la fattura: invoice_id e un elenco files, ciascuno con il suo kind, il suo sha256 e il file stesso come file_base64. Il file è l’originale archiviato, quindi il corpo si trova in questa risposta e non nell’elenco. Per una fattura che non è nell’elenco, la risposta è 404, e lo stesso vale per la fattura di un altro cliente. La chiave di un cliente con lo scope read può chiamarla 10 volte al minuto. Per file che superano 8 MiB in totale la risposta è 413 (evidence-too-large); leggerli uno per uno con GET /invoices/{id}/documents/{kind}.
curl "https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/evidence" \
-H "Authorization: Bearer <your-api-key>"import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/evidence"))
.header("Authorization", "Bearer <your-api-key>")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}const response = await fetch('https://api-sandbox-eu.eurinvoice.com/care/inv_unknown/evidence', {
headers: {
Authorization: 'Bearer <your-api-key>',
},
});
console.log(response.status);
console.log(await response.text());{
"type": "https://eurinvoice.com/problems/not-found",
"title": "This invoice is not on the care list",
"status": 404
}Risposte
| Stato | Significato |
|---|---|
200 | L’elenco, la riga contrassegnata o le evidenze. |
401 | Nessuna chiave, o una chiave sconosciuta. |
403 | La chiave non ha lo scope read, oppure la chiave di un cliente ha tentato di contrassegnare una riga come gestita. |
404 | La fattura non è nell’elenco degli scarti. |
413 | Le evidenze superano 8 MiB in totale (evidence-too-large). |
429 | Troppe richieste per la chiave. Attendere Retry-After secondi. |