API REST e-Signature.eu — recommandé électronique

1. Présentation

L’API REST d’e-Signature.eu permet à votre application d’envoyer des recommandés électroniques sans passer par notre site. Vous envoyez le PDF, une adresse expéditeur vérifiée et le destinataire ; le document reçoit un horodatage électronique qualifié, et le destinataire signe un accusé de réception après avoir vérifié son identité. Vous récupérez le résultat via l’API ou un callback.

L’ancienne URL de base https://www.e-signature.eu/wp-json/esig/v3/regis/ reste valable. Nous recommandons d’utiliser l’URL api.e-signature.eu.

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/regis/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’un recommandé

1. Vous envoyez le PDF, une adresse expéditeur vérifiée et le destinataire. Le document reçoit un horodatage électronique qualifié et les crédits sont débités.
2. Le destinataire reçoit un email avec deux liens : l’un pour signer l’accusé de réception et accéder au document, l’autre pour refuser.
3. Pour signer, le destinataire vérifie son identité avec l’une des méthodes acceptées (itsme®, Evrotrust, OTP…).
4. Le recommandé devient finished (signé), declined (refusé), ou expired sans réaction après 14 jours.

Un expéditeur, un destinataire par recommandé. Comme sur le site, un rappel automatique est envoyé tous les 4 jours (non paramétrable) ; il n’y a ni rappel manuel ni annulation.

6. Adresse expéditeur

Comme sur le site, l’adresse expéditeur (sender_email) doit être vérifiée avant de pouvoir être utilisée :

1. Appelez verifySender : un email avec un lien de vérification est envoyé à l’adresse (réponse 202). Si l’adresse est déjà vérifiée, la réponse est 200 avec "verified": true.
2. Le titulaire de l’adresse clique sur le lien.
3. L’adresse peut alors être utilisée dans request.

{ "email": "[email protected]", "lang": "en" }

{
  "success": true,
  "result": {
    "email": "[email protected]",
    "verified": false,
    "message": "A verification email has been sent to [email protected]. The address can be used as sender_email once the link in this email has been clicked."
  }
}

Liste les adresses expéditeur de votre compte avec leur état.

{
  "success": true,
  "result": [
    {
      "email": "[email protected]",
      "verified": true
    },
    {
      "email": "[email protected]",
      "verified": false
    }
  ]
}

7. Envoyer un recommandé

{
  "title": "Formal notice rent October",
  "lang": "en",
  "sender_email": "[email protected]",
  "recipient": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "phone": "+32475111222"
  },
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "send_email": true,
  "note_html": "Please acknowledge receipt.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "INV-2026-0042",
  "metadata": {
    "customer_id": 311
  },
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Coût

Prix de la méthode la plus chère de methods, pour un destinataire. Débité à la création du recommandé.

Réponse 201 Created

{
  "success": true,
  "result": {
    "type": "regis",
    "id_sign": 123,
    "doc_name": "Formal-notice-rent-October",
    "lang": "en",
    "sender_email": "[email protected]",
    "status_id": "pending",
    "date_added": "2026-10-20 11:50:00",
    "date_status": "2026-10-20 11:50:00",
    "date_expired": "2026-11-03 11:50:00",
    "timezone": "Europe/Brussels",
    "methods": [
      "itsme-qes-signature",
      "evrotrust-signature"
    ],
    "reminder": 4,
    "last_reminder": null,
    "send_email": true,
    "from_api": true,
    "credits": 1,
    "credits_balance": 41,
    "recipient": {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "status": "pending",
      "signing_time": "",
      "signing_method": "",
      "verified_firstname": "",
      "verified_lastname": "",
      "signature_link": "https://www.e-signature.eu/en/sign-regis/?key=…",
      "declined_link": "https://www.e-signature.eu/en/sign-regis/?key=…"
    },
    "external_reference": "INV-2026-0042",
    "metadata": {
      "customer_id": 311
    }
  }
}

8. L’objet recommandé

Renvoyé par request, getRequest, modifyRecipient, delete et envoyé dans les callbacks. Le champ "type": "regis" le distingue d’une demande de signature lorsque les deux utilisent la même URL de callback.

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 recommandés

status_id (facultatif) : pending, finished, declined ou expired. external_reference (facultatif) : uniquement les recommandés ayant cette référence.

{
  "success": true,
  "result": [
    {
      "id_sign": 123,
      "status_id": "pending",
      "doc_name": "Formal-notice-rent-October",
      "date_added": "2026-10-20 11:50:00",
      "external_reference": "INV-2026-0042"
    }
  ]
}

Obtenir un recommandé

Modifier le destinataire

{ "email": "[email protected]", "phone": "+32475333444" }

Recommandé pending uniquement. Envoyez seulement les champs à modifier parmi firstname, lastname, email, phone. Si l’email change, l’ancien destinataire est informé de l’annulation et le nouveau reçoit le recommandé.

Supprimer un recommandé

Statut finished, declined ou expired uniquement. Supprime les fichiers et l’historique ; la réponse contient le recommandé une dernière fois (status_id: deleted) : téléchargez les documents avant de supprimer.

Télécharger l’audit trail

Indisponible tant qu’il est en attente. Renvoie le recommandé avec audit_trail_base64 : un PDF horodaté avec l’historique complet.

Obtenir le solde de crédits

Lister les méthodes

Méthodes acceptées dans methods pour le recommandé, avec le prix pour votre compte. La liste peut différer de celle de l’API des signatures.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "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.

Emails non délivrés

Lorsqu’un email envoyé par e-Signature.eu à un signataire (ou au destinataire d’un recommandé) est renvoyé par son serveur de messagerie (adresse inconnue, boîte pleine, serveur qui refuse le message…), vous recevez le callback signer.email_failed. Le statut de la demande et du signataire ne change pas.

Corrigez l’adresse avec modifySigner (demande de signature) ou modifyRecipient (recommandé) : l’invitation est envoyée à la nouvelle adresse, et aucun email d’annulation n’est envoyé à l’adresse en erreur. Le titulaire du compte est aussi prévenu par email, et le signataire est signalé Email non délivré dans le tableau de bord en ligne.

permanent : plus aucun email n’est envoyé à cette adresse pour cette demande (rappels compris) jusqu’à sa correction. transient ou undetermined : les emails ne sont pas bloqués ; le prochain rappel part normalement et, s’il échoue à nouveau, vous recevez un nouveau callback signer.email_failed.

Seules les demandes en cours et les signataires qui n’ont pas encore signé sont concernés. Avec send_email: false, e-Signature.eu n’envoie aucun email aux signataires : cet événement ne se produit donc pas.

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.

Pour le recommandé, le callback est envoyé quand l’accusé est signé, refusé ou expiré, à chaque rappel automatique et quand le destinataire est modifié (sur le site ou via l’API). Le destinataire correspond à signer_key 1 dans changes.

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.

12. Conservation

Le document horodaté et l’accusé de réception signé sont téléchargeables pendant 30 jours, via getRequest ou le callback. L’audit trail est conservé pendant la durée définie dans notre DPA. Archivez les documents de votre côté dans les 30 jours.