Klucz API
Jak działa klucz typu bearer: osobny zestaw kluczy dla każdego klienta, z zakresami.
- W sandboxie
Prostymi słowami
Klucz API pozwala systemowi wywołującemu udowodnić, że może korzystać z usługi. Każdy klient ma własne klucze, a każdy klucz ma zakresy, które określają, co może robić. Pierwszy klucz do sandboxa wydajemy na prośbę.
Klucz należy wysyłać jako token typu bearer przy każdym wywołaniu.
Authorization: Bearer <your-api-key>Co usługa z nim robi
Usługa oblicza skrót SHA-256 wysłanego klucza i porównuje go ze skrótem, który przechowuje. Nie zapisuje żadnej wartości klucza. Każde użycie jest zapisywane w dzienniku audytu jako wiersz, który również nie zawiera wartości klucza. Klucz sandboxa zaczyna się od eik_test_, a klucz produkcyjny od eik_live_.
Prawidłowy klucz
Wywołanie wymagające klucza, wykonane z prawidłowym kluczem. Lista do obsługi jest pusta, bo nic nie zostało odrzucone.
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": []
}Brak klucza lub błędny klucz
Odpowiedzią jest 401, zanim usługa odczyta cokolwiek innego.
curl "https://api-sandbox-eu.eurinvoice.com/invoices/inv_unknown"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/invoices/inv_unknown"))
.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/invoices/inv_unknown', {
});
console.log(response.status);
console.log(await response.text());{
"type": "https://eurinvoice.com/problems/unauthorized",
"title": "Missing or unknown API key",
"status": 401
}Klucze i zakresy
Klucz należy do jednego klienta i widzi tylko dane tego klienta. Dla faktury innego klienta odpowiedzią jest 404.
| Zakres | Co może robić klucz |
|---|---|
submit | Wysyłać faktury (POST /invoices, POST /invoices/xml), wykonywać przebieg próbny (POST /validate) i anulować fakturę. |
read | Odczytywać faktury, zdarzenia i dokumenty, listę do obsługi i katalog. |
admin | Zarządzać webhookiem, danymi dostępowymi do sieci i kluczami API klienta. |
Wywołanie bez wymaganego zakresu kończy się odpowiedzią 403. Każdy zakres ma własny limit żądań.
Tworzenie i unieważnianie kluczy
Klucz jest pokazywany raz, w odpowiedzi, która go tworzy. Przechowujemy tylko jego SHA-256, więc zgubionego klucza nie można pokazać ponownie: należy go unieważnić i utworzyć nowy.
- Klucz z zakresem
admintworzy klucze dla własnego klienta, z dowolnymi zakresami, które sam posiada, i je unieważnia. Unieważnienie klucza unieważnia też wszystkie klucze, które utworzył. - Jeden klient może mieć do 20 aktywnych kluczy. Każde wywołanie jest liczone dla klienta, a nie dla klucza, więc więcej kluczy nie daje więcej żądań.
- Unieważniony klucz przestaje działać natychmiast.
Pierwszy klucz dla klienta pochodzi od nas. Kolejne klucze tworzy się przez POST /keys.
Ostrzeżenie
Prawdziwych kluczy nie należy umieszczać w przykładach, zgłoszeniach ani e-mailach.