API REST e-Signature.eu — signatures électroniques (SES, AES, QES)

1. Présentation

L’API REST d’e-Signature.eu permet à votre application d’envoyer des documents en signature électronique (simple SES, avancée AES ou qualifiée QES selon eIDAS) sans passer par notre site. Vous envoyez le PDF et les signataires ; nous gérons la vérification d’identité, la signature et le suivi ; vous récupérez le document signé via l’API ou un callback.

Cette documentation décrit l’API v3. Vous utilisez déjà l’API v2 (https://api.e-signature.eu/v2/signature/) ? Consultez le Changelog.

2. Authentification

Vos identifiants sont disponibles dans Mon compte > Signatures API une fois connecté sur e-signature.eu :

• User ID : envoyé dans l’URL, paramètre userid de chaque appel ;
• API token : envoyé dans l’en-tête HTTP x-api-key de chaque appel.

curl -X GET "https://api.e-signature.eu/v3/signature/requestBalance?userid=123" \
  -H "x-api-key: YOUR_API_TOKEN"

Gardez votre token secret : il donne un accès complet à votre compte via l’API. Les appels doivent partir de votre serveur, jamais d’un navigateur ou d’une application mobile.

3. Conventions

Requêtes et réponses

• HTTPS uniquement. Les corps de requête sont en JSON (Content-Type: application/json).
• Chaque réponse est en JSON, sous l’une de ces deux formes :

{ "success": true,  "result": { ... } }
{ "success": false, "error": "Readable error message" }

Limites

4. Crédits

Les demandes sont payées avec vos crédits prépayés e-signature.eu. Le prix d’une méthode s’obtient avec getMethods (vos prix spécifiques sont pris en compte). Votre solde est renvoyé par requestBalance et dans chaque objet demande (credits_balance).

Recharge automatique des crédits

Pour ne jamais manquer de crédits, votre compte peut se recharger automatiquement. Cela se configure une fois dans Mon compte > Signatures API, et non via l’API :

1. Choisissez un seuil (en crédits) et le pack de crédits à commander.
2. Enregistrez un moyen de paiement chez notre prestataire de paiement Mollie (carte, ou domiciliation SEPA via Bancontact, iDEAL…). Un paiement de vérification de 0,01 € est demandé une seule fois.
3. Chaque fois que des crédits sont débités et que votre solde passe sous le seuil, une commande du pack choisi est créée et payée automatiquement avec le moyen de paiement enregistré. La facture vous est envoyée par email.

5. Fonctionnement d’une demande de signature

1. Vous créez la demande avec le PDF, les signataires et les méthodes de signature acceptées. Les crédits sont débités.
2. Chaque signataire reçoit un email avec un lien de signature personnel (ou vous envoyez vous-même le signature_link lorsque send_email vaut false).
3. Le signataire vérifie son identité avec l’une des méthodes acceptées (itsme®, Evrotrust, Veriff, OTP…) et signe.
4. Quand tout le monde a signé, la demande est finished : le PDF signé (PAdES) est disponible via getRequest et envoyé dans le callback.

Ordre de signature

Par défaut, tous les signataires signent en parallèle. Pour définir un ordre, indiquez sign_first: true pour les signataires du premier groupe : ils sont invités immédiatement, éventuellement à plusieurs en parallèle. Les autres signataires ne sont invités que lorsque tout le premier groupe a signé. Deux groupes au maximum.

Deux modes d’intégration

N’interrogez pas l’API en boucle

N’appelez pas getRequest à répétition pour suivre l’état d’une demande : utilisez les callbacks, envoyés automatiquement à chaque changement. Des appels excessifs déclenchent une limitation automatique qui suspend temporairement le traitement de vos requêtes.

6. Créer une demande de signature

{
  "title": "Sales agreement 2026-114",
  "lang": "en",
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "signature_place": "position_auto",
  "reminder": 3,
  "send_email": true,
  "email_notification": false,
  "note_html": "Please sign the agreement before Friday.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "QUOTE-2026-114",
  "metadata": {
    "crm_deal_id": 8812
  },
  "callback_url": "https://erp.example.com/hooks/esignature",
  "signers": [
    {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "sign_first": true
    },
    {
      "firstname": "Marc",
      "lastname": "Dubois",
      "email": "[email protected]",
      "sign_first": false
    }
  ],
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Méthodes de signature

Ce sont les prix standards : getMethods renvoie les méthodes disponibles et les prix de votre compte. Seule une signature électronique qualifiée (QES) équivaut légalement à une signature manuscrite selon le règlement eIDAS. otp-email-non-qualified couvre l’email et le SMS : le code est envoyé par SMS si le signataire a un phone, sinon par email, au même prix.

Champs du corps de la requête

Champs d’un signataire

Coût

Prix de la méthode la plus chère de methods × nombre de signataires. Les crédits sont débités à la création de la demande. Ceux des signataires qui n’ont pas signé sont remboursés si la demande est annulée ou arrêtée.

Réponse 201 Created

{
  "success": true,
  "result": {
    "id_sign": 4521,
    "lang": "en",
    "doc_name": "Sales-agreement-2026-114",
    "send_email": true,
    "from_api": true,
    "signature_redirect": "https://www.example.com/thank-you",
    "status_id": "pending",
    "date_status": "2026-10-20 10:15:02",
    "last_reminder": null,
    "timezone": "Europe/Brussels",
    "credits": 2,
    "credits_balance": 38.4,
    "signers": {
      "1": {
        "firstname": "Ann",
        "lastname": "Peeters",
        "email": "[email protected]",
        "phone": "+32475111222",
        "sign_first": true,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      },
      "2": {
        "firstname": "Marc",
        "lastname": "Dubois",
        "email": "[email protected]",
        "sign_first": false,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      }
    },
    "external_reference": "QUOTE-2026-114",
    "metadata": {
      "crm_deal_id": 8812
    }
  }
}

7. Positionnement des signatures

position_auto (par défaut)

Placez les marqueurs #SIG01, #SIG02… (également accepté : #SIG01#) sous forme de texte dans votre document, là où chaque signataire doit signer (#SIG01 = premier signataire du tableau signers). La signature est placée en haut à gauche du marqueur. Si un même marqueur apparaît plusieurs fois, sa première occurrence est utilisée. Un marqueur est ignoré si sa zone de signature recouvrirait une signature déjà placée (ou une signature existante) : le signataire prend alors le marqueur libre suivant. Un marqueur si proche du bord de la page que la signature doit être décalée n’est utilisé qu’en dernier recours.

Document non encore signé

Si le document ne contient aucun marqueur, ou si le marqueur d’un signataire est absent, une page de signatures contenant les marqueurs est ajoutée à la fin du document et toutes les signatures sont placées sur cette page (6 signataires sur la première page ajoutée, puis 10 par page supplémentaire).

Document déjà signé

Aucune page ne peut être ajoutée à un PDF déjà signé électroniquement : cela invaliderait les signatures existantes. Avec position_auto, les signatures sont placées sur les marqueurs libres, c’est-à-dire les marqueurs dont la zone de signature ne recouvre aucune signature existante. Les marqueurs libres sont attribués aux signataires dans l’ordre (#SIG01, #SIG02…).

position_manual

Indiquez la position de la signature, en centimètres, pour chaque signataire :

{ "lastname": "Peeters", "email": "[email protected]", "sign_page": 3, "sign_left": 2.5, "sign_bottom": 6 }

sign_left et sign_bottom indiquent le coin supérieur gauche de la signature. La signature est placée en dessous et à droite de ce point.

Les limites dépendent de la taille réelle de la page et de la taille du cachet visuel : toute la signature doit rester à au moins 2 cm de chaque bord de la page. Si plusieurs méthodes de signature sont acceptées, le plus grand cachet est pris en compte. Si une valeur est hors limites, le message d’erreur indique la plage autorisée pour cette page.

Une signature ne peut pas recouvrir une autre signature de la demande, ni une signature existante si le document est déjà signé.

8. L’objet demande de signature

Renvoyé par request, getRequest, cancel, skip, remind, delete et envoyé dans les callbacks.

Signataire

{
  "1": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "status": "signed",
    "signing_time": "2026-10-20 11:02:47",
    "signing_method": "itsme-qes-signature",
    "verified_firstname": "Ann",
    "verified_lastname": "Peeters"
  }
}

9. Autres endpoints

Tous les endpoints reçoivent userid dans l’URL et x-api-key dans les en-têtes. id_sign est passé dans l’URL.

Lister les demandes

status_id (facultatif) : pending, finished ou skipped. external_reference (facultatif) : uniquement les demandes ayant cette référence.

{
  "success": true,
  "result": [
    {
      "id_sign": 4521,
      "status_id": "pending",
      "external_reference": "QUOTE-2026-114"
    },
    {
      "id_sign": 4498,
      "status_id": "finished"
    }
  ]
}

Obtenir une demande

Renvoie l’objet demande de signature, avec le PDF signé une fois la demande terminée. Pour suivre l’état d’une demande, utilisez les callbacks plutôt que des appels répétés.

Envoyer un rappel

Envoie un email de rappel aux signataires status: pending du groupe actuellement invité (le groupe sign_first d’abord). Demande pending uniquement. Fonctionne aussi pour les demandes créées avec send_email: false.

Arrêter une demande (en gardant les signatures déjà faites)

Possible lorsqu’au moins un signataire a signé et qu’au moins un autre ne l’a pas fait. La demande devient skipped, le PDF partiellement signé est disponible et les crédits des signataires qui n’ont pas signé sont remboursés.

Annuler une demande

Possible tant que personne n’a signé ; pour terminer une demande partiellement signée, utilisez skip. La réponse contient la demande avec status_id: cancelled ; la demande et son document sont ensuite retirés de votre tableau de bord, les liens de signature ne fonctionnent plus et les crédits sont remboursés.

Supprimer une demande

Demandes finished ou skipped uniquement. Supprime les documents et la demande. La réponse contient la demande une dernière fois, avec status_id: deleted : téléchargez le PDF signé avant de supprimer.

Télécharger l’audit trail

Indisponible tant que la demande est en cours (HTTP 412). Renvoie l’objet demande avec audit_trail_base64 : un PDF retraçant l’historique de la demande (dates, méthodes, identités vérifiées).

Obtenir le solde de crédits

{ "success": true, "result": { "credits_balance": 38.4 } }

Lister les méthodes de signature

Méthodes acceptées dans methods, avec le prix en crédits par signataire pour votre compte. lang (facultatif) traduit les libellés.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "id": "evrotrust-signature",
      "label": "Evrotrust | QES",
      "credits": 1
    },
    {
      "id": "veriff-advanced-signature",
      "label": "Veriff | AES",
      "credits": 0.7
    },
    {
      "id": "otp-email-non-qualified",
      "label": "OTP by Email/SMS | SES",
      "credits": 0.4
    }
  ]
}

