Dazr Sign API: udviklerdokumentation

Forbered og send dokumenter til underskrift fra din egen software i navnet på de personer, der bruger den. Underskrivere underskriver med Dazr Sign som sædvanligt: logget ind med Dazr Identity, efter tur, én gang.

• Hurtig start
• Teksttags
• Popups
• Kvalificerede signaturer
• Krav om kvalificerede signaturer
• Certifikater via Dazr
• Webhooks
• Reference
• Fejl og grænser
• Overførsler

Hurtig start

1. Slå Dazr Sign API til. Åbn Udviklere i Sign-portalen, og vælg Slå Dazr Sign API til for din app. Alle din organisations apps står der og i konsollen for Dazr Identity, med samme klient-id og hemmelighed; hvert API slås til for sig. Du kan også registrere en ny app der.
2. Bed om scopet sign. Send folk gennem det sædvanlige forløb Log ind med Dazr Identity med scope=openid sign (tilføj offline_access for et refresh token). Samtykkeskærmen siger, at din app må forberede og sende dokumenter til underskrift i deres navn og se deres status. Det virker med Dazr Sign API alene; beder du også om personers data (profile, email og de andre), skal Dazr Identity API også være slået til.
3. Kald API'et med access tokenet. Basisadressen er https://sign.dazr.eu/api/sign/v1. Send Authorization: Bearer <access token> og JSON.
4. Opret og send et dokument. Upload en PDF med teksttags og en liste over modtagere, og send den derefter, eller åbn forberedelsesvinduet, så personen placerer felterne.

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

Skriv felterne ind i PDF'en som tekst. Hvert tag erstattes af et felt af samme størrelse eller større, og tagteksten males over, så underskrivere aldrig ser den.

Tallet er modtagerens position i recipients, startende ved 1. Et tag for en modtager, du ikke har angivet, tilføjer en tom modtager, der udfyldes i forberedelsesvinduet. Send "text_tags": false for at ignorere tags. Du kan også sende fields med positioner i punkter (1/72 tomme) fra sidens øverste venstre hjørne: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. En value på et tekst-, virksomheds- eller afkrydsningsfelt låser det: underskriveren ser det og kan ikke ændre det.

Popups: forbered og underskriv

Opret en kladde med "prepare": { "origin": "https://app.example.eu" }, så får du en prepare_url. Åbn den i en popup: personen placerer modtagere og felter i en kompakt editor og klikker derefter på Send eller Gem som skabelon. For en underskriver, hvis tur det er, giver POST /documents/{id}/recipients/{recipient_id}/signing_url en underskriftspopup. Begge links er gyldige i 10 til 15 minutter og virker én gang. Personen logger ind med Dazr Identity i popuppen, hvis det er nødvendigt, med den adresse, dokumentet blev sendt til.

Når det er færdigt, sender popuppen { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } med postMessage til den side, der åbnede den, kun hvis siden er på en af din apps popup-origins (som standard origins for dine omdirigerings-URI'er), og lukker. event er sent, saved, cancelled, signed eller declined. Med redirect_uri (en af dine registrerede omdirigerings-URI'er) og state går en popup, der har mistet sin opener, tilbage dertil med de samme værdier som query-parametre.

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

Sender din side Cross-Origin-Opener-Policy: same-origin, så brug same-origin-allow-popups i stedet, ellers kan popuppen ikke melde tilbage.

Kvalificerede signaturer

Hver underskriver har et level: "advanced" (standard: e-mailadressen bekræftes ved login med Dazr Identity) eller "qualified". En kvalificeret underskriver downloader PDF'en i Dazr Sign, underskriver den med sin egen kvalificerede elektroniske signatur (et elektronisk ID-kort, en signeringsapp som itsme, et kvalificeret certifikat i Adobe Acrobat Reader) og uploader den underskrevne fil. Dazr Sign tjekker den mod EU's tillidslister og accepterer den kun, hvis det er en kvalificeret signatur på præcis den fil, der blev udleveret. Dazr udsteder ikke kvalificerede signaturer.

Sæt niveauet pr. modtager: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. En kvalificeret underskriver har ingen initialfelter. name_rule på dokumentet angiver, hvad der sker, når navnet på certifikatet afviger fra modtagerens navn: "warn" (standard: accepteret, med name_matches false) eller "block" (afvist). Skabeloner beholder niveauet for hver rolle, og from_template kan hæve en rolle til "qualified".

Hver signatur forbliver gyldig: senere signaturer og Dazrs endelige segl tilføjes som inkrementelle opdateringer, og revisionssporet for et sådant dokument er en separat forseglet PDF på GET /documents/{id}/audit.pdf. Modtagere i dokumenter og webhooks har level og, når en kvalificeret underskriver har underskrevet, 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 andet level giver 400 invalid_level.

