Dazr Sign API: documentatie voor ontwikkelaars

Snel aan de slag

  1. Schakel de Dazr Sign API in. Open in het Sign-portaal Ontwikkelaars en kies Dazr Sign API inschakelen voor je app. Elke app van je organisatie staat daar en in de console van Dazr Identity, met dezelfde client-ID en hetzelfde secret; elke API schakel je apart in. Je kunt daar ook een nieuwe app registreren.
  2. Vraag de scope sign aan. Stuur mensen door de gebruikelijke flow van Inloggen met Dazr Identity met scope=openid sign (voeg offline_access toe voor een refresh token). Het toestemmingsscherm vermeldt dat je app namens hen documenten mag voorbereiden en ter ondertekening versturen, en de status ervan mag zien. Dit werkt met alleen de Dazr Sign API; wie ook gegevens van mensen vraagt (profile, email en de andere), heeft ook de Dazr Identity API nodig.
  3. Roep de API aan met het toegangstoken. Het basisadres is https://sign.dazr.eu/api/sign/v1. Stuur Authorization: Bearer <access token> en JSON.
  4. Maak een document en verstuur het. Upload een pdf met teksttags en een lijst ontvangers en verstuur het, of open de voorbereidingspop-up zodat de persoon zelf de velden plaatst.
// Node 18+: create a document from a PDF with text tags, then send it
import fs from 'node:fs';
const api = 'https://sign.dazr.eu/api/sign/v1';
const headers = { Authorization: 'Bearer ' + accessToken, 'Content-Type': 'application/json' };

let res = await fetch(api + '/documents', {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': 'order-1042' },
  body: JSON.stringify({
    title: 'Service agreement',
    file: fs.readFileSync('agreement.pdf').toString('base64'),
    recipients: [
      { name: 'Alex Example', email: 'alex@example.eu' },
      { name: 'Sam Client', email: 'sam@client.example' },
    ],
  }),
});
const { document } = await res.json();

res = await fetch(api + '/documents/' + document.id + '/send', { method: 'POST', headers });
console.log((await res.json()).document.status); // "sent"

Teksttags

Typ de velden als tekst in de pdf. Elke tag wordt vervangen door een veld van dezelfde grootte of groter, en de tagtekst wordt overschilderd, zodat ondertekenaars die nooit zien.

TagVeld
{{signature:1}}Handtekening van de eerste ontvanger
{{initials:2}}Paraaf van de tweede ontvanger
{{name:1}} {{date:1}}Naam en datum van ondertekening, ingevuld door Dazr Sign
{{text:2:Company}}Een tekstveld met het label Company
{{checkbox:2:Terms:optional}}Een optioneel selectievakje
{{company:1}}Bedrijfsnaam (ingevuld wanneer de persoon namens een organisatie tekent)

Het getal is de positie van de ontvanger in recipients, vanaf 1. Een tag voor een ontvanger die je niet hebt opgegeven, voegt een lege ontvanger toe, in te vullen in de voorbereidingspop-up. Stuur "text_tags": false om tags te negeren. Je kunt ook fields sturen met posities in punten (1/72 inch) vanaf de linkerbovenhoek van de pagina: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. Een value op een tekst-, bedrijfs- of selectievakveld legt het vast: de ondertekenaar ziet het en kan het niet wijzigen.

Maak een concept met "prepare": { "origin": "https://app.example.eu" } en je krijgt een prepare_url. Open die in een pop-up: de persoon plaatst ontvangers en velden in een compacte editor en klikt dan op Versturen of Opslaan als sjabloon. Voor een ondertekenaar die aan de beurt is, geeft POST /documents/{id}/recipients/{recipient_id}/signing_url een ondertekenpop-up. Beide links zijn 10 tot 15 minuten geldig en werken één keer. Zo nodig meldt de persoon zich in de pop-up aan bij Dazr Identity, met het adres waarnaar het document is verstuurd.

