Dazr Sign API: utvecklardokumentation

Förbered och skicka dokument för underskrift från din egen programvara i namnet på de personer som använder den. Undertecknare undertecknar med Dazr Sign som vanligt: inloggade med Dazr Identity, i tur och ordning, en gång.

Så fungerar åtkomst Varje dokument tillhör en person med ett Dazr-konto. Din app agerar för den personen med en access token som personen har godkänt, aldrig på egen hand. Din app ser bara de dokument den har skapat, och personen kan när som helst stoppa den i Dazr Identity.

Snabbstart

  1. Aktivera Dazr Sign API. Öppna Utvecklare i Sign-portalen och välj Aktivera Dazr Sign API för din app. Alla din organisations appar finns där och i konsolen för Dazr Identity, med samma klient-id och hemlighet; varje API aktiveras separat. Du kan också registrera en ny app där.
  2. Be om scopet sign. Skicka människor genom det vanliga flödet Logga in med Dazr Identity med scope=openid sign (lägg till offline_access för en refresh token). Samtyckesskärmen säger att din app får förbereda och skicka dokument för underskrift i deras namn och se deras status. Det fungerar med enbart Dazr Sign API; ber du också om personuppgifter (profile, email och de andra) måste Dazr Identity API också vara aktiverat.
  3. Anropa API:t med access token. Basadressen är https://sign.dazr.eu/api/sign/v1. Skicka Authorization: Bearer <access token> och JSON.
  4. Skapa och skicka ett dokument. Ladda upp en PDF med texttaggar och en lista över mottagare och skicka den sedan, eller öppna förberedelsefönstret så att personen placerar fälten.
// 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"

Texttaggar

Skriv in fälten i PDF:en som text. Varje tagg ersätts av ett fält av samma storlek eller större, och taggtexten målas över så att undertecknare aldrig ser den.

TaggFält
{{signature:1}}Signatur för den första mottagaren
{{initials:2}}Initialer för den andra mottagaren
{{name:1}} {{date:1}}Namn och datum för underskrift, ifyllda av Dazr Sign
{{text:2:Company}}Ett textfält med etiketten Företag
{{checkbox:2:Terms:optional}}En valfri kryssruta
{{company:1}}Företagsnamn (ifyllt när personen undertecknar för en organisations räkning)

Talet är mottagarens position i recipients, med början på 1. En tagg för en mottagare som du inte har angett lägger till en tom mottagare som fylls i i förberedelsefönstret. Skicka "text_tags": false för att ignorera taggar. Du kan också skicka fields med positioner i punkter (1/72 tum) från sidans övre vänstra hörn: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. Ett value på ett text-, företags- eller kryssrutefält låser det: undertecknaren ser det och kan inte ändra det.

Skapa ett utkast med "prepare": { "origin": "https://app.example.eu" } så får du en prepare_url. Öppna den i ett popup-fönster: personen placerar mottagare och fält i en kompakt redigerare och klickar sedan på Skicka eller Spara som mall. För en undertecknare vars tur det är ger POST /documents/{id}/recipients/{recipient_id}/signing_url ett underskriftsfönster. Båda länkarna är giltiga i 10 till 15 minuter och fungerar en gång. Personen loggar in med Dazr Identity i popup-fönstret om det behövs, med den adress som dokumentet skickades till.

När det är klart skickar popup-fönstret { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } med postMessage till den sida som öppnade det, bara om sidan finns på någon av din apps popup-origins (som standard origins för dina omdirigerings-URI:er), och stänger. event är sent, saved, cancelled, signed eller declined. Med redirect_uri (en av dina registrerade omdirigerings-URI:er) och state går ett popup-fönster som har förlorat sin opener tillbaka dit med samma värden som query-parametrar.

<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>

Skickar din sida Cross-Origin-Opener-Policy: same-origin, använd då same-origin-allow-popups i stället, annars kan popup-fönstret inte rapportera tillbaka.

Kvalificerade signaturer

Varje undertecknare har en level: "advanced" (standard: e-postadressen bekräftas vid inloggning med Dazr Identity) eller "qualified". En kvalificerad undertecknare laddar ned PDF:en i Dazr Sign, undertecknar den med sin egen kvalificerade elektroniska signatur (ett elektroniskt id-kort, en signeringsapp som itsme, ett kvalificerat certifikat i Adobe Acrobat Reader) och laddar upp den undertecknade filen. Dazr Sign kontrollerar den mot EU:s förtroendelistor och godtar den bara om det är en kvalificerad signatur på exakt den fil som lämnades ut. Dazr utfärdar inte kvalificerade signaturer.

Ange nivån per mottagare: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. En kvalificerad undertecknare har inga initialfält. name_rule på dokumentet anger vad som händer när namnet på certifikatet skiljer sig från mottagarens namn: "warn" (standard: godtas, med name_matches false) eller "block" (avvisas). Mallar behåller nivån för varje roll, och from_template kan höja en roll till "qualified".

Varje signatur förblir giltig: senare signaturer och Dazrs slutliga stämpel läggs till som inkrementella uppdateringar, och revisionsspåret för ett sådant dokument är en separat förseglad PDF på GET /documents/{id}/audit.pdf. Mottagare i dokument och webhooks har level och, när en kvalificerad undertecknare har undertecknat, 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) och name_matches. Varje annan level ger 400 invalid_level.

Krav på kvalificerade signaturer