10. Callbacks (webhooks)

Définissez votre URL de callback dans Mon compte > Signatures API (HTTPS, accessible publiquement). Vous pouvez aussi définir une callback_url par demande. Le callback est un POST dont le corps JSON contient l’état complet actuel de la demande (même format que getRequest), envoyé pour les demandes créées via l’API.

Champs de l’événement

Types d’événements

Le corps contient toujours l’état complet actuel : votre intégration peut se baser sur status_id et sur le statut de chaque signataire plutôt que sur le seul type d’événement.

En-têtes

Vérifier la signature

Votre secret de signature est affiché dans Mon compte > Signatures API, où vous pouvez aussi le régénérer. v1 est le HMAC-SHA256 de "<t>.<raw request body>" avec votre secret, encodé en hexadécimal. Utilisez le corps brut, avant toute lecture JSON, et refusez les callbacks de plus de 5 minutes.

PHP

$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_ESIG_SIGNATURE'] ?? '';
preg_match( '/t=(\d+),v1=([a-f0-9]{64})/', $header, $m );
$valid = $m
    && abs( time() - (int) $m[1] ) <= 300
    && hash_equals( hash_hmac( 'sha256', $m[1] . '.' . $body, $secret ), $m[2] );

Node.js

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

C# (.NET)

using System.Security.Cryptography; using System.Text; using System.Text.RegularExpressions;
static bool Verify(string rawBody, string header, string secret) {
    var m = Regex.Match(header ?? "", @"t=(\d+),v1=([a-f0-9]{64})");
    if (!m.Success || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(m.Groups[1].Value)) > 300) return false;
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(m.Groups[1].Value + "." + rawBody))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(m.Groups[2].Value));
}