Als het klaar is, stuurt de pop-up { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } met postMessage naar de pagina die hem opende, alleen als die pagina op een van de pop-uporigins van je app staat (standaard de origins van je redirect-URI’s), en sluit dan. event is sent, saved, cancelled, signed of declined. Met redirect_uri (een van je geregistreerde redirect-URI’s) en state keert een pop-up die zijn opener kwijt is daarheen terug, met dezelfde waarden als queryparameters.

<script src="https://sign.dazr.eu/sdk.js"></script>
<script>
document.querySelector('#sign').addEventListener('click', async () => {
  // Ask your server for the URL after the click: the popup opens at once.
  const url = fetch('/my-server/prepare-url').then(r => r.json()).then(j => j.prepare_url);
  const result = await DazrSign.open(url);
  if (result.event === 'sent') showSent(result.document_id);
  // 'closed': the window was closed; check the status with the API or a webhook
});
</script>

Als je pagina Cross-Origin-Opener-Policy: same-origin stuurt, gebruik dan same-origin-allow-popups, anders kan de pop-up niets terugmelden.

Handtekeningen met ID-verificatie

Een ondertekenaar met niveau "simple" kan worden gevraagd om een handtekening met ID-verificatie, een geavanceerde elektronische handtekening volgens eIDAS: { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. Het staat uit tenzij je het instelt, en alleen voor ondertekenaars met niveau "simple" (anders 400 invalid_id_verified; een document kan het niet combineren met gekwalificeerde ondertekenaars: 400 id_verification_with_qualified). De ondertekenaar ondertekent zoals altijd en verifieert daarna de identiteit met Dazr Identity: een foto van het identiteitsbewijs en een selfie, beoordeeld door een medewerker van Dazr, of een bestaande verificatie, met toestemming. Sjablonen bewaren het per rol, en from_template accepteert id_verified per ontvanger.

De handtekening telt, en het document wordt pas compleet, zodra de verificatie is goedgekeurd. Tot dan blijft het document sent met waiting_for_id_verification true en zonder ondertekende pdf. Ontvangers hebben id_verified en id_verification: status (not_signed, to_verify, verifying, review, verified of rejected), verified_at en name_matches. Webhooks voegen sign.document.id_verified en sign.document.id_rejected toe. Na een afwijzing kan de afzender de ondertekenaar in het Sign-portaal vragen opnieuw te ondertekenen; de handtekening telt nooit in plaats daarvan als een eenvoudige.

Elke verificatie kost EUR 1,50 excl. btw van het tegoed van de organisatie van de app, afgeschreven wanneer de ondertekenaar die start of een bestaande gebruikt (één keer per verificatie en organisatie). send antwoordt 402 id_verification_payer als de app geen organisatie heeft en 402 id_verification_balance (met needCents) als het tegoed de ondertekenaars met ID-verificatie niet dekt.

Gekwalificeerde handtekeningen

Elke ondertekenaar heeft een level: "simple" (de standaard: een eenvoudige elektronische handtekening volgens eIDAS, met het e-mailadres bevestigd door in te loggen met Dazr Identity, een uitgebreide audittrail en een verzegelde pdf) of "qualified". "advanced", de naam van vóór 13 oktober 2026, wordt nog steeds geaccepteerd en betekent "simple"; antwoorden en webhooks zeggen "simple". Een gekwalificeerde ondertekenaar downloadt de pdf in Dazr Sign, ondertekent hem met zijn eigen gekwalificeerde elektronische handtekening (een elektronische identiteitskaart of een gekwalificeerd certificaat in Adobe Acrobat Reader) en uploadt het ondertekende bestand. Dazr Sign controleert dat tegen de Europese vertrouwenslijsten en accepteert het alleen als het een gekwalificeerde handtekening is op precies het bestand dat het uitgaf. Dazr geeft zelf geen certificaten uit.

Stel het niveau per ontvanger in: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Een gekwalificeerde ondertekenaar heeft geen paraafvelden. name_rule op het document bepaalt wat er gebeurt als de naam op het certificaat afwijkt van de naam van de ontvanger: "warn" (standaard: geaccepteerd, met name_matches false) of "block" (geweigerd). Sjablonen bewaren het niveau van elke rol, en from_template kan een rol verhogen naar "qualified".

Elke handtekening blijft geldig: latere handtekeningen en het afsluitende Dazr-zegel worden als incrementele updates toegevoegd, en de audittrail van zo’n document is een aparte verzegelde pdf op GET /documents/{id}/audit.pdf. Ontvangers in documenten en webhooks hebben level en, zodra een gekwalificeerde ondertekenaar heeft ondertekend, certificate: subject (common_name, given_name, surname, serial_number, country, organization, organization_identifier), issuer, serial, sha256, trust_service_provider, trusted_list_country, signing_time, trusted_timestamp, format (PAdES of CAdES) en name_matches. Elk ander level geeft 400 invalid_level.

Gekwalificeerde handtekeningen vereisen

Eigenaren en beheerders van een organisatie kunnen een gekwalificeerde elektronische handtekening vereisen van iedereen die ondertekent: voor de documenten die een app aanmaakt (de pagina van de app onder Ontwikkelaars in het Sign-portaal) of voor de documenten die leden van de organisatie versturen (Instellingen in het Sign-portaal). Dazr Sign dwingt dit af op de server. Een ondertekenaar zonder level ondertekent gekwalificeerd, "level": "simple" geeft 422 qualified_signature_required met de index van de ontvanger, rollen uit sjablonen worden gekwalificeerd (een eenvoudige rol vragen bij from_template geeft 400 qualified_signature_required), en een document wordt pas afgerond als de gekwalificeerde handtekening van elke ondertekenaar is gecontroleerd. Documenten tonen qes_required.

Certificaten via Dazr

Dazr geeft zelf geen certificaten uit, maar kan er een regelen bij een gekwalificeerde verlener van vertrouwensdiensten als die optie aanstaat. Dan laat "provider_allowed": true bij een gekwalificeerde ondertekenaar die er nog geen heeft, zo een gekwalificeerd certificaat krijgen. Die bevestigt bij de verlener wie hij is (identiteitsbewijs, videogesprek) en tekent daarna op de ondertekenpagina met een eenmalige code uit de app van de verlener. Dazr bewaart nooit ondertekengegevens: de apparaatnaam, pincode en eenmalige code gaan voor die ene handtekening naar de verlener. De ondertekende pdf wordt gecontroleerd zoals een upload. Het certificaat is 3 jaar van de ondertekenaar zelf en ondertekent latere Dazr-documenten zonder extra kosten. In certificate noemt issued_through de verlener (null voor een eigen certificaat van de ondertekenaar).

Deze optie staat nu niet aan: provider_allowed wordt geaccepteerd en heeft geen effect zolang dat zo is.

De ondertekenaar betaalt op de ondertekenpagina (standaard), of de organisatie van de app betaalt vooraf: "qes_payer": "organisation" op het document, of de instelling van de app. Dan antwoordt send met 402 payment_required met checkout_url (een betaalpagina) en amount (net, vat, total, certificates), en het document wordt verstuurd zodra de betaling binnen is (sign.document.sent). Een vooraf betaald certificaat dat niemand gebruikt, wordt terugbetaald als het document is afgerond, geannuleerd, geweigerd of verlopen. Documenten tonen qes_payer: "signer" of "organisation".

Webhooks

Stel in het Sign-portaal onder Ontwikkelaars een webhook-URL in voor je app. Je krijgt het ondertekeningssecret één keer te zien. Dazr Sign stuurt sign.document.sent, viewed, signed, completed, declined, voided en expired voor de documenten die je app heeft gemaakt, met de status van het document en van de ontvangers, nooit de inhoud. Mislukte leveringen worden opnieuw geprobeerd na 5 minuten, 30 minuten, 2, 6, 12 en 24 uur; het leveringslog toont elke poging en kan er een opnieuw versturen.

// Node: check the Dazr-Signature header (t=<unix time>,v1=<HMAC-SHA256 hex>)
import crypto from 'node:crypto';

export function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest();
  return crypto.timingSafeEqual(want, Buffer.from(m[2], 'hex'));
}
// The body: { id, type: 'sign.document.completed', created, data: { document: { id, status, recipients: [...] } } }

