Obsługa faktur z błędami
Trwałe odrzucenia i to, kto się nimi zajmuje.
- W sandboxie
Prostymi słowami
Lista do obsługi zawiera faktury, które krajowy kanał przesyłania odrzucił na stałe albo których wysyłka nie powiodła się mimo wszystkich ponowień, wraz z informacją, co jest nie tak i kto ma zareagować. Na tej liście pracuje Obsługa odrzuceń (Rejection Care), usługa w abonamencie miesięcznym. Nigdy nie wysyłamy ponownie odrzuconego pliku w niezmienionej postaci: klient lub partner poprawia dane w ERP, a następnie przesyłana jest poprawiona faktura.
Faktura trafia na listę do obsługi, gdy kanał odrzuci ją na stałe albo gdy po błędach przejściowych wyczerpią się ponowienia. Lista podaje, co jest nie tak i kto ma zareagować. Nigdy nie wysyłamy ponownie odrzuconego pliku w niezmienionej postaci: należy poprawić dane w ERP i przesłać poprawioną fakturę. Obsługa odrzuceń, czyli miesięczny abonament, korzysta z tych trzech wywołań. Poziom usług określa umowa, a nie ta strona.
Klucz klienta z zakresem read odczytuje wiersze własnego klienta. Oznaczanie wiersza jako obsłużonego to praca Obsługi odrzuceń, więc klucz klienta dostaje 403 przy tym wywołaniu.
Lista
GET /care zwraca po jednym wierszu dla każdej faktury.
| Pole | Znaczenie |
|---|---|
invoice_id | Identyfikator faktury. |
invoice_ref | Własny identyfikator partnera. |
client, route | Klient i kanał przesyłania faktury. |
catalogue_code | Kod, który wyjaśnia odrzucenie (zob. błędy). |
who_acts | Podmiot przypisany do kodu: erp, us, business, client, buyer lub route. |
field | Miejsce w modelu kanonicznym, na przykład invoice.buyer_reference. Nigdy wartość. |
fix_hint | Co zmienić, na podstawie odrzucenia lub wpisu w katalogu. |
age_seconds | Od jak dawna faktura jest na liście. |
deadline_at | Orientacyjny termin faktury, jeśli go ma (zob. odczyt faktury). |
handled | Czy ktoś oznaczył ją jako obsłużoną. |
handled_at | Kiedy została oznaczona. Występuje tylko wtedy, gdy handled ma wartość true. |
Parametr zapytania status wybiera open, handled lub all (domyślnie). Klucz klienta dostaje najwyżej 200 najnowszych wierszy, a truncated: true informuje, że jest ich więcej. Listę można pobierać 30 razy na minutę.
Uwaga
Treści faktur nie zawiera ani lista, ani dziennik.
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": []
}Oznaczenie faktury jako obsłużonej
POST /care/{id}/handled oznacza wiersz jako obsłużony i zwraca ten wiersz w odpowiedzi. Ponowne wywołanie zachowuje pierwszą wartość handled_at. Dla faktury, której nie ma na liście, odpowiedzią jest 404. Wywołać je może tylko klucz operatora.
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
}Eksport dowodów
GET /care/{id}/evidence zwraca pliki zapisane dla faktury: invoice_id i listę files, w której każdy element zawiera kind, sha256 i sam plik jako file_base64. Plik to zapisany oryginał, więc treść faktury jest w tej odpowiedzi, a nie na liście. Dla faktury, której nie ma na liście, odpowiedzią jest 404, podobnie jak dla faktury innego klienta. Klucz klienta z zakresem read może wywołać to 10 razy na minutę. Pliki o łącznym rozmiarze powyżej 8 MiB kończą się odpowiedzią 413 (evidence-too-large); należy odczytać je pojedynczo przez 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
}Odpowiedzi
| Status | Znaczenie |
|---|---|
200 | Lista, oznaczony wiersz lub dowody. |
401 | Brak klucza lub nieznany klucz. |
403 | Klucz nie ma zakresu read albo klucz klienta próbował oznaczyć wiersz jako obsłużony. |
404 | Faktury nie ma na liście do obsługi. |
413 | Dowody mają łącznie ponad 8 MiB (evidence-too-large). |
429 | Zbyt wiele żądań dla klucza. Należy odczekać liczbę sekund podaną w Retry-After. |