REST API van e-Signature.eu — elektronische aangetekende zending

1. Overzicht

Met de REST API van e-Signature.eu verstuurt uw applicatie elektronische aangetekende zendingen zonder via onze website te gaan. U stuurt de pdf, een geverifieerd afzenderadres en de ontvanger; het document krijgt een gekwalificeerde elektronische tijdstempel en de ontvanger ondertekent een ontvangstbewijs na controle van zijn identiteit. U ontvangt het resultaat via de API of een callback.

De vorige basis-URL https://www.e-signature.eu/wp-json/esig/v3/regis/ blijft geldig. We raden aan de URL van api.e-signature.eu te gebruiken.

2. Authenticatie

Uw gegevens staan in Mijn account > API-handtekeningen zodra u bent aangemeld op e-signature.eu:

• User ID: in de URL, als parameter userid van elke oproep;
• API token: in de HTTP-header x-api-key van elke oproep.

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

Houd uw token geheim: het geeft via de API volledige toegang tot uw account. Oproepen moeten vanaf uw server gebeuren, nooit vanuit een browser of mobiele app.

3. Conventies

Verzoeken en antwoorden

• Alleen HTTPS. De request bodies zijn JSON (Content-Type: application/json).
• Elk antwoord is JSON, in een van deze twee vormen:

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

Limieten

4. Credits

Aanvragen worden betaald met uw prepaid credits van e-signature.eu. De prijs van een methode vraagt u op met getMethods (uw specifieke prijzen worden meegerekend). Uw saldo staat in requestBalance en in elk aanvraagobject (credits_balance).

Automatisch opladen van credits

Om nooit zonder credits te vallen, kan uw account zich automatisch opladen. Dit stelt u één keer in via Mijn account > API-handtekeningen, niet via de API:

1. Kies een drempel (in credits) en het te bestellen creditpakket.
2. Sla een betaalmethode op bij onze betaalprovider Mollie (kaart, of SEPA-domiciliëring via Bancontact, iDEAL…). Eén keer wordt een verificatiebetaling van € 0,01 gevraagd.
3. Telkens wanneer credits worden afgeschreven en uw saldo onder de drempel zakt, wordt een bestelling van het gekozen pakket aangemaakt en automatisch betaald met de opgeslagen betaalmethode. De factuur wordt u per e-mail bezorgd.

5. Hoe een aangetekende zending werkt

1. U stuurt de pdf, een geverifieerd afzenderadres en de ontvanger. Het document krijgt een gekwalificeerde elektronische tijdstempel en de credits worden afgeschreven.
2. De ontvanger krijgt een e-mail met twee links: één om het ontvangstbewijs te ondertekenen en het document te openen, één om te weigeren.
3. Om te ondertekenen bevestigt de ontvanger zijn identiteit met een van de toegelaten methoden (itsme®, Evrotrust, OTP…).
4. De aangetekende zending wordt finished (ondertekend), declined (geweigerd), of expired als er na 14 dagen niets is gebeurd.

Eén afzender en één ontvanger per aangetekende zending. Zoals op de website wordt om de 4 dagen een automatische herinnering verstuurd (niet instelbaar); er is geen manuele herinnering en geen annulering.

6. Afzenderadres

Zoals op de website moet het afzenderadres (sender_email) eerst geverifieerd zijn:

1. Roep verifySender op: er wordt een e-mail met een verificatielink naar het adres gestuurd (antwoord 202). Is het adres al geverifieerd, dan is het antwoord 200 met "verified": true.
2. De eigenaar van het adres klikt op de link.
3. Het adres kan dan worden gebruikt in 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."
  }
}

Geeft de afzenderadressen van uw account met hun status.

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

7. Een aangetekende zending versturen

{
  "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..."
}

Kosten

Prijs van de duurste methode in methods, voor één ontvanger. Afgeschreven bij het aanmaken van de aangetekende zending.

Antwoord 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. Het object aangetekende zending

Teruggegeven door request, getRequest, modifyRecipient, delete en verstuurd in de callbacks. Het veld "type": "regis" onderscheidt het van een ondertekeningsaanvraag als beide dezelfde callback-URL gebruiken.

9. Andere endpoints

Alle endpoints krijgen userid in de URL en x-api-key in de headers. id_sign wordt in de URL meegegeven.

De aangetekende zendingen oplijsten

status_id (optioneel): pending, finished, declined of expired. external_reference (optioneel): alleen de zendingen met deze referentie.

{
  "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"
    }
  ]
}

Een aangetekende zending opvragen

De ontvanger wijzigen

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