Naslag

Alle paden beginnen met https://sign.dazr.eu/api/sign/v1. Tijden zijn ISO 8601 in UTC.

VerzoekWat het doet
POST /documentsMaakt een concept van een pdf: file in base64, een multipart-upload (file plus data als JSON) of een upload_id. Optioneel: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateMaakt een concept van een sjabloon: template_id, recipients als { role, name, email }, values per veld-ID of label.
GET /documentsToont de documenten van je app voor deze persoon, nieuwste eerst: limit (tot 100), cursor, status.
GET /documents/{id}Het document met zijn status, ontvangers en velden.
POST /documents/{id}/sendVerstuurt een concept.
POST /documents/{id}/remindHerinnert de ondertekenaars die aan de beurt zijn (hooguit één keer per uur).
POST /documents/{id}/voidAnnuleert een document dat ter ondertekening uitstaat, met een optionele reason.
DELETE /documents/{id}Verwijdert een concept of een afgesloten document.
POST /documents/{id}/prepare_urlEen nieuwe voorbereidingspop-up voor een concept: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlEen ondertekenpop-up voor een ondertekenaar die aan de beurt is: origin, redirect_uri, state.
GET /documents/{id}/original.pdfDe pdf zoals hij is verstuurd.
GET /documents/{id}/signed.pdfDe verzegelde kopie, zodra iedereen heeft getekend.
GET /documents/{id}/audit.jsonDe audittrail: gebeurtenissen, hashes en ondertekenaars.
GET /documents/{id}/audit.pdfDe aparte, verzegelde audittrail van een document met gekwalificeerde ondertekenaars, zodra iedereen heeft ondertekend.
POST /uploadsStart een upload in delen voor pdf’s groter dan 4 MB: size. Daarna PUT /uploads/{upload_id}/parts/{n} met de ruwe bytes van elk deel.
GET /templatesDe sjablonen van de persoon, met hun rollen en velden.
GET /templates/{id}Eén sjabloon.
POST /templatesSlaat een van de documenten van je app op als sjabloon: document_id, name.
DELETE /templates/{id}Verwijdert een sjabloon.

