Stable Pro API · v1
Authentification et autorisations
Clés, environnements, autorisations, limites de requêtes.
Les clés
Chaque requête porte une clé dans l'en-tête Authorization :
Authorization: Bearer sp_live_7Kq2…
Une clé est sp_live_ (production) ou sp_test_ (staging) suivi de 40 lettres et chiffres. L'écurie vient de la clé : vous ne transmettez jamais l'identifiant d'une écurie, et une clé ne lit qu'une seule écurie.
Les clés sont créées par le titulaire de l'écurie dans Stable Pro, Paramètres → Connexions. Une connexion, c'est votre logiciel ; elle peut avoir plusieurs clés au fil du temps. Le titulaire voit pour chaque clé ses quatre derniers caractères, sa dernière utilisation et le nombre de requêtes, et peut la révoquer à tout moment.
- Une clé ne s'affiche qu'une fois, à sa création. Stable Pro n'en conserve qu'une empreinte : si elle est perdue, le titulaire en crée une nouvelle.
- Rotation : quand le titulaire crée une nouvelle clé pour la connexion, la précédente continue de fonctionner pendant 7 jours, puis s'arrête. Remplacez-la dans votre logiciel pendant ce délai.
- Expiration : le titulaire peut donner une date d'expiration à une clé (90 jours, un an, ou aucune).
- Une clé
sp_test_est refusée en production, et une clésp_live_sur le staging (401,reason: wrong_environment).
Quand une clé n'est pas valide, la réponse est 401 avec WWW-Authenticate: Bearer et un reason : missing, malformed, wrong_environment, unknown, connection_revoked, revoked, expired, rotated.
GET /connection renvoie la connexion de la clé appelante : son nom, ses autorisations et la clé elle-même (jamais le secret).
Les autorisations
Le titulaire choisit ce que la connexion peut lire :
| Autorisation | Ouvre |
|---|---|
charges:read | les débits et les corrections, le solde des clients |
payments:read | les encaissements et les remboursements, les affectations, les mouvements du crédit |
receipts:read | les reçus de Stable Pro et leur PDF |
customers:read | les clients : code, type, nom, s'ils sont encore actifs |
customers.fiscal:read | les données de facturation des clients : adresse structurée, identifiants fiscaux, code fiscal ; et les données fiscales de qui a payé pour le compte d'un client |
Une requête sans l'autorisation de son endpoint répond 403 avec type: …/forbidden et missing_permission. Sans customers.fiscal:read, les données de facturation sont absentes de la réponse, elles ne valent pas null : elles n'y sont pas du tout, objets imbriqués compris. Chaque lecture des données de facturation est comptée à part dans le journal des requêtes de l'écurie.
/connection, /organization, /codes et /events ne demandent aucune autorisation particulière. Chaque événement n'est affiché qu'avec l'autorisation de l'objet vers lequel il pointe (voir Événements).
L'espace Comptabilité
L'API fait partie de l'espace Comptabilité de l'offre de l'écurie. Si l'écurie ne l'a pas, chaque requête répond 403 avec type: …/accounting-disabled.
Limites de requêtes
| Limite | Valeur | En cas de dépassement |
|---|---|---|
| par clé | 60 requêtes par minute | 429, Retry-After: 60 |
| par écurie | 10 000 requêtes par jour | 429, Retry-After: 86400 |
Si le limiteur lui-même n'est pas disponible, l'API répond 503 avec Retry-After: 30 : elle ne laisse jamais passer une requête sans la contrôler.
Lecture seule
La version 1 lit. Elle ne peut rien créer, modifier ni supprimer dans Stable Pro. Renvoyer à Stable Pro les documents qu'émet votre logiciel (numéro, statut, faits couverts) est la prochaine phase de l'API.