Krav om kvalificerede signaturer

Ejere og administratorer af en organisation kan kræve en kvalificeret elektronisk signatur af alle, der underskriver: for de dokumenter, en app opretter (appens side under Udviklere i Sign-portalen), eller for de dokumenter, organisationens medlemmer sender (Indstillinger i Sign-portalen). Dazr Sign håndhæver det på serveren. En underskriver uden level underskriver kvalificeret, "level": "advanced" giver 422 qualified_signature_required med modtagerens index, skabelonroller hæves til kvalificeret (beder du from_template om en avanceret rolle, giver det 400 qualified_signature_required), og et dokument fuldføres kun, når hver underskrivers kvalificerede signatur er verificeret. Dokumenter viser qes_required.

Certifikater via Dazr

Hvor Dazr Sign tilbyder det, lader "provider_allowed": true på en kvalificeret underskriver vedkommende få et kvalificeret certifikat fra Dazrs tillidstjenesteudbyder, hvis personen ikke har et. Personen bekræfter sin identitet hos udbyderen (identitetsdokument, videoopkald) og underskriver derefter på underskriftssiden med en engangskode fra udbyderens app. Dazr gemmer aldrig signeringsoplysninger: enhedsnavn, pinkode og engangskode går til udbyderen for den ene signatur. Den underskrevne PDF tjekkes som en upload. Certifikatet tilhører underskriveren i 3 år og underskriver senere Dazr-dokumenter uden ekstra betaling. I certificate angiver issued_through udbyderen (null for underskriverens eget certifikat).

Underskriveren betaler på underskriftssiden (standard), eller appens organisation betaler på forhånd: "qes_payer": "organisation" på dokumentet eller appens indstilling. Så svarer send 402 payment_required med checkout_url (en betalingsside) og amount (net, vat, total, certificates), og dokumentet sendes, når betalingen er modtaget (sign.document.sent). Et forudbetalt certifikat, som ingen bruger, refunderes, når dokumentet fuldføres, annulleres, afvises eller udløber. Dokumenter viser qes_payer: "signer" eller "organisation".

Webhooks

Angiv en webhook-URL for din app i Sign-portalen under Udviklere. Du får dens signeringshemmelighed én gang. Dazr Sign sender sign.document.sent, viewed, signed, completed, declined, voided og expired for de dokumenter, din app har oprettet, med dokumentets status og modtagernes status, aldrig indholdet. Mislykkede leveringer forsøges igen efter 5 minutter, 30 minutter, 2, 6, 12 og 24 timer; leveringsloggen viser hvert forsøg og kan sende et 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: [...] } } }

Reference

Alle stier starter med https://sign.dazr.eu/api/sign/v1. Tidspunkter er ISO 8601 i UTC.

Send en Idempotency-Key-header, når du opretter et dokument: samme nøgle og body inden for 24 timer returnerer det samme dokument (header Idempotent-Replayed: true) i stedet for et nyt.

Fejl og grænser

Fejl har en HTTP-status og en body som { "error": { "code": "not_found", "message": "..." } }, nogle gange med detaljer som index.

• PDF'er op til 25 MB og 200 sider, uden adgangskode. Anmodninger op til 4 MB; større PDF'er går via /uploads.
• Op til 20 modtagere og 400 felter pr. dokument, 100 skabeloner pr. person. Dokumenter og skabeloner tæller med i personens Dazr-lagerplads.
• 120 anmodninger i minuttet for hver person pr. app, 30 nye dokumenter hvert 10. minut og 30 afsendelser i timen.
• Access tokens varer 10 minutter. Brug refresh tokenet (offline_access) til at få et nyt.

Overførsel af en app

En app kan flyttes til en anden organisation registreret hos Dazr under Overfør app i appens indstillinger. Med Dazr Sign API slået til kan den kun flyttes til en verificeret organisation, og en ejer eller administrator der skal acceptere inden for 14 dage. Udviklerdokumentationen for Dazr Identity beskriver hvert trin.

• Dokumenter, din app oprettede før overførslen, bliver hos de personer, der ejer dem. Appen ser dem ikke længere via API'et, og der sendes ingen webhooks for dem.
• Webhook-URL'en og popup-origins bliver. Webhookens signeringshemmelighed fornyes og vises én gang for den administrator, der accepterer.
• Access tokens og refresh tokens udstedt før overførslen holder op med at virke, og folk godkender appen igen ved næste login. Skabeloner tilhører personer og påvirkes ikke.
• Antal dokumenter i Sign-portalen starter forfra ved overførslen.