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/envelopesCré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.pdfDocument signé et scellé
GET /v1/envelopes/{id}/proof.pdfCertificat de preuve
GET /v1/envelopes/{id}/eventsJournal de preuve chaîné
POST /v1/envelopes/{id}/remindRelancer les signataires en attente
POST /v1/envelopes/{id}/signers/{sid}/embedLien 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)

Créer un compte développeur