Connaître les capacités de sa clé
Lire le plan, les fonctionnalités et les limites effectives de votre clé API avant d'envoyer, pour dimensionner vos lots.
GET /api/v1/organization répond à une question : que puis-je faire avec
cette clé ? Plutôt que de coder en dur les limites d'un plan, votre
intégration les lit, et reste juste quand elles changent.
curl https://app.signlift.eu/api/v1/organization \
-H "X-Api-Key: $SIGNLIFT_API_KEY"{
"id": 12,
"name": "Capsens",
"plan": "pro",
"environment": "sandbox",
"features": {
"sms_otp": true,
"initials": true,
"branding_profiles": true,
"transactional_sms": false
},
"limits": {
"documents_per_request": 10,
"branding_profiles": 2,
"transactional_sms_per_month": 10000,
"rate_limit": { "per_minute": 120, "per_hour": 3000 }
}
}Le détail des champs est dans la référence.
transactional_sms et transactional_sms_per_month concernent les
SMS transactionnels.
L'environnement est celui de la clé
environment désigne l'environnement de la clé qui appelle, pas celui de
l'organisation : une même organisation peut avoir une clé sandbox et une clé
production, et elles ne reçoivent pas la même réponse. Les plafonds d'appels
(rate_limit) sont ceux de cet environnement, dont les budgets sont séparés.
Les limites sont les limites effectives
Les valeurs de limits sont celles qui s'appliquent réellement à votre
organisation : si un forçage a été posé par le back-office (plus de documents
par demande, un plafond d'appels relevé, des chartes graphiques sur un plan qui
n'en inclut pas), c'est la valeur forcée qui est renvoyée, pas celle du plan.
Ne déduisez donc jamais une limite du seul plan.
null signifie illimité
Un plafond à null n'a pas de borne. Gérez ce cas avant toute comparaison :
const { limits } = await response.json()
// null means unlimited: keep every document in one request
const perRequest = limits.documents_per_request ?? InfinityPas de SMS en sandbox
features.sms_otp dit si votre plan ouvre l'authentification par SMS. En
sandbox, aucun SMS n'est jamais envoyé, même quand il vaut true : le
code est simulé et remonté dans la réponse de l'envoi d'OTP. Ne concluez pas
de la réponse d'une clé sandbox que vos signataires recevront un SMS. Voir
Sandbox.
402 en production sans accès payant
Comme tous les autres endpoints, celui-ci répond 402 payment_required à une
clé de production dont l'organisation n'a pas d'accès payant. Vous pouvez
l'utiliser comme vérification de démarrage : un 402 ici signale que l'API de
production n'est pas ouverte, avant même d'avoir tenté un envoi. Une clé
sandbox, elle, répond toujours.
Quand l'appeler
Appelez-le une fois au démarrage de votre service, ou avant chaque lot, puis gardez la réponse en mémoire le temps du traitement. Il n'a pas besoin d'être appelé à chaque envoi, et il consomme votre budget d'appels comme les autres routes (voir Limites et rate-limits).
Deux dimensionnements en dépendent :
- Le regroupement des documents.
documents_per_requestborne le nombre de documents d'une demande de signature. Pour un lot de documents à faire signer par les mêmes signataires, découpez-le en paquets de cette taille, ou en une seule demande si la limite estnull. - La cadence.
rate_limit.per_minuteetrate_limit.per_hourdonnent le rythme que votre file d'envoi peut tenir. Laissez de la marge : le compteur est partagé par toutes les clés de l'organisation sur cet environnement.
const { limits } = await getOrganization()
const size = limits.documents_per_request ?? documents.length
for (let i = 0; i < documents.length; i += size) {
await createSignatureRequest(documents.slice(i, i + size))
}Aller plus loin
- Référence de
GET /organization - Limites et rate-limits : plafonds par environnement et gestion des
429. - Sandbox