Réponses et nouveaux essais

• Répondez HTTP 2xx dès réception du callback, et traitez-le de manière asynchrone si nécessaire.
• En cas d’erreur réseau, de délai dépassé (30 s), de HTTP 429 ou 5xx, le callback est renvoyé toutes les heures avec le même event_id, jusqu’à 24 tentatives. Les autres réponses 4xx sont considérées comme définitives. Si la demande change à nouveau avant une livraison réussie, le callback suivant porte un nouvel événement et l’état complet actuel. L’état actuel reste disponible à tout moment via getRequest.
• Les redirections sont suivies (la méthode POST est conservée). localhost et les adresses privées ne peuvent pas être utilisés.

11. Erreurs

Les erreurs sont renvoyées avec "success": false et un message error lisible. Basez votre logique sur le code HTTP : les messages peuvent évoluer.

Erreurs par endpoint

Messages de validation à la création (request, HTTP 400)

Le message indique le champ ou le problème ; … représente une valeur de votre requête. Basez votre code sur le code HTTP, et affichez le message pour aider à corriger la requête.

12. Conservation

Les documents signés sont téléchargeables pendant 30 jours après la finalisation, via getRequest ou le callback request.completed. L’audit trail est conservé pendant la durée définie dans notre DPA. Archivez le document signé et l’audit trail de votre côté dans les 30 jours.

13. Changelog

API v3 — différences avec l’API v2

L’API v2 (https://api.e-signature.eu/v2/signature/) reste disponible et inchangée. Les endpoints, paramètres et l’authentification sont identiques dans les deux versions : pour passer à l’API v3, remplacez l’URL de base par https://api.e-signature.eu/v3/signature/. Vous pouvez migrer endpoint par endpoint.

Les anciennes URL (https://www.e-signature.eu/wp-json/signature/ pour l’API v2 et https://www.e-signature.eu/wp-json/esig/v3/signature/ pour l’API v3) restent valables. Nous recommandons d’utiliser les URL api.e-signature.eu.

Les callbacks suivent la version utilisée pour créer la demande : une demande créée avec l’API v2 continue de recevoir les callbacks de l’API v2.