API Signature Électronique

Intégrez la signature électronique dans vos applications en quelques lignes de code

v1.0Productionhttps://api.vusadoc.fr

Vue d'ensemble

L'API Signature Électronique de Vusadoc vous permet d'intégrer la signature de documents PDF dans vos applications. Elle est idéale pour faire signer des devis, contrats ou tout autre document.

Signature simple eIDAS

Signature électronique légalement reconnue

Détection automatique

Détecte automatiquement la zone "Signature client"

Webhooks

Notification en temps réel après signature

Format PAdES

PDF signé conforme aux standards européens

Flux de signature

Votre applicationEnvoie le PDF à signer via l'API

VusadocRetourne une URL de signature

Votre applicationEnvoie l'URL au signataire

Le signataireSigne sur la page Vusadoc

VusadocEnvoie le PDF signé via callback

Authentification

Toutes les requêtes à l'API doivent inclure votre clé API dans l'en-tête X-API-Key.

Obtenir une clé API

Pour obtenir votre clé API, faites une demande ici.

En-tête d'authentification

X-API-Key: app_xxxxxxxxxxxxxxxx

Sécurité

Ne partagez jamais votre clé API. Ne l'incluez pas dans le code côté client (JavaScript frontend). Utilisez-la uniquement côté serveur.

Environnements

Environnement	URL de base	Description
Production	`https://api.vusadoc.fr`	Environnement de production
Sandbox	`https://sandbox.api.vusadoc.fr`	Environnement de test (signatures non valides légalement)

Créer une demande de signature

Initialise une nouvelle demande de signature et retourne l'URL à envoyer au signataire.

POST/api/external/signature/init

Paramètres

Paramètre	Type	Requis	Description
`documentTitle`	string	Oui	Titre du document (ex: "Devis-2026-001")
`documentReference`	string	Non	Référence interne du document
`pdfBase64`	string	Oui	Contenu du PDF encodé en base64
`signerEmail`	string	Oui	Email du signataire
`signerName`	string	Non	Nom complet du signataire
`callbackUrl`	string	Oui	URL de votre webhook pour recevoir le PDF signé
`expirationDays`	integer	Non	Nombre de jours avant expiration (défaut: 30)

Exemple de requête

CURL

curl -X POST "https://api.vusadoc.fr/api/external/signature/init" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documentTitle": "Devis-2026-001",
    "documentReference": "DEV-001",
    "pdfBase64": "JVBERi0xLjQK...",
    "signerEmail": "client@example.com",
    "signerName": "Jean Dupont",
    "callbackUrl": "https://votre-app.com/webhook/signature",
    "expirationDays": 30
  }'

Réponse

JSON Response - 201 Created

{
  "signatureId": "sig_abc123xyz",
  "signatureUrl": "https://app.vusadoc.fr/sign/sig_abc123xyz?token=xxxxx",
  "status": "PENDING",
  "expiresAt": "2026-06-02T00:00:00Z",
  "zoneDetected": true,
  "zonePageNumber": 2
}

Détection automatique de zone

Si votre PDF contient le texte "Signature client" ou "Signature du client", la zone de signature sera automatiquement positionnée à cet endroit. Sinon, elle sera placée en bas de la dernière page.

Consulter le statut

Récupère les informations et le statut d'une demande de signature.

GET/api/external/signature/{signatureId}

Exemple de requête

CURL

curl -X GET "https://api.vusadoc.fr/api/external/signature/sig_abc123xyz" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse

JSON Response - 200 OK

{
  "signatureId": "sig_abc123xyz",
  "status": "PENDING",
  "documentTitle": "Devis-2026-001",
  "documentReference": "DEV-001",
  "signerEmail": "client@example.com",
  "signerName": "Jean Dupont",
  "createdAt": "2026-05-02T10:00:00Z",
  "expiresAt": "2026-06-02T00:00:00Z",
  "signedAt": null
}

Statuts possibles

