REST API van e-Signature.eu — elektronische handtekeningen (SES, AES, QES)

1. Overzicht

Met de REST API van e-Signature.eu verstuurt uw applicatie documenten ter elektronische ondertekening (eenvoudig SES, geavanceerd AES of gekwalificeerd QES volgens eIDAS) zonder via onze website te gaan. U stuurt de pdf en de ondertekenaars; wij verzorgen de identiteitscontrole, de ondertekening en de opvolging; u ontvangt het ondertekende document via de API of een callback.

Deze documentatie beschrijft API v3. Gebruikt u al API v2 (https://api.e-signature.eu/v2/signature/)? Zie de Changelog.

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/signature/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 ondertekeningsaanvraag werkt

1. U maakt de aanvraag aan met de pdf, de ondertekenaars en de toegelaten ondertekeningsmethoden. De credits worden afgeschreven.
2. Elke ondertekenaar ontvangt een e-mail met een persoonlijke ondertekeningslink (of u bezorgt zelf de signature_link wanneer send_email false is).
3. De ondertekenaar bevestigt zijn identiteit met een van de toegelaten methoden (itsme®, Evrotrust, Veriff, OTP…) en ondertekent.
4. Wanneer iedereen heeft ondertekend, is de aanvraag finished: de ondertekende pdf (PAdES) is beschikbaar via getRequest en wordt meegestuurd in de callback.

Volgorde van ondertekening

Standaard ondertekenen alle ondertekenaars parallel. Om een volgorde vast te leggen, zet u sign_first: true bij de ondertekenaars van de eerste groep: zij worden meteen uitgenodigd, eventueel met meerderen tegelijk. De andere ondertekenaars worden pas uitgenodigd wanneer de hele eerste groep heeft ondertekend. Maximaal twee groepen.

Twee integratiemodi

Vraag de API niet herhaaldelijk op

Roep getRequest niet herhaaldelijk op om de status van een aanvraag te volgen: gebruik de callbacks, die automatisch bij elke wijziging worden verstuurd. Te veel oproepen activeren een automatische beperking die de verwerking van uw verzoeken tijdelijk opschort.

6. Een ondertekeningsaanvraag aanmaken

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

Ondertekeningsmethoden

Dit zijn de standaardprijzen: getMethods geeft de beschikbare methoden en de prijzen voor uw account. Alleen een gekwalificeerde elektronische handtekening (QES) is volgens de eIDAS-verordening wettelijk gelijkwaardig aan een handgeschreven handtekening. otp-email-non-qualified dekt e-mail en sms: de code wordt per sms verstuurd als de ondertekenaar een phone heeft, anders per e-mail, tegen dezelfde prijs.

Velden van de request body

Velden van een ondertekenaar

Kosten

Prijs van de duurste methode in methods × aantal ondertekenaars. De credits worden afgeschreven bij het aanmaken van de aanvraag. De credits van ondertekenaars die niet hebben ondertekend, worden terugbetaald als de aanvraag wordt geannuleerd of stopgezet.

Antwoord 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. Plaatsing van de handtekeningen

position_auto (standaard)

Plaats de markeringen #SIG01, #SIG02… (ook toegestaan: #SIG01#) als tekst in uw document, op de plaats waar elke ondertekenaar moet tekenen (#SIG01 = eerste ondertekenaar van de array signers). De handtekening wordt linksboven de markering geplaatst. Komt dezelfde markering meerdere keren voor, dan geldt de eerste. Een markering wordt overgeslagen als haar handtekeningzone een reeds geplaatste (of bestaande) handtekening zou bedekken: de ondertekenaar krijgt dan de volgende vrije markering. Een markering zo dicht bij de paginarand dat de handtekening moet worden verschoven, wordt alleen in laatste instantie gebruikt.

Document nog niet ondertekend

Bevat het document geen markering, of ontbreekt de markering van een ondertekenaar, dan wordt aan het einde van het document een handtekeningenpagina met de markeringen toegevoegd en worden alle handtekeningen op die pagina geplaatst (6 ondertekenaars op de eerste toegevoegde pagina, daarna 10 per extra pagina).

Document al ondertekend

Aan een pdf die al elektronisch is ondertekend, kan geen pagina worden toegevoegd: dat zou de bestaande handtekeningen ongeldig maken. Met position_auto worden de handtekeningen op de vrije markeringen geplaatst, d.w.z. de markeringen waarvan de handtekeningzone geen bestaande handtekening bedekt. Vrije markeringen worden in volgorde aan de ondertekenaars toegewezen (#SIG01, #SIG02…).

position_manual

Geef voor elke ondertekenaar de positie van de handtekening op, in centimeter:

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

sign_left en sign_bottom geven de linkerbovenhoek van de handtekening. De handtekening wordt onder en rechts van dit punt geplaatst.

De limieten hangen af van de werkelijke grootte van de pagina en van de grootte van de visuele stempel: de volledige handtekening moet minstens 2 cm van elke rand van de pagina blijven. Zijn er meerdere ondertekeningsmethoden toegelaten, dan geldt de grootste stempel. Valt een waarde buiten de limieten, dan vermeldt de foutmelding het toegestane bereik voor die pagina.

Een handtekening mag geen andere handtekening van de aanvraag bedekken, noch een bestaande handtekening als het document al ondertekend is.

8. Het object ondertekeningsaanvraag

Teruggegeven door request, getRequest, cancel, skip, remind, delete en verstuurd in de callbacks.

Ondertekenaar

{
  "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. Andere endpoints

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

De aanvragen oplijsten

status_id (optioneel): pending, finished of skipped. external_reference (optioneel): alleen de aanvragen met deze referentie.

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

Een aanvraag opvragen

Geeft het object ondertekeningsaanvraag terug, met de ondertekende pdf zodra de aanvraag is afgerond. Gebruik de callbacks om de status te volgen, niet herhaalde oproepen.

Een herinnering sturen

Stuurt een herinneringsmail naar de ondertekenaars met status: pending van de groep die momenteel is uitgenodigd (eerst de groep sign_first). Alleen voor aanvragen pending. Werkt ook voor aanvragen aangemaakt met send_email: false.

Een aanvraag stopzetten (met behoud van de reeds geplaatste handtekeningen)

Mogelijk wanneer minstens één ondertekenaar heeft ondertekend en minstens één nog niet. De aanvraag wordt skipped, de gedeeltelijk ondertekende pdf is beschikbaar en de credits van de niet-ondertekenaars worden terugbetaald.

Een aanvraag annuleren

Mogelijk zolang niemand heeft ondertekend; gebruik skip om een gedeeltelijk ondertekende aanvraag af te sluiten. Het antwoord bevat de aanvraag met status_id: cancelled; daarna worden de aanvraag en het document uit uw dashboard verwijderd, werken de ondertekeningslinks niet meer en worden de credits terugbetaald.

Een aanvraag verwijderen

Alleen aanvragen finished of skipped. Verwijdert de documenten en de aanvraag. Het antwoord bevat de aanvraag nog één keer, met status_id: deleted: download de ondertekende pdf vóór het verwijderen.

De audit trail downloaden

Niet beschikbaar zolang de aanvraag loopt (HTTP 412). Geeft het aanvraagobject terug met audit_trail_base64: een pdf met de geschiedenis van de aanvraag (data, methoden, gecontroleerde identiteiten).

Het creditsaldo opvragen

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

De ondertekeningsmethoden oplijsten

Methoden toegelaten in methods, met de prijs in credits per ondertekenaar voor uw account. lang (optioneel) vertaalt de labels.

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

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.

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.

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.

Fouten per endpoint

Validatieberichten bij het aanmaken (request, HTTP 400)

Het bericht noemt het veld of het probleem; … staat voor een waarde uit uw verzoek. Baseer uw code op de HTTP-code en toon het bericht om het verzoek te helpen corrigeren.

12. Bewaring

Ondertekende documenten kunnen gedurende 30 dagen na afronding worden gedownload, via getRequest of de callback request.completed. De audit trail wordt bewaard gedurende de periode vastgelegd in onze DPA. Archiveer het ondertekende document en de audit trail binnen 30 dagen aan uw kant.

13. Changelog

API v3 — verschillen met API v2

API v2 (https://api.e-signature.eu/v2/signature/) blijft beschikbaar en ongewijzigd. Endpoints, parameters en authenticatie zijn in beide versies identiek: om over te stappen op API v3 vervangt u de basis-URL door https://api.e-signature.eu/v3/signature/. U kunt endpoint per endpoint overstappen.

De vorige URL’s (https://www.e-signature.eu/wp-json/signature/ voor API v2 en https://www.e-signature.eu/wp-json/esig/v3/signature/ voor API v3) blijven geldig. We raden aan de URL’s van api.e-signature.eu te gebruiken.

Callbacks volgen de versie waarmee de aanvraag is aangemaakt: een aanvraag via API v2 blijft callbacks van API v2 ontvangen.