Chiave API
Come funziona la chiave bearer: un insieme di chiavi per ciascun cliente, con scope.
- Nella sandbox
In parole semplici
La chiave API è il modo in cui un sistema chiamante dimostra di poter usare il servizio. Ogni cliente ha le proprie chiavi, e ogni chiave ha scope che dicono cosa può fare. Rilasciamo la prima chiave sandbox su richiesta.
Inviare la chiave come token bearer in ogni chiamata.
Authorization: Bearer <your-api-key>Cosa ne fa il servizio
Il servizio calcola l’hash SHA-256 della chiave inviata e lo confronta con quello che conserva. Non memorizza alcun valore della chiave. Ogni utilizzo scrive una riga di audit, e anche quella riga non contiene alcun valore. Una chiave sandbox inizia con eik_test_, una chiave di produzione con eik_live_.
Una chiave valida
Una chiamata che richiede una chiave, con una chiave valida. L’elenco degli scarti è vuoto perché non è stato scartato nulla.
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": []
}Una chiave mancante o errata
La risposta è 401, prima che venga letto qualsiasi altro dato.
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
}Chiavi e scope
Una chiave appartiene a un solo cliente e vede solo i dati di quel cliente. La fattura di un altro cliente risponde 404.
| Scope | Cosa può fare la chiave |
|---|---|
submit | Inviare fatture (POST /invoices, POST /invoices/xml), eseguire una simulazione (POST /validate) e annullare una fattura. |
read | Leggere fatture, eventi e documenti, l’elenco degli scarti e il catalogo. |
admin | Gestire il webhook, le credenziali per le infrastrutture e le chiavi API del cliente. |
Una chiamata senza lo scope che richiede risponde 403. Ogni scope ha il proprio limite di frequenza.
Creare e revocare le chiavi
Una chiave viene mostrata una sola volta, nella risposta che la crea. Conserviamo solo il suo SHA-256, quindi una chiave smarrita non può essere mostrata di nuovo: va revocata e ne va creata una nuova.
- Una chiave con lo scope
admincrea chiavi per il proprio cliente, con qualsiasi scope che possiede essa stessa, e le revoca. Revocare una chiave revoca anche tutte le chiavi che ha creato. - Un cliente può avere fino a 20 chiavi attive. Ogni chiamata viene conteggiata per il cliente, non per la chiave, quindi più chiavi non danno più richieste.
- Una chiave revocata smette di funzionare subito.
La prima chiave di un cliente viene da noi. Le chiavi successive si creano con POST /keys.
Avvertenza
Non inserire chiavi reali in esempi, ticket o e-mail.