Dazr Sign API: documentatie voor ontwikkelaars
Bereid documenten voor en verstuur ze ter ondertekening vanuit je eigen software, namens de mensen die deze gebruiken. Ondertekenaars tekenen zoals altijd met Dazr Sign: aangemeld met Dazr Identity, op hun beurt, één keer.
- Snel aan de slag
- Teksttags
- Pop-ups
- Handtekeningen met ID-verificatie
- Gekwalificeerde handtekeningen
- Gekwalificeerde handtekeningen vereisen
- Certificaten via Dazr
- Webhooks
- Naslag
- Fouten en limieten
- Overdrachten
Snel aan de slag
- 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.
- Vraag de scope
signaan. Stuur mensen door de gebruikelijke flow van Inloggen met Dazr Identity metscope=openid sign(voegoffline_accesstoe 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,emailen de andere), heeft ook de Dazr Identity API nodig. - Roep de API aan met het toegangstoken. Het basisadres is
https://sign.dazr.eu/api/sign/v1. StuurAuthorization: Bearer <access token>en JSON. - 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.
| Tag | Veld |
|---|---|
{{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.
Pop-ups: voorbereiden en ondertekenen
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.
| Verzoek | Wat het doet |
|---|---|
POST /documents | Maakt 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_template | Maakt een concept van een sjabloon: template_id, recipients als { role, name, email }, values per veld-ID of label. |
GET /documents | Toont 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}/send | Verstuurt een concept. |
POST /documents/{id}/remind | Herinnert de ondertekenaars die aan de beurt zijn (hooguit één keer per uur). |
POST /documents/{id}/void | Annuleert een document dat ter ondertekening uitstaat, met een optionele reason. |
DELETE /documents/{id} | Verwijdert een concept of een afgesloten document. |
POST /documents/{id}/prepare_url | Een nieuwe voorbereidingspop-up voor een concept: origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | Een ondertekenpop-up voor een ondertekenaar die aan de beurt is: origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | De pdf zoals hij is verstuurd. |
GET /documents/{id}/signed.pdf | De verzegelde kopie, zodra iedereen heeft getekend. |
GET /documents/{id}/audit.json | De audittrail: gebeurtenissen, hashes en ondertekenaars. |
GET /documents/{id}/audit.pdf | De aparte, verzegelde audittrail van een document met gekwalificeerde ondertekenaars, zodra iedereen heeft ondertekend. |
POST /uploads | Start 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 /templates | De sjablonen van de persoon, met hun rollen en velden. |
GET /templates/{id} | Eén sjabloon. |
POST /templates | Slaat 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.
| Status | Codes |
|---|---|
400 | invalid_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) |
401 | unauthenticated, invalid_token (verlopen of ingetrokken, of de persoon heeft je app verwijderd) |
402 | payment_required, met checkout_url en amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (ook voor documenten die je app niet heeft gemaakt), template_not_found |
409 | not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress, payment_in_progress |
413 | pdf_too_large, too_large, quota |
422 | idempotency_key_reused, qualified_signature_required (een ondertekenaar met level simple terwijl gekwalificeerde handtekeningen vereist zijn) |
429 | rate_limited, met een header Retry-After |
502 | payment_unavailable |
- Pdf’s tot 25 MB en 200 pagina’s, zonder wachtwoord. Verzoeken tot 4 MB; grotere pdf’s gaan via
/uploads. - Tot 20 ontvangers en 400 velden per document, 100 sjablonen per persoon. Documenten en sjablonen tellen mee voor de Dazr-opslag van de persoon.
- 120 verzoeken per minuut per persoon per app, 30 nieuwe documenten per 10 minuten en 30 verzendingen per uur.
- Toegangstokens zijn 10 minuten geldig. Gebruik het refresh token (
offline_access) om een nieuw te krijgen.
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.
- Documenten die je app vóór de overdracht heeft gemaakt, blijven bij de mensen van wie ze zijn. De app ziet ze niet meer via de API en er worden geen webhooks meer voor verstuurd.
- De webhook-URL en de pop-up-origins blijven. Het ondertekeningsgeheim voor webhooks wordt vernieuwd en één keer getoond aan wie accepteert.
- Toegangstokens en refresh-tokens van vóór de overdracht werken niet meer, en mensen geven bij hun volgende keer inloggen opnieuw toestemming. Sjablonen zijn van mensen en veranderen niet.
- Aantallen documenten in het Sign-portaal beginnen opnieuw bij de overdracht.