Dazr Sign-API: utviklerdokumentasjon

Klargjør og send dokumenter til signering fra din egen programvare, i navnet til dem som bruker den. Signerere signerer med Dazr Sign som vanlig: innlogget med Dazr Identity, etter tur, én gang.

• Hurtigstart
• Teksttagger
• Popup-vinduer
• Kvalifiserte signaturer
• Krav om kvalifiserte signaturer
• Sertifikater gjennom Dazr
• Webhooks
• Referanse
• Feil og begrensninger
• Overføringer

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å signerere ser den aldri.

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: signereren 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 signerer 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.

Kvalifiserte signaturer

Hver signerer har et level: "advanced" (standard: e-postadressen bekreftes ved innlogging med Dazr Identity) eller "qualified". En kvalifisert signerer laster ned PDF-en i Dazr Sign, signerer den med sin egen kvalifiserte elektroniske signatur (et elektronisk ID-kort, en signeringsapp som itsme, et kvalifisert sertifikat i Adobe Acrobat Reader) og laster opp den signerte filen. Dazr Sign sjekker den mot EUs tillitslister og godtar den bare hvis det er en kvalifisert signatur på nøyaktig den filen den ga ut. Dazr utsteder ikke kvalifiserte signaturer.

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 dokumentasjonssporet 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": "advanced" gir 422 qualified_signature_required med mottakerens index, malroller heves til kvalifisert (ber du from_template om en avansert 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

Der Dazr Sign tilbyr det, lar "provider_allowed": true på en kvalifisert signerer vedkommende få et kvalifisert sertifikat fra Dazrs tillitstjenesteyter hvis vedkommende ikke har et. De bekrefter hvem de er hos leverandøren (identitetsdokument, videosamtale) og signerer så på signeringssiden med en engangskode fra leverandørens app. Dazr tar aldri vare på signeringslegitimasjon: enhetsnavnet, PIN-koden og engangskoden går til leverandøren for den ene signaturen. Den signerte PDF-en sjekkes som en opplasting. Sertifikatet tilhører signereren i 3 år og signerer senere Dazr-dokumenter uten ekstra kostnad. I certificate angir issued_through leverandøren (null for signererens eget sertifikat).

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

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.

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