Dazr Sign-API: utviklerdokumentasjon
Klargjør og send dokumenter til signering fra din egen programvare, i navnet til dem som bruker den. Signatarer signerer med Dazr Sign som vanlig: innlogget med Dazr Identity, etter tur, én gang.
- Hurtigstart
- Teksttagger
- Popup-vinduer
- Signaturer med ID-kontroll
- Kvalifiserte signaturer
- Krav om kvalifiserte signaturer
- Sertifikater gjennom Dazr
- Webhooks
- Referanse
- Feil og begrensninger
- Overføringer
Hurtigstart
- Aktiver Dazr Sign-API-et. I Sign-portalen åpner du Utviklere og velger Aktiver Dazr Sign-API for appen din. Alle apper i organisasjonen din står der og i Dazr Identity-konsollen, med samme klient-ID og hemmelighet; hvert API aktiveres for seg. Du kan også registrere en ny app der.
- Be om omfanget
sign. Send folk gjennom den vanlige flyten for innlogging med Dazr Identity medscope=openid sign(legg tiloffline_accessfor et oppdateringstoken). Samtykkeskjermen sier at appen din kan klargjøre og sende dokumenter til signering i deres navn, og se statusen. Dette fungerer med Dazr Sign-API-et alene; skal du også be om folks data (profile,emailog de andre), må Dazr Identity-API-et også være aktivert. - Kall API-et med tilgangstokenet. Grunnadressen er
https://sign.dazr.eu/api/sign/v1. SendAuthorization: Bearer <access token>og JSON. - Opprett og send et dokument. Last opp en PDF med teksttagger og en liste over mottakere, og send den, eller åpne klargjøringsvinduet så personen plasserer feltene.
// 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"
Teksttagger
Skriv feltene inn i PDF-en som tekst. Hver tagg erstattes av et felt av samme størrelse eller større, og taggteksten males over, så signatarer ser den aldri.
| Tagg | Felt |
|---|---|
{{signature:1}} | Signaturen til første mottaker |
{{initials:2}} | Initialene til andre mottaker |
{{name:1}} {{date:1}} | Navn og signeringsdato, fylt ut av Dazr Sign |
{{text:2:Company}} | Et tekstfelt med etiketten Company |
{{checkbox:2:Terms:optional}} | En valgfri avkrysningsboks |
{{company:1}} | Firmanavn (fylt ut når personen signerer på vegne av en organisasjon) |
Tallet er mottakerens plass i recipients, fra 1. En tagg for en mottaker du ikke har oppført, legger til en tom mottaker, som fylles ut i klargjøringsvinduet. Send "text_tags": false for å se bort fra tagger. Du kan også sende fields med posisjoner i punkter (1/72 tomme) fra øvre venstre hjørne av siden: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. En value på et tekst-, firma- eller avkrysningsfelt låser det: signataren ser det og kan ikke endre det.
Popup-vinduer: klargjøring og signering
Opprett et utkast med "prepare": { "origin": "https://app.example.eu" }, så får du en prepare_url. Åpne den i et popup-vindu: personen plasserer mottakere og felt i et kompakt redigeringsprogram og klikker deretter Send eller Lagre som mal. For en signatar som står for tur, gir POST /documents/{id}/recipients/{recipient_id}/signing_url et signeringsvindu. Begge lenkene er gyldige i 10 til 15 minutter og virker én gang. Personen logger inn med Dazr Identity inne i popup-vinduet om nødvendig, med adressen dokumentet ble sendt til.
Når det er ferdig, sender popup-vinduet { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } med postMessage til siden som åpnet det, bare hvis den siden er på en av appens popup-opprinnelser (som standard opprinnelsene til omdirigerings-URI-ene dine), og lukkes. event er sent, saved, cancelled, signed eller declined. Med redirect_uri (en av de registrerte omdirigerings-URI-ene dine) og state går et popup-vindu som har mistet siden som åpnet det, tilbake dit med de samme verdiene som spørreparametere.
<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>
Hvis siden din sender Cross-Origin-Opener-Policy: same-origin, bruk same-origin-allow-popups i stedet, ellers kan ikke popup-vinduet rapportere tilbake.
Signaturer med ID-kontroll
En person med nivået "simple" kan bli bedt om en signatur med ID-kontroll, en avansert elektronisk signatur etter eIDAS: { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. Den er av med mindre du angir den, og bare for personer med nivået "simple" (ellers 400 invalid_id_verified; et dokument kan ikke blande den med kvalifiserte signerende: 400 id_verification_with_qualified). Personen signerer som vanlig og får deretter identiteten verifisert med Dazr Identity: et bilde av ID-dokumentet og en selfie som en person hos Dazr gjennomgår, eller en verifisering personen allerede har, med samtykke. Maler beholder den per rolle, og from_template tar imot id_verified per mottaker.
Signaturen teller, og dokumentet blir ferdig, først når verifiseringen er godkjent. Inntil da forblir dokumentet sent med waiting_for_id_verification true og uten signert PDF. Mottakere har id_verified og id_verification: status (not_signed, to_verify, verifying, review, verified eller rejected), verified_at og name_matches. Webhooks legger til sign.document.id_verified og sign.document.id_rejected. Etter et avslag kan avsenderen be personen om å signere på nytt i Sign-portalen; signaturen teller aldri som en enkel i stedet.
Hver verifisering koster EUR 1,50 eks. mva. fra saldoen til appens organisasjon, trukket når personen starter den eller bruker en eksisterende (én gang per verifisering og organisasjon). send svarer 402 id_verification_payer når appen ikke har en organisasjon, og 402 id_verification_balance (med needCents) når saldoen ikke dekker personene med ID-kontroll.
Kvalifiserte signaturer
Hver signatar har et level: "simple" (standard: en enkel elektronisk signatur etter eIDAS, der e-postadressen bekreftes ved innlogging med Dazr Identity, med et detaljert revisjonsspor og en forseglet PDF) eller "qualified". "advanced", navnet før 13. oktober 2026, godtas fortsatt og betyr "simple"; svar og webhooks sier "simple". En kvalifisert signatar laster ned PDF-en i Dazr Sign, signerer den med sin egen kvalifiserte elektroniske signatur (et elektronisk ID-kort eller et kvalifisert sertifikat i Adobe Acrobat Reader) og laster opp den signerte filen. Dazr Sign kontrollerer den mot EUs tillitslister og godtar den bare hvis det er en kvalifisert signatur på nøyaktig den filen som ble utlevert. Dazr utsteder ikke sertifikater.
Angi nivået per mottaker: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. En kvalifisert signerer har ingen initialfelt. name_rule på dokumentet sier hva som skjer når navnet på sertifikatet avviker fra mottakerens navn: "warn" (standard: godtatt, med name_matches false) eller "block" (avvist). Maler beholder nivået for hver rolle, og from_template kan heve en rolle til "qualified".
Hver signatur forblir gyldig: senere signaturer og det endelige Dazr-seglet legges til som inkrementelle oppdateringer, og revisjonssporet for et slikt dokument er en separat forseglet PDF på GET /documents/{id}/audit.pdf. Mottakere i dokumenter og webhooks har level og, når en kvalifisert signerer har signert, 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 eller CAdES) og name_matches. Ethvert annet level gir 400 invalid_level.
Krav om kvalifiserte signaturer
Eiere og administratorer i en organisasjon kan kreve en kvalifisert elektronisk signatur fra alle som signerer: for dokumentene en app oppretter (appens side under Utviklere i Sign-portalen) eller for dokumentene organisasjonens medlemmer sender (Innstillinger i Sign-portalen). Dazr Sign håndhever det på serveren. En signerer uten level signerer kvalifisert, "level": "simple" gir 422 qualified_signature_required med mottakerens index, malroller heves til kvalifisert (ber du from_template om en enkel rolle, gir det 400 qualified_signature_required), og et dokument fullføres bare når hver signerers kvalifiserte signatur er verifisert. Dokumenter viser qes_required.
Sertifikater gjennom Dazr
Dazr utsteder ikke sertifikater, men kan skaffe et fra en kvalifisert tilbyder av tillitstjenester når det alternativet er slått på. Da lar "provider_allowed": true på en kvalifisert signatar vedkommende få et kvalifisert sertifikat på denne måten hvis de ikke har et. De bekrefter identiteten sin hos tilbyderen (ID-dokument, videosamtale) og signerer deretter på signeringssiden med en engangskode fra tilbyderens app. Dazr lagrer aldri signeringsopplysninger: enhetsnavn, PIN-kode og engangskode går til tilbyderen bare for den ene signaturen. Den signerte PDF-en kontrolleres som en opplasting. Sertifikatet tilhører signataren i 3 år og signerer senere Dazr-dokumenter uten ekstra kostnad. I certificate oppgir issued_through tilbyderen (null for signatarens eget sertifikat).
Dette alternativet er ikke slått på for øyeblikket: provider_allowed godtas og har ingen virkning før det er det.
Signataren betaler på signeringssiden (standard), eller appens organisasjon betaler på forhånd: "qes_payer": "organisation" på dokumentet, eller appens innstilling. Da svarer send med 402 payment_required med checkout_url (en betalingsside) og amount (net, vat, total, certificates), og dokumentet sendes når betalingen er mottatt (sign.document.sent). Et forhåndsbetalt sertifikat som ingen bruker, refunderes når dokumentet er fullført, avbrutt, avslått eller utløpt. Dokumenter viser qes_payer: "signer" eller "organisation".
Webhooks
Angi en webhook-URL for appen din i Sign-portalen under Utviklere. Du får signeringshemmeligheten én gang. Dazr Sign sender sign.document.sent, viewed, signed, completed, declined, voided og expired for dokumentene appen din har opprettet, med dokumentets status og mottakernes status, aldri innholdet. Mislykkede leveranser prøves på nytt etter 5 minutter, 30 minutter, 2, 6, 12 og 24 timer; leveringsloggen viser hvert forsøk og kan sende ett på nytt.
// 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: [...] } } }
Referanse
Alle stier starter med https://sign.dazr.eu/api/sign/v1. Tidspunkter er ISO 8601 i UTC.
| Forespørsel | Hva den gjør |
|---|---|
POST /documents | Oppretter et utkast fra en PDF: file i base64, en multipart-opplasting (file pluss data som JSON) eller en upload_id. Valgfritt: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare. |
POST /documents/from_template | Oppretter et utkast fra en mal: template_id, recipients som { role, name, email }, values etter felt-ID eller etikett. |
GET /documents | Lister appens dokumenter for denne personen, nyeste først: limit (opptil 100), cursor, status. |
GET /documents/{id} | Dokumentet med status, mottakere og felt. |
POST /documents/{id}/send | Sender et utkast. |
POST /documents/{id}/remind | Minner signatarene som står for tur (høyst én gang i timen). |
POST /documents/{id}/void | Avbryter et dokument som er ute til signering, med en valgfri reason. |
DELETE /documents/{id} | Sletter et utkast eller et lukket dokument. |
POST /documents/{id}/prepare_url | Et nytt klargjøringsvindu for et utkast: origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | Et signeringsvindu for en signatar som står for tur: origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | PDF-en slik den ble sendt. |
GET /documents/{id}/signed.pdf | Den forseglede kopien, når alle har signert. |
GET /documents/{id}/audit.json | Revisjonssporet: hendelser, hasher og signatarer. |
GET /documents/{id}/audit.pdf | Det separate, forseglede revisjonssporet for et dokument med kvalifiserte signatarer, når alle har signert. |
POST /uploads | Starter en opplasting i deler for PDF-er over 4 MB: size. Deretter PUT /uploads/{upload_id}/parts/{n} med de rå bytene i hver del. |
GET /templates | Personens maler, med roller og felt. |
GET /templates/{id} | Én mal. |
POST /templates | Lagrer et av appens dokumenter som mal: document_id, name. |
DELETE /templates/{id} | Sletter en mal. |
Send en Idempotency-Key-header når du oppretter et dokument: samme nøkkel og innhold innen 24 timer returnerer det samme dokumentet (header Idempotent-Replayed: true) i stedet for et nytt.
Feil og begrensninger
Feil har en HTTP-status og et innhold som { "error": { "code": "not_found", "message": "..." } }, noen ganger med detaljer som index.
| Status | Koder |
|---|---|
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 (utløpt eller tilbakekalt, eller personen har fjernet appen din) |
402 | payment_required, med checkout_url og amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (også for dokumenter appen din ikke har opprettet), 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 (en signerer med nivå simple mens kvalifiserte signaturer er påkrevd) |
429 | rate_limited, med en Retry-After-header |
502 | payment_unavailable |
- PDF-er opptil 25 MB og 200 sider, uten passord. Forespørsler opptil 4 MB; større PDF-er går gjennom
/uploads. - Opptil 20 mottakere og 400 felt per dokument, 100 maler per person. Dokumenter og maler teller med i personens Dazr-lagring.
- 120 forespørsler i minuttet per person per app, 30 nye dokumenter hvert 10. minutt og 30 utsendinger i timen.
- Tilgangstokener varer i 10 minutter. Bruk oppdateringstokenet (
offline_access) for å få et nytt.
Overføring av en app
En app kan flyttes til en annen organisasjon som er registrert hos Dazr, under Overfør app i appinnstillingene. Med Dazr Sign-API-et aktivert kan den bare flyttes til en verifisert organisasjon, og en eier eller administrator der må godta innen 14 dager. Utviklerdokumentasjonen for Dazr Identity beskriver hvert trinn.
- Dokumenter appen din opprettet før overføringen, blir hos personene som eier dem. Appen ser dem ikke lenger gjennom API-et, og det sendes ingen webhooks for dem.
- Webhook-URL-en og popup-opprinnelsene blir værende. Signeringshemmeligheten for webhooken fornyes og vises én gang til administratoren som godtar.
- Tilgangstokener og oppdateringstokener som er utstedt før overføringen, slutter å virke, og folk godkjenner appen på nytt ved neste innlogging. Maler tilhører personer og påvirkes ikke.
- Dokumenttellingene i Sign-portalen starter på nytt ved overføringen.