Stable Pro API · v1
Autenticazione e permessi
Chiavi, ambienti, permessi, limiti di richieste.
Le chiavi
Ogni richiesta porta una chiave nell'intestazione Authorization:
Authorization: Bearer sp_live_7Kq2…
Una chiave è sp_live_ (produzione) o sp_test_ (staging) seguito da 40 lettere e cifre. La scuderia viene dalla chiave: non passi mai l'id di una scuderia, e una chiave legge una scuderia sola.
Le chiavi le crea il titolare della scuderia in Stable Pro, Impostazioni → Collegamenti. Un collegamento è il tuo programma; nel tempo può avere più di una chiave. Il titolare vede di ogni chiave gli ultimi quattro caratteri, l'ultimo uso e il numero di richieste, e può revocarla quando vuole.
- Una chiave si vede una volta sola, quando viene creata. Stable Pro ne conserva solo un'impronta: se va persa, il titolare ne crea una nuova.
- Rotazione: quando il titolare crea una chiave nuova per il collegamento, quella di prima continua a funzionare per 7 giorni, poi smette. Sostituiscila nel tuo programma entro quel tempo.
- Scadenza: il titolare può dare una scadenza a una chiave (90 giorni, un anno, o nessuna).
- Una chiave
sp_test_è rifiutata in produzione, e unasp_live_sullo staging (401,reason: wrong_environment).
Quando una chiave non è valida la risposta è 401 con WWW-Authenticate: Bearer e un reason: missing, malformed, wrong_environment, unknown, connection_revoked, revoked, expired, rotated.
GET /connection restituisce il collegamento della chiave che chiama: il nome, i permessi e la chiave stessa (mai il segreto).
I permessi
Il titolare sceglie cosa può leggere il collegamento:
| Permesso | Apre |
|---|---|
charges:read | addebiti e correzioni, il saldo dei clienti |
payments:read | incassi e rimborsi, assegnazioni, movimenti del credito |
receipts:read | le ricevute di Stable Pro e il loro PDF |
customers:read | i clienti: codice, tipo, nome, se sono ancora attivi |
customers.fiscal:read | i dati per la fattura dei clienti: indirizzo strutturato, identificativi fiscali, codice fiscale; e i dati fiscali di chi ha pagato per conto di un cliente |
Una richiesta senza il permesso del suo endpoint risponde 403 con type: …/forbidden e missing_permission. Senza customers.fiscal:read i dati per la fattura mancano dalla risposta, non valgono null: non ci sono proprio, oggetti annidati compresi. Ogni lettura dei dati per la fattura è contata a parte nel registro delle richieste della scuderia.
/connection, /organization, /codes e /events non chiedono un permesso particolare. Ogni novità si vede solo col permesso dell'oggetto a cui punta (vedi Novità).
L'area Contabilità
L'API fa parte dell'area Contabilità del piano della scuderia. Se la scuderia non ce l'ha, ogni richiesta risponde 403 con type: …/accounting-disabled.
Limiti di richieste
| Limite | Valore | Quando si supera |
|---|---|---|
| per chiave | 60 richieste al minuto | 429, Retry-After: 60 |
| per scuderia | 10.000 richieste al giorno | 429, Retry-After: 86400 |
Se il limitatore stesso non è disponibile, l'API risponde 503 con Retry-After: 30: non lascia mai passare una richiesta senza controllarla.
Solo lettura
La versione 1 legge. Non può creare, cambiare né cancellare niente in Stable Pro. Scrivere indietro i documenti che emette il tuo programma (numero, stato, quali fatti coprono) è la prossima fase dell'API.