Dazr Sign-API: utviklerdokumentasjon

Hurtigstart

  1. 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.
  2. Be om omfanget sign. Send folk gjennom den vanlige flyten for innlogging med Dazr Identity med scope=openid sign (legg til offline_access for 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, email og de andre), må Dazr Identity-API-et også være aktivert.
  3. Kall API-et med tilgangstokenet. Grunnadressen er https://sign.dazr.eu/api/sign/v1. Send Authorization: Bearer <access token> og JSON.
  4. 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.

TaggFelt
{{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.

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ørselHva den gjør
POST /documentsOppretter 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_templateOppretter et utkast fra en mal: template_id, recipients som { role, name, email }, values etter felt-ID eller etikett.
GET /documentsLister 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}/sendSender et utkast.
POST /documents/{id}/remindMinner signatarene som står for tur (høyst én gang i timen).
POST /documents/{id}/voidAvbryter 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_urlEt nytt klargjøringsvindu for et utkast: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlEt signeringsvindu for en signatar som står for tur: origin, redirect_uri, state.
GET /documents/{id}/original.pdfPDF-en slik den ble sendt.
GET /documents/{id}/signed.pdfDen forseglede kopien, når alle har signert.
GET /documents/{id}/audit.jsonRevisjonssporet: hendelser, hasher og signatarer.
GET /documents/{id}/audit.pdfDet separate, forseglede revisjonssporet for et dokument med kvalifiserte signatarer, når alle har signert.
POST /uploadsStarter 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 /templatesPersonens maler, med roller og felt.
GET /templates/{id}Én mal.
POST /templatesLagrer 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.

StatusKoder
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 (utløpt eller tilbakekalt, eller personen har fjernet appen din)
402payment_required, med checkout_url og amount
403insufficient_scope, sign_api_disabled
404not_found (også for dokumenter appen din ikke har opprettet), 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 (en signerer med nivå simple mens kvalifiserte signaturer er påkrevd)
429rate_limited, med en Retry-After-header
502payment_unavailable

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.