Opvolging (mislukte facturen)
Definitieve afwijzingen en wie ermee aan de slag gaat.
- In de sandbox
In gewone woorden
De opvolgingslijst bevat de facturen die een verzendkanaal definitief heeft afgewezen of waarvoor alle herhaalpogingen zijn mislukt, met wat er mis is en wie handelt. Met deze lijst werkt de maandelijkse opvolging van afwijzingen (Rejection Care). We versturen een afgewezen bestand nooit ongewijzigd opnieuw: de eindklant of de partner corrigeert de gegevens in het ERP, en er wordt een gecorrigeerde factuur ingediend.
Een factuur komt op de opvolgingslijst als het verzendkanaal ze definitief afwijst, of als tijdelijke fouten al hun herhaalpogingen hebben opgebruikt. De lijst vermeldt wat er mis is en wie handelt. We versturen een afgewezen bestand nooit ongewijzigd opnieuw: corrigeer de gegevens in het ERP en dien een gecorrigeerde factuur in. De opvolging van afwijzingen, het maandelijkse abonnement, werkt met deze drie aanroepen. Het serviceniveau staat in het contract, niet hier.
Een sleutel van een eindklant met de scope read leest de rijen van de eigen eindklant. Een rij als afgehandeld markeren is werk van de opvolging van afwijzingen, dus de sleutel van een eindklant krijgt 403 op die aanroep.
De lijst
GET /care geeft één rij per factuur terug.
| Veld | Betekenis |
|---|---|
invoice_id | De ID van de factuur. |
invoice_ref | De eigen referentie van de partner. |
client, route | De eindklant en het verzendkanaal van de factuur. |
catalogue_code | De code die de afwijzing uitlegt (zie fouten). |
who_acts | De verantwoordelijke voor de code: erp, us, business, client, buyer of route. |
field | Een plek in het canonieke model, zoals invoice.buyer_reference. Nooit een waarde. |
fix_hint | Wat er moet veranderen, uit de afwijzing of het catalogusitem. |
age_seconds | Hoelang de factuur al op de lijst staat. |
deadline_at | De indicatieve termijn van de factuur, als ze er een heeft (zie een factuur lezen). |
handled | Of iemand ze als afgehandeld heeft gemarkeerd. |
handled_at | Wanneer ze is gemarkeerd. Alleen aanwezig als handled op true staat. |
De queryparameter status kiest open, handled of all (de standaard). De sleutel van een eindklant krijgt hooguit de nieuwste 200 rijen, en truncated: true meldt dat er meer zijn. Hij mag 30 keer per minuut de lijst opvragen.
Opmerking
De lijst bevat geen factuurinhoud, en het log evenmin.
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": []
}Als afgehandeld markeren
POST /care/{id}/handled markeert een rij als afgehandeld en antwoordt met die rij. Bij een nieuwe aanroep blijft de eerste handled_at behouden. Een factuur die niet op de lijst staat, geeft 404. Alleen de sleutel van de operator mag deze aanroep doen.
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
}Het bewijsmateriaal exporteren
GET /care/{id}/evidence geeft de bestanden terug die voor de factuur zijn opgeslagen: invoice_id en een lijst files, elk met zijn kind, zijn sha256 en het bestand zelf als file_base64. Het bestand is het opgeslagen origineel; de factuurinhoud staat dus in dit antwoord en niet in de lijst. Een factuur die niet op de lijst staat, geeft 404, en de factuur van een andere eindklant ook. Een sleutel van een eindklant met de scope read mag deze aanroep 10 keer per minuut doen. Bestanden van samen meer dan 8 MiB geven 413 (evidence-too-large); lees ze dan één voor één met 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
}Antwoorden
| Status | Betekenis |
|---|---|
200 | De lijst, de gemarkeerde rij of het bewijsmateriaal. |
401 | Geen sleutel, of een onbekende sleutel. |
403 | De sleutel mist de scope read, of de sleutel van een eindklant probeerde een rij als afgehandeld te markeren. |
404 | De factuur staat niet op de opvolgingslijst. |
413 | Het bewijsmateriaal is samen groter dan 8 MiB (evidence-too-large). |
429 | Te veel aanvragen voor de sleutel. Wacht het aantal seconden in Retry-After. |