Signlift

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 ?? Infinity

Pas 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_request borne 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 est null.
  • La cadence. rate_limit.per_minute et rate_limit.per_hour donnent 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

On this page