L'API Paraphe
Envoyez des documents en signature depuis vos logiciels, et recevez un webhook à chaque étape. La référence complète, avec un bac à sable, est sur /docs.
Authentification
Créez une clé dans API et intégrations. Une clé de test (pk_test_…) envoie de vrais mails mais sans valeur légale ni décompte. Passez-la dans l'en-tête :
Authorization: Bearer pk_live_…
Créer un envoi
Requête multipart/form-data avec le PDF (document) et sa description en JSON (payload). Les positions sont en pourcentage de la page, depuis le coin haut gauche.
POST /v1/envelopes
{
"title": "Contrat de maîtrise d'œuvre Roux",
"ordered": true, // signature dans l'ordre
"expires_in_days": 15,
"remind_every_days": 3,
"signers": [{
"name": "Claire Roux", "email": "claire.roux@exemple.fr",
"phone": "+33612345678", "auth": "email+sms",
"fields": [
{ "type": "signature", "page": 4, "x": 9, "y": 70, "w": 32, "h": 8 },
{ "type": "mention", "page": 4, "x": 9, "y": 80, "label": "Lu et approuvé" },
{ "type": "initials", "page": "all" }
]
}],
"metadata": { "crm_affaire": "AFF-2611-042" }
}
Types de champs : signature, initials (paraphe), date (remplie automatiquement), text, checkbox, mention (texte à recopier). Chaque signataire doit avoir au moins un champ signature.
Principales routes
POST /v1/envelopes | Créer et envoyer (ou "send": false pour un brouillon) |
GET /v1/envelopes/{id} | Statut de l'envoi et de chaque signataire |
GET /v1/envelopes/{id}/signed.pdf | Document signé et scellé |
GET /v1/envelopes/{id}/proof.pdf | Certificat de preuve |
GET /v1/envelopes/{id}/events | Journal de preuve chaîné |
POST /v1/envelopes/{id}/remind | Relancer les signataires en attente |
POST /v1/envelopes/{id}/signers/{sid}/embed | Lien de signature à ouvrir depuis votre page |
DELETE /v1/envelopes/{id} | Annuler un envoi en cours |
Webhooks
Événements : envelope.sent, signer.signed, envelope.completed, envelope.declined, envelope.expired, envelope.canceled. Chaque appel porte l'en-tête Paraphe-Signature: t=…,v1=… : un HMAC-SHA256 de "t.corps" avec votre secret. Rejetez les appels dont la signature ne correspond pas ou dont t a plus de 5 minutes. Sans réponse 2xx, l'appel est retenté jusqu'à 6 fois sur 24 heures.
# Vérifier un webhook (Python)
t, v1 = [p.split("=", 1)[1] for p in header.split(",")]
attendu = hmac.new(secret.encode(), f"{t}.{corps}".encode(), "sha256").hexdigest()
assert hmac.compare_digest(attendu, v1)