Stuur een header Idempotency-Key mee wanneer je een document maakt: dezelfde sleutel en body binnen 24 uur geven hetzelfde document terug (header Idempotent-Replayed: true) in plaats van een tweede.

Fouten en limieten

Fouten hebben een HTTP-status en een body zoals { "error": { "code": "not_found", "message": "..." } }, soms met details zoals index.

StatusCodes
400invalid_field, invalid_recipients, invalid_email, not_pdf, pdf_unreadable, pdf_encrypted, invalid_origin, invalid_redirect_uri, unknown_role, unknown_field, invalid_provider_allowed, invalid_qes_payer, qualified_signature_required (from_template)
401unauthenticated, invalid_token (verlopen of ingetrokken, of de persoon heeft je app verwijderd)
402payment_required, met checkout_url en amount
403insufficient_scope, sign_api_disabled
404not_found (ook voor documenten die je app niet heeft gemaakt), template_not_found
409not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress, payment_in_progress
413pdf_too_large, too_large, quota
422idempotency_key_reused, qualified_signature_required (een ondertekenaar met level simple terwijl gekwalificeerde handtekeningen vereist zijn)
429rate_limited, met een header Retry-After
502payment_unavailable

Een app overdragen

Een app kan naar een andere organisatie op Dazr verhuizen, via App overdragen in de instellingen van de app. Met de Dazr Sign API aan kan dat alleen naar een geverifieerde organisatie, en een eigenaar of beheerder daar moet binnen 14 dagen accepteren. De ontwikkelaarsdocumentatie van Dazr Identity beschrijft elke stap.