Statut	Description
PENDING	En attente de signature
SIGNED	Document signé avec succès
EXPIRED	La demande a expiré
CANCELLED	La demande a été annulée

Annuler une demande

Annule une demande de signature en attente. Le document sera supprimé.

DELETE/api/external/signature/{signatureId}

Attention

Seules les demandes en statut PENDING peuvent être annulées.

Exemple de requête

CURL

curl -X DELETE "https://api.vusadoc.fr/api/external/signature/sig_abc123xyz" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse

JSON Response - 200 OK

{
  "signatureId": "sig_abc123xyz",
  "status": "CANCELLED",
  "message": "Demande de signature annulée avec succès"
}

Callbacks (Webhooks)

Après la signature du document, Vusadoc envoie une requête POST à votre callbackUrl contenant le PDF signé et les informations de signature.

Payload du callback

POST sur votre callbackUrl

{
  "event": "signature.completed",
  "signatureId": "sig_abc123xyz",
  "status": "SIGNED",
  "documentTitle": "Devis-2026-001",
  "documentReference": "DEV-001",
  "signerEmail": "client@example.com",
  "signerName": "Jean Dupont",
  "signedAt": "2026-05-02T14:30:00Z",
  "signedPdfBase64": "JVBERi0xLjQK...",
  "signerIp": "192.168.1.100"
}

Vérification de la signature HMAC

Chaque callback inclut un en-tête X-Vusadoc-Signature contenant une signature HMAC-SHA256 du payload. Vous devez vérifier cette signature pour vous assurer que le callback provient bien de Vusadoc.

En-tête de signature

X-Vusadoc-Signature: sha256=a1b2c3d4e5f6...

Exemple d'implémentation

CURL

# Exemple de payload reçu sur votre webhook
# POST https://votre-app.com/webhook/signature

{
  "event": "signature.completed",
  "signatureId": "sig_abc123xyz",
  "status": "SIGNED",
  "documentTitle": "Devis-2026-001",
  "documentReference": "DEV-001",
  "signerEmail": "client@example.com",
  "signerName": "Jean Dupont",
  "signedAt": "2026-05-02T14:30:00Z",
  "signedPdfBase64": "JVBERi0xLjQK...",
  "signerIp": "192.168.1.100"
}

Acquittement

Votre endpoint doit répondre avec un code HTTP 200 pour acquitter la réception. En cas d'échec, Vusadoc réessaiera jusqu'à 5 fois avec un délai exponentiel.

Tentative	Délai
1	Immédiat
2	5 minutes
3	30 minutes
4	2 heures
5	24 heures

Gestion des erreurs

L'API utilise les codes HTTP standards et retourne des erreurs au format JSON.

Format des erreurs

JSON Error Response

{
  "error": "INVALID_API_KEY",
  "message": "La clé API fournie est invalide ou inactive",
  "timestamp": "2026-05-02T10:00:00Z"
}

Codes d'erreur

Code HTTP	Code erreur	Description
400	`INVALID_REQUEST`	Paramètres manquants ou invalides
400	`INVALID_PDF`	Le PDF fourni est invalide ou corrompu
401	`INVALID_API_KEY`	Clé API invalide ou manquante
403	`API_KEY_INACTIVE`	La clé API a été désactivée
404	`SIGNATURE_NOT_FOUND`	Demande de signature introuvable
409	`INVALID_STATUS`	L'opération n'est pas autorisée dans le statut actuel
429	`RATE_LIMIT_EXCEEDED`	Trop de requêtes, réessayez plus tard
500	`INTERNAL_ERROR`	Erreur interne du serveur

OpenAPI / Swagger

Téléchargez la spécification OpenAPI pour importer l'API dans vos outils (Postman, Insomnia, etc.) ou générer automatiquement des clients.

Télécharger OpenAPI (YAML) Télécharger OpenAPI (JSON)

Swagger UI interactif

Une interface Swagger interactive sera bientôt disponible pour tester l'API directement depuis votre navigateur.