Ägare och administratörer för en organisation kan kräva en kvalificerad elektronisk signatur av alla som undertecknar: för de dokument som en app skapar (appens sida under Utvecklare i Sign-portalen), eller för de dokument som organisationens medlemmar skickar (Inställningar i Sign-portalen). Dazr Sign genomdriver det på servern. En undertecknare utan level undertecknar kvalificerat, "level": "advanced" ger 422 qualified_signature_required med mottagarens index, mallroller höjs till kvalificerad (ber du from_template om en avancerad roll ger det 400 qualified_signature_required), och ett dokument slutförs bara när varje undertecknares kvalificerade signatur har verifierats. Dokument visar qes_required.

Certifikat via Dazr

Där Dazr Sign erbjuder det låter "provider_allowed": true på en kvalificerad undertecknare hen få ett kvalificerat certifikat från Dazrs tillhandahållare av betrodda tjänster, om personen inte har något. Personen bekräftar sin identitet hos tillhandahållaren (identitetshandling, videosamtal) och undertecknar sedan på underskriftssidan med en engångskod från tillhandahållarens app. Dazr lagrar aldrig signeringsuppgifter: enhetsnamn, pinkod och engångskod går till tillhandahållaren för den enda signaturen. Den undertecknade PDF:en kontrolleras som en uppladdning. Certifikatet tillhör undertecknaren i 3 år och undertecknar senare Dazr-dokument utan extra kostnad. I certificate anger issued_through tillhandahållaren (null för undertecknarens eget certifikat).

Undertecknaren betalar på underskriftssidan (standard), eller appens organisation betalar i förväg: "qes_payer": "organisation" på dokumentet eller appens inställning. Då svarar send 402 payment_required med checkout_url (en betalningssida) och amount (net, vat, total, certificates), och dokumentet skickas när betalningen har tagits emot (sign.document.sent). Ett förbetalt certifikat som ingen använder återbetalas när dokumentet slutförs, ställs in, avvisas eller går ut. Dokument visar qes_payer: "signer" eller "organisation".

Webhooks

Ange en webhook-URL för din app i Sign-portalen under Utvecklare. Du får dess signeringshemlighet en gång. Dazr Sign skickar sign.document.sent, viewed, signed, completed, declined, voided och expired för de dokument som din app har skapat, med dokumentets status och mottagarnas status, aldrig innehållet. Misslyckade leveranser försöks igen efter 5 minuter, 30 minuter, 2, 6, 12 och 24 timmar; leveransloggen visar varje försök och kan skicka ett igen.

// 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: [...] } } }

Referens

Alla sökvägar börjar med https://sign.dazr.eu/api/sign/v1. Tider är ISO 8601 i UTC.

FörfråganVad den gör
POST /documentsSkapar ett utkast från en PDF: file i base64, en multipart-uppladdning (file plus data som JSON) eller ett upload_id. Valfritt: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateSkapar ett utkast från en mall: template_id, recipients som { role, name, email }, values efter fält-id eller etikett.
GET /documentsVisar din apps dokument för den här personen, nyaste först: limit (upp till 100), cursor, status.
GET /documents/{id}Dokumentet med dess status, mottagare och fält.
POST /documents/{id}/sendSkickar ett utkast.
POST /documents/{id}/remindPåminner de undertecknare vars tur det är (högst en gång i timmen).
POST /documents/{id}/voidStäller in ett dokument som har skickats för underskrift, med en valfri reason.
DELETE /documents/{id}Raderar ett utkast eller ett stängt dokument.
POST /documents/{id}/prepare_urlEtt nytt förberedelsefönster för ett utkast: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlEtt underskriftsfönster för en undertecknare vars tur det är: origin, redirect_uri, state.
GET /documents/{id}/original.pdfPDF:en som den skickades.
GET /documents/{id}/signed.pdfDen förseglade kopian, när alla har undertecknat.
GET /documents/{id}/audit.jsonRevisionsspåret: händelser, hashar och undertecknare.
GET /documents/{id}/audit.pdfDet separata, förseglade revisionsspåret för ett dokument med kvalificerade undertecknare, när alla har undertecknat.
POST /uploadsStartar en uppladdning i delar för PDF:er över 4 MB: size. Sedan PUT /uploads/{upload_id}/parts/{n} med de råa byten för varje del.
GET /templatesPersonens mallar med deras roller och fält.
GET /templates/{id}En mall.
POST /templatesSparar ett av din apps dokument som mall: document_id, name.
DELETE /templates/{id}Raderar en mall.

Skicka ett Idempotency-Key-huvud när du skapar ett dokument: samma nyckel och body inom 24 timmar returnerar samma dokument (huvud Idempotent-Replayed: true) i stället för ett nytt.

Fel och gränser

Fel har en HTTP-status och en body som { "error": { "code": "not_found", "message": "..." } }, ibland 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 (utgången eller återkallad, eller personen har tagit bort din app)
402payment_required, med checkout_url och amount
403insufficient_scope, sign_api_disabled
404not_found (även för dokument som din app inte har skapat), 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 undertecknare med nivå advanced medan kvalificerade signaturer krävs)
429rate_limited, med ett Retry-After-huvud
502payment_unavailable

Överföring av en app

En app kan flyttas till en annan organisation som är registrerad hos Dazr under Överför app i appens inställningar. Med Dazr Sign API aktiverat kan den bara flyttas till en verifierad organisation, och en ägare eller administratör där måste godta inom 14 dagar. Utvecklardokumentationen för Dazr Identity beskriver varje steg.