API d'intégration Paraf

1. Connexion & authentification

Base URL : https://paraf.digital

Chaque requête porte votre clé API dans l'en-tête :

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx

• La clé est transmise en privé (jamais dans cette page). Paraf n'en stocke que le hash.
• Révocable à tout moment. Limite : 120 requêtes/min/clé.
• Vos documents sont isolés sous votre compte ; on les retrouve via votre externalRef.

2. Créer une demande de signature

POST/api/integration/signatures

{
  "document": {
    "base64": "<PDF en base64>",      // OU "url": "https://.../doc.pdf"
    "fileName": "bulletin-mai.pdf",
    "title": "Bulletin de paie - Mai 2026",
    "type": "bulletin"                 // libre : bulletin | contrat | ...
  },
  "signatories": [
    { "name": "Nom du salarié", "email": "signataire@votre-domaine.fr", "role": "Salarié" },
    { "name": "Nom du représentant", "email": "employeur@votre-domaine.fr", "role": "Employeur" }
  ],
  "externalRef": "votre-id-interne-12345",
  "callbackUrl": "https://votre-app/webhooks/paraf"
}

Réponse 201 :

{
  "signatureRequestId": 42,
  "status": "pending",
  "externalRef": "votre-id-interne-12345",
  "signatories": [
    { "name": "Nom du salarié", "email": "signataire@votre-domaine.fr",
      "signatureUrl": "https://paraf.digital/sign/<token>" }
  ],
  "webhookSecret": "<secret HMAC à stocker>"
}

• Paraf envoie déjà l'email d'invitation à chaque signataire. L'usage du signatureUrl (redirection) est optionnel.
• Stockez le mapping externalRef ↔ signatureRequestId et le webhookSecret.

2 bis. Mode « préparation » — l'utilisateur place les champs

Pour des documents riches (contrat, attestation…) nécessitant plusieurs champs(signature, paraphe, date, texte, case), ajoutez "mode": "prepare". Paraf renvoie une page-éditeur que votre utilisateur ouvre en iframe(il reste dans votre logiciel) : il place les champs, puis clique « Envoyer ».

// Réponse 201 (mode prepare)
{
  "signatureRequestId": 42,
  "status": "draft",
  "preparationUrl": "https://paraf.digital/prepare/<token>",
  "signatories": [ { "name": "Nom du salarié", "email": "signataire@votre-domaine.fr" } ]
}

<iframe src="https://paraf.digital/prepare/<token>"
        style="width:100%;height:800px;border:0"></iframe>

Jeton non devinable, à usage unique. mode par défaut = "auto"(signature auto-placée + envoi immédiat).

3. Consulter le statut

GET/api/integration/signatures/:id

{
  "signatureRequestId": 42,
  "externalRef": "votre-id-interne-12345",
  "status": "pending",          // pending | completed | declined | expired | cancelled
  "documentReady": false,       // true quand le PDF signé est disponible
  "signatories": [
    { "name": "Nom du salarié", "email": "signataire@votre-domaine.fr", "status": "viewed", "signedAt": null }
  ]
}

3 bis. Relancer un signataire, ou annuler la demande

POST/api/integration/signatures/:id/remind

Renvoie l'email d'invitation aux signataires qui n'ont pas encore signé — le lien de signature n'étant retourné qu'une fois, à la création. Corps facultatif { "email": "signataire@votre-domaine.fr" } pour ne viser qu'une personne. Un même signataire n'est pas relancé deux fois en moins d'une heure (motif too_soon).

POST/api/integration/signatures/:id/cancel

Retire une demande partie par erreur : le lien de signature cesse de fonctionner. Le signataire qui l'ouvre ensuite lit « Cette demande de signature a été annulée par son expéditeur » et ne peut plus rien signer.

// Corps facultatif — la raison va au journal d'audit, PAS au signataire
{ "reason": "Document incomplet, remplacé par la demande #43" }

// Réponse 200
{
  "signatureRequestId": 42,
  "status": "cancelled",
  "alreadyCancelled": false,
  "cancelledSignatories": [           // ceux qui attendaient pour rien
    { "name": "Nom du salarié", "email": "signataire@votre-domaine.fr", "status": "viewed" }
  ]
}

• Un document déjà signé ne s'annule pas (409 already_completed) : c'est une preuve.
• Rejouable : ré-annuler renvoie alreadyCancelled: true, jamais une erreur.
• Aucun email n'est envoyé aux signataires : à votre application de les prévenir si besoin.

4. Récupérer le document signé + preuve

GET/api/integration/signatures/:id/document

Renvoie le PDF signé (application/pdf) avec le certificat de preuve concaténé, et l'en-tête X-Paraf-Signed-Hash. Le PDF est streamé après vérification de votre clé (jamais d'URL publique). Renvoie 409 tant que tout le monde n'a pas signé.

5. Webhook (Paraf → votre application)

Si callbackUrl est fourni, Paraf envoie un POST à chaque état final :

X-Paraf-Event: signature.completed     // ou .declined / .expired / .cancelled
X-Paraf-Signature: <HMAC-SHA256 hex du corps brut, clé = webhookSecret>
X-Paraf-Delivery: 42

{
  "event": "signature.completed",
  "signatureRequestId": 42,
  "externalRef": "votre-id-interne-12345",
  "status": "completed",
  "documentUrl": "https://paraf.digital/api/integration/signatures/42/document",
  "occurredAt": "2026-06-17T09:12:30Z"
}

Vérification de la signature (Node) :

const expected = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(rawRequestBody)        // le corps BRUT, non re-sérialisé
  .digest("hex");
if (expected !== req.headers["x-paraf-signature"]) return res.status(401).end();

Livraison best-effort + retries (jusqu'à 6 tentatives). Idempotence conseillée sur (signatureRequestId, event).

6. Codes d'erreur

7. Sécurité & RGPD

• Clé hashée (SHA-256), révocable, rate-limitée. Stockez-la côté serveur, jamais dans le front.
• Jeton de signature non devinable, lié au signataire.
• Téléchargement du signé authentifié — pas d'URL publique pour ce flux.
• Webhook signé (HMAC) pour prouver l'origine Paraf.
• Signature électronique simple recevable en preuve, accompagnée d'une empreinte SHA-256 et d'un journal d'audit.