Aller au contenu

Appeler l'API VoidSign

Authentification

Chaque requête doit inclure votre clé API dans l'en-tête X-VoidSign-Key :

X-VoidSign-Key: vs_live_...

Conservez vos clés API côté serveur

N'exposez jamais vos clés API dans du code côté client, des dépôts publics ou des journaux. Utilisez des variables d'environnement ou un gestionnaire de secrets (par exemple AWS Secrets Manager, HashiCorp Vault) pour les stocker de manière sécurisée.

Pour les instructions de configuration, consultez Première Requête : Configurer votre clé API.

Endpoints disponibles

Méthode Endpoint Description
POST /api/v1/requests Créer une demande de signature
GET /api/v1/requests/{request_id} Obtenir le statut d'une demande
GET /api/v1/requests/{request_id}/downloads/signed Télécharger le PDF signé
GET /api/v1/requests/{request_id}/downloads/audit-trail/json Télécharger le dossier de preuves (JSON)
GET /api/v1/requests/{request_id}/downloads/audit-trail/pdf Télécharger le dossier de preuves (PDF)

Pour les schémas de requêtes et de réponses, consultez la Référence API.

Limites de débit

L'API applique une limite de débit de type token bucket de 60 requêtes par minute par clé API. Chaque clé API démarre avec 60 jetons, et un jeton est consommé par requête. Les jetons se rechargent à un rythme constant d'un jeton par seconde.

Surveillez votre budget restant

Vérifiez l'en-tête RateLimit-Remaining après chaque réponse. Si vos jetons restants descendent en dessous d'un seuil confortable, mettez en place un backoff exponentiel avant de recevoir un 429.

Pour tous les détails sur les en-têtes, les réponses d'erreur et la spécification du token bucket, consultez En-têtes et politique de limites de débit.

Stratégie de relance

function call_api_with_retry(url, api_key, max_retries = 5):
    wait_time = 0

    for attempt in 1 to max_retries:
        sleep(wait_time)

        response = http_get(url, headers={"X-VoidSign-Key": api_key})

        if response.status != 429:
            return response

        base_delay = int(response.headers["Retry-After"])
        wait_time  = base_delay * 2^(attempt - 1) + random(0, base_delay)

    raise Error("Rate limit: max retries exceeded")

La logique suit une backoff exponentiel avec *jitter* :

  1. Respecter Retry-After : utilisez le délai fourni par le serveur comme temps d'attente de base plutôt qu'une valeur codée en dur, afin que le client attende toujours au moins aussi longtemps que le serveur le demande.
  2. Facteur exponentiel : 2^(attempt - 1) double le temps d'attente à chaque 429 consécutif (1×, 2×, 4×, 8×, 16×), reculant progressivement pour laisser au token bucket le temps de se recharger.
  3. Jitter : random(0, base_delay) ajoute une composante aléatoire à chaque attente, évitant un "effet de troupeau" où plusieurs clients limités en même temps réessaient tous de manière synchronisée.

Bonnes pratiques

  • Surveiller RateLimit-Remaining : vérifiez cet en-tête après chaque réponse pour connaître le nombre de requêtes restantes avant limitation.
  • Mettre en place un backoff exponentiel : lorsque vous recevez un 429, attendez le nombre de secondes indiqué dans l'en-tête Retry-After, puis réessayez. Si la requête échoue à nouveau, doublez le temps d'attente.
  • Mettre en cache les réponses : si vous interrogez régulièrement le statut d'une demande de signature, mettez en cache le résultat et réduisez la fréquence d'interrogation pour les demandes peu susceptibles de changer rapidement.
  • Répartir les requêtes dans le temps : au lieu d'envoyer toutes les requêtes en rafale, distribuez-les de manière uniforme pour rester bien en deçà de la limite.
  • Utiliser les webhooks plutôt que le polling : les webhooks éliminent la majeure partie du trafic de polling. Consultez Passer en production pour le workflow de production recommandé.