Alleen voor zendingen pending. Stuur enkel de te wijzigen velden mee uit firstname, lastname, email, phone. Wijzigt het e-mailadres, dan wordt de vorige ontvanger op de hoogte gebracht van de annulering en ontvangt de nieuwe ontvanger de zending.

Een aangetekende zending verwijderen

Alleen status finished, declined of expired. Verwijdert de bestanden en de geschiedenis; het antwoord bevat de zending nog één keer (status_id: deleted): download de documenten vóór het verwijderen.

De audit trail downloaden

Niet beschikbaar zolang de zending openstaat. Geeft de zending terug met audit_trail_base64: een pdf met tijdstempel en de volledige geschiedenis.

Het creditsaldo opvragen

De methoden oplijsten

Methoden toegelaten in methods voor aangetekende zendingen, met de prijs voor uw account. De lijst kan verschillen van die van de handtekening-API.

{
  "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)

Stel uw callback-URL in via Mijn account > API-handtekeningen (HTTPS, publiek bereikbaar). U kunt ook per aanvraag een callback_url opgeven. De callback is een POST met een JSON-body met de volledige huidige status van de aanvraag (zelfde formaat als getRequest), verstuurd voor aanvragen die via de API zijn aangemaakt.

Eventvelden

Types events

De body bevat altijd de volledige huidige status: uw integratie kan steunen op status_id en de status van elke ondertekenaar, niet alleen op het type event.

Niet-afgeleverde e-mails

Wanneer een e-mail die e-Signature.eu naar een ondertekenaar (of naar de ontvanger van een aangetekende zending) stuurt, door diens mailserver wordt teruggestuurd (onbekend adres, volle mailbox, server die het bericht weigert…), ontvangt u de callback signer.email_failed. De status van de aanvraag en van de ondertekenaar verandert niet.

Corrigeer het adres met modifySigner (ondertekeningsaanvraag) of modifyRecipient (aangetekende zending): de uitnodiging wordt naar het nieuwe adres verstuurd en er wordt geen annuleringsmail naar het foutieve adres gestuurd. De accounthouder wordt ook per e-mail verwittigd, en de ondertekenaar wordt in het online dashboard gemarkeerd met E-mail niet afgeleverd.

permanent: er worden voor deze aanvraag geen e-mails meer naar dit adres gestuurd (ook geen herinneringen) tot het gecorrigeerd is. transient of undetermined: e-mails worden niet geblokkeerd; de volgende herinnering wordt normaal verstuurd en als die opnieuw mislukt, ontvangt u een nieuwe callback signer.email_failed.

Alleen lopende aanvragen en ondertekenaars die nog niet ondertekend hebben zijn betrokken. Met send_email: false stuurt e-Signature.eu geen e-mail naar de ondertekenaars, dus deze gebeurtenis doet zich niet voor.

Headers

De handtekening controleren

Uw ondertekeningsgeheim staat in Mijn account > API-handtekeningen, waar u het ook opnieuw kunt aanmaken. v1 is de HMAC-SHA256 van "<t>.<raw request body>" met uw geheim, hexadecimaal gecodeerd. Gebruik de ruwe body, vóór elke JSON-verwerking, en weiger callbacks ouder dan 5 minuten.

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));
}

Antwoorden en nieuwe pogingen

• Antwoord met HTTP 2xx zodra de callback is ontvangen en verwerk hem zo nodig asynchroon.
• Bij een netwerkfout, time-out (30 s), HTTP 429 of 5xx wordt de callback elk uur opnieuw verstuurd met hetzelfde event_id, tot 24 pogingen. Andere 4xx-antwoorden gelden als definitief. Wijzigt de aanvraag opnieuw vóór een geslaagde levering, dan bevat de volgende callback een nieuw event en de volledige huidige status. De huidige status blijft altijd beschikbaar via getRequest.
• Doorverwijzingen worden gevolgd (de methode POST blijft behouden). localhost en privé-adressen kunnen niet worden gebruikt.

Voor aangetekende zendingen wordt de callback verstuurd wanneer het ontvangstbewijs is ondertekend, geweigerd of verlopen, bij elke automatische herinnering en wanneer de ontvanger wordt gewijzigd (op de website of via de API). De ontvanger is signer_key 1 in changes.

11. Fouten

Fouten worden teruggegeven met "success": false en een leesbaar bericht error. Baseer uw logica op de HTTP-code: de berichten kunnen worden verbeterd.

12. Bewaring

Het document met tijdstempel en het ondertekende ontvangstbewijs kunnen 30 dagen worden gedownload, via getRequest of de callback. De audit trail wordt bewaard gedurende de periode vastgelegd in onze DPA. Archiveer de documenten binnen 30 dagen aan uw kant.