Passer en production¶

Introduction¶

Ce guide montre comment intégrer VoidSign dans un backend de production. Le guide Première Requête utilise le polling par souci de simplicité, mais une intégration en production doit s'appuyer sur les webhooks pour un traitement efficace et en temps réel.

Le principe est simple : créer une demande de signature, écouter un webhook lorsque tous les signataires ont signé, puis télécharger les documents complétés.

Prérequis¶

Avant de suivre ce guide, assurez-vous d'avoir :

• Pris connaissance de l'authentification, de l'API et des limites de débit
• Configuré un webhook pour recevoir les événements request.completed

Processus de production type¶

Diagramme de séquence¶

sequenceDiagram
    participant B as Votre serveur
    participant V@{ "type": "entity" } as VoidSign API
    participant S as Signataire(s)

    B->>V: POST /api/v1/requests (créer la demande)
    V-->>B: 201 { request_id }
    V->>S: Invitations par e-mail

    Note over B: Pas d'interrogation nécessaire.<br/>Attente du webhook

    S->>V: Signe le document
    V->>B: POST webhook: request.completed
    B-->>V: 200 OK

    B->>V: GET /downloads/signed
    V-->>B: 200 signed.pdf
    B->>V: GET /downloads/audit-trail/json
    V-->>B: 200 audit-trail.json

    Note over B: Stocker les documents,<br/>mettre à jour votre système

Étapes détaillées¶

1. Créer la demande de signature

Envoyez un POST /api/v1/requests avec votre document et les informations des signataires. Conservez le request_id retourné (vous en aurez besoin pour télécharger les documents par la suite). Consultez Première Requête : Créer une demande de signature pour un exemple curl complet et Positionner les champs pour le positionnement des champs de signature.

2. VoidSign envoie les invitations

VoidSign envoie par e-mail à chaque signataire un lien unique pour consulter et signer le document. Votre backend n'a rien à faire à cette étape. Consultez Cycle de vie d'une demande pour les détails du processus d'invitation.

3. Les signataires signent

Chaque signataire ouvre son lien et signe. À mesure que chaque signataire termine, son statut individuel passe à signed. Lorsque le dernier signataire signe, le statut de la demande passe à signed. Consultez Cycle de vie d'une demande pour le modèle complet des statuts.

4. Recevoir le webhook request.completed

VoidSign envoie un événement request.completed à votre endpoint webhook. Vérifiez la signature HMAC-SHA256, puis extrayez le request_id du payload. Consultez Configurer les webhooks pour les détails de la vérification.

5. Télécharger les documents signés

Utilisez le request_id pour télécharger le PDF signé et le dossier de preuves :

# Télécharger le PDF signé
curl -X GET \
  "https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/signed" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output signed.pdf

# Télécharger le dossier de preuves (JSON)
curl -X GET \
  "https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/audit-trail/json" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output audit-trail.json

# Télécharger le dossier de preuves (PDF)
curl -X GET \
  "https://api.voidsign.com/api/v1/requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/downloads/audit-trail/pdf" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output audit-trail.pdf

6. Traitement et stockage

Enregistrez le PDF signé et le dossier de preuves dans votre système de stockage (par exemple S3, base de données), mettez à jour l'état de votre application et notifiez les parties prenantes internes. La demande de signature est désormais terminée.

Gestion des erreurs¶

• Endpoint *webhook temporairement indisponible : VoidSign retente automatiquement les livraisons échouées (consultez Événements webhook : Comportement de réessai pour le calendrier). Assurez-vous que votre endpoint* est idempotent afin que les réessais soient sûrs.
• Le téléchargement retourne 429 : vous avez dépassé la limite de débit. Appliquez un backoff exponentiel en utilisant l'en-tête Retry-After. Consultez Limites de débit.
• Le téléchargement retourne 400 avec not_signed : la demande n'est pas encore terminée. Ne téléchargez pas de manière proactive ; attendez le webhook request.completed.
• Livraisons de webhook en double : utilisez l'en-tête webhook-id pour dédupliquer les événements et éviter un double traitement dans votre système.

À venir¶

Métadonnées métier¶

Requêtes idempotentes¶

Synchronisation et interrogation¶