Passer en production¶

Introduction¶

Ce guide couvre les étapes communes à toute intégration en production, quel que soit le mode d'intégration choisi. Pour les spécificités de chaque flux, voir Intégrer la signature par mail et Intégrer la signature sur votre application.

La création de la demande, les webhooks, le téléchargement du PDF signé et celui du dossier de preuves sont identiques dans les deux flux. Seule la délivrance du lien de signature au signataire change. Si vous n'avez pas encore choisi votre mode, consultez Modes d'intégration.

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
• Choisi votre mode d'intégration et lu le guide correspondant (flux mail ou flux embarqué)

Processus de production type¶

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

    B->>V: POST /api/v1/requests
    V-->>B: 201 { request_id, … }
    V->>S: Invitation au signataire

    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/pdf
    V-->>B: 200 audit-trail.pdf

    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 vos documents, les signataires et le invitation_mode adapté à votre cas. Conservez le request_id retourné (et, en flux embarqué, chaque signer_id ainsi que la valeur embed.iframe_url). Consultez la Référence API pour la spécification complète, Positionner les champs pour le placement des champs de signature, et le tutoriel Première Requête (flux mail / flux embarqué) pour des exemples curl.

2. Délivrance du lien de signature

L'étape qui distingue les deux flux. Consultez le guide correspondant à votre mode : Intégrer la signature par mail ou Intégrer la signature sur votre application.

Consultez Cycle de vie d'une demande pour les statuts intermédiaires.

3. Les signataires signent

Chaque signataire ouvre le document, valide son code OTP 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.

Si vous utilisez le flux embarqué, votre UI peut aussi réagir par signataire via postMessage — voir Intégrer la signature sur votre application.

4. Recevoir le webhook request.completed

VoidSign envoie un événement request.completed à votre endpoint webhook, identiquement dans les deux modes. 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 signature_request_not_completed : 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.

Pour les erreurs propres à chaque flux (expiration de jeton, codes voidsign:error, etc. en flux embarqué ; expiration du lien d'invitation en flux mail), consultez les guides dédiés.

Rotation des clés API¶

Pour renouveler une clé API sans interruption de service (fuite suspectée, rotation périodique de vos secrets), utilisez la rotation depuis l'interface web (https://app.voidsign.com/pro/api/keys) plutôt que de supprimer puis recréer une clé.

À la rotation :

• une nouvelle clé (même nom) est émise immédiatement ; déployez-la dans votre configuration ;
• l'ancienne clé reste valide pendant une période de grâce que vous choisissez, puis est révoquée automatiquement.

Les périodes de grâce disponibles sont 24 h, 48 h, 7 jours (168 h) et 30 jours (720 h). Pendant toute la période de grâce, les deux clés authentifient normalement, ce qui vous laisse le temps de basculer vos environnements. Passé l'échéance, l'ancienne clé est révoquée : elle renvoie alors 401 avec le code api_key_revoked.

À venir¶

Métadonnées métier¶

Requêtes idempotentes¶

Synchronisation et interrogation¶