API Dazr Sign: dokumentace pro vývojáře

Připravujte a odesílejte dokumenty k podpisu z vlastního softwaru, jménem lidí, kteří ho používají. Podepisující podepisují v Dazr Sign jako obvykle: přihlášení přes Dazr Identity, postupně, jednou.

Jak funguje přístup Každý dokument patří osobě s účtem Dazr. Vaše aplikace jedná za tuto osobu s přístupovým tokenem, který schválila, nikdy sama za sebe. Vaše aplikace vidí jen dokumenty, které vytvořila, a osoba ji může kdykoli zastavit v Dazr Identity.

Rychlý start

  1. Zapněte API Dazr Sign. V portálu Sign otevřete Vývojáři a pro svou aplikaci zvolte Zapnout API Dazr Sign. Jsou tam uvedeny všechny aplikace vaší organizace, stejně jako v konzoli Dazr Identity, se stejným client ID a tajemstvím; každé API se zapíná zvlášť. Můžete tam také zaregistrovat novou aplikaci.
  2. Požádejte o rozsah sign. Pošlete lidi obvyklým tokem Přihlášení přes Dazr Identity s scope=openid sign (pro obnovovací token přidejte offline_access). Obrazovka souhlasu uvádí, že vaše aplikace může jejich jménem připravovat a odesílat dokumenty k podpisu a vidět jejich stav. Funguje to jen se zapnutým API Dazr Sign; žádat i o údaje lidí (profile, email a další) vyžaduje navíc zapnuté API Dazr Identity.
  3. Volejte API s přístupovým tokenem. Základní adresa je https://sign.dazr.eu/api/sign/v1. Posílejte Authorization: Bearer <access token> a JSON.
  4. Vytvořte a odešlete dokument. Nahrajte PDF s textovými značkami a seznamem příjemců a pak ho odešlete, nebo otevřete okno přípravy, aby pole umístila daná osoba.
// 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"

Textové značky

Pole napište do PDF jako text. Každá značka se nahradí polem stejné nebo větší velikosti a text značky se přemaluje, takže ho podepisující nikdy nevidí.

ZnačkaPole
{{signature:1}}Podpis prvního příjemce
{{initials:2}}Iniciály druhého příjemce
{{name:1}} {{date:1}}Jméno a datum podpisu, vyplní Dazr Sign
{{text:2:Company}}Textové pole s popiskem Firma
{{checkbox:2:Terms:optional}}Nepovinné zaškrtávací políčko
{{company:1}}Název firmy (vyplní se, když osoba podepisuje za organizaci)

Číslo je pozice příjemce v recipients, počínaje 1. Značka pro příjemce, kterého jste neuvedli, přidá prázdného příjemce k doplnění v okně přípravy. Pošlete "text_tags": false, chcete-li značky ignorovat. Můžete také poslat fields s pozicemi v bodech (1/72 palce) od levého horního rohu stránky: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. value u textového pole, pole firmy nebo zaškrtávacího políčka hodnotu zafixuje: podepisující ji vidí a nemůže ji změnit.

Vytvořte koncept s "prepare": { "origin": "https://app.example.eu" } a dostanete prepare_url. Otevřete ho ve vyskakovacím okně: osoba v kompaktním editoru umístí příjemce a pole a pak klikne na Odeslat nebo Uložit jako šablonu. Pro podepisujícího, který je na řadě, dá POST /documents/{id}/recipients/{recipient_id}/signing_url vyskakovací okno pro podpis. Oba odkazy platí 10 až 15 minut a fungují jednou. Osoba se ve vyskakovacím okně v případě potřeby přihlásí přes Dazr Identity, a to adresou, na kterou byl dokument odeslán.

Po dokončení vyskakovací okno pošle { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } pomocí postMessage stránce, která ho otevřela, jen pokud je tato stránka na jednom z originů vyskakovacích oken vaší aplikace (ve výchozím stavu originy vašich URI pro přesměrování), a zavře se. event je sent, saved, cancelled, signed nebo declined. S redirect_uri (jedním z vašich registrovaných URI pro přesměrování) a state se vyskakovací okno, které ztratilo svého otvíratele, vrátí tam se stejnými hodnotami jako parametry dotazu.

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

Pokud vaše stránka posílá Cross-Origin-Opener-Policy: same-origin, použijte místo toho same-origin-allow-popups, jinak vyskakovací okno nemůže odpovědět.

Kvalifikované podpisy

Každý podepisující má level: "advanced" (výchozí: e-mailová adresa je potvrzena přihlášením přes Dazr Identity) nebo "qualified". Podepisující s kvalifikovaným podpisem stáhne PDF v Dazr Sign, podepíše ho vlastním kvalifikovaným elektronickým podpisem (elektronický občanský průkaz, podpisová aplikace jako itsme, kvalifikovaný certifikát v Adobe Acrobat Reader) a nahraje podepsaný soubor. Dazr Sign ho ověří podle důvěryhodných seznamů EU a přijme ho, jen pokud jde o kvalifikovaný podpis přesně na souboru, který vydal. Dazr kvalifikované podpisy nevydává.

Úroveň nastavte pro každého příjemce: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Podepisující s kvalifikovaným podpisem nemá pole pro iniciály. name_rule u dokumentu určuje, co se stane, když se jméno v certifikátu liší od jména příjemce: "warn" (výchozí: přijato, s name_matches false) nebo "block" (odmítnuto). Šablony si uchovávají úroveň každé role a from_template může roli zvýšit na "qualified".

Každý podpis zůstává platný: pozdější podpisy a závěrečná pečeť Dazr se přidávají jako přírůstkové aktualizace a auditní stopa takového dokumentu je samostatné zapečetěné PDF na GET /documents/{id}/audit.pdf. Příjemci v dokumentech a webhoocích mají level a poté, co podepisující s kvalifikovaným podpisem podepíše, i 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 nebo CAdES) a name_matches. Jakákoli jiná hodnota level vrátí 400 invalid_level.

Webhooky

Nastavte URL webhooku pro svou aplikaci v portálu Sign v části Vývojáři. Podpisové tajemství dostanete jednou. Dazr Sign posílá sign.document.sent, viewed, signed, completed, declined, voided a expired pro dokumenty, které vaše aplikace vytvořila, se stavem dokumentu a jeho příjemců, nikdy s jeho obsahem. Neúspěšná doručení se opakují po 5 minutách, 30 minutách, 2, 6, 12 a 24 hodinách; protokol doručení ukazuje každý pokus a umožňuje jedno znovu odeslat.

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

Všechny cesty začínají https://sign.dazr.eu/api/sign/v1. Časy jsou ve formátu ISO 8601 v UTC.

PožadavekCo dělá
POST /documentsVytvoří koncept z PDF: file v base64, nahrání multipart (file plus data jako JSON) nebo upload_id. Volitelné: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateVytvoří koncept ze šablony: template_id, recipients jako { role, name, email }, values podle ID pole nebo popisku.
GET /documentsVypíše dokumenty vaší aplikace pro tuto osobu, od nejnovějších: limit (až 100), cursor, status.
GET /documents/{id}Dokument s jeho stavem, příjemci a poli.
POST /documents/{id}/sendOdešle koncept.
POST /documents/{id}/remindPřipomene se podepisujícím, kteří jsou na řadě (nejvýše jednou za hodinu).
POST /documents/{id}/voidZruší dokument odeslaný k podpisu, s volitelným reason.
DELETE /documents/{id}Smaže koncept nebo uzavřený dokument.
POST /documents/{id}/prepare_urlNové okno přípravy pro koncept: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlOkno pro podpis pro podepisujícího, který je na řadě: origin, redirect_uri, state.
GET /documents/{id}/original.pdfPDF tak, jak bylo odesláno.
GET /documents/{id}/signed.pdfZapečetěná kopie, jakmile všichni podepíšou.
GET /documents/{id}/audit.jsonAuditní stopa: události, hashe a podepisující.
GET /documents/{id}/audit.pdfSamostatná zapečetěná auditní stopa dokumentu s podepisujícími s kvalifikovaným podpisem, jakmile všichni podepíšou.
POST /uploadsZahájí nahrávání po částech pro PDF větší než 4 MB: size. Poté PUT /uploads/{upload_id}/parts/{n} se surovými bajty každé části.
GET /templatesŠablony osoby s jejich rolemi a poli.
GET /templates/{id}Jedna šablona.
POST /templatesUloží jeden z dokumentů vaší aplikace jako šablonu: document_id, name.
DELETE /templates/{id}Smaže šablonu.

Při vytváření dokumentu pošlete hlavičku Idempotency-Key: stejný klíč a tělo během 24 hodin vrátí stejný dokument (hlavička Idempotent-Replayed: true) místo druhého.

Chyby a limity

Chyby mají stav HTTP a tělo jako { "error": { "code": "not_found", "message": "..." } }, někdy s podrobnostmi, například index.

StatusKódy
400invalid_field, invalid_recipients, invalid_email, not_pdf, pdf_unreadable, pdf_encrypted, invalid_origin, invalid_redirect_uri, unknown_role, unknown_field
401unauthenticated, invalid_token (vypršel nebo byl zneplatněn, nebo osoba vaši aplikaci odebrala)
403insufficient_scope, sign_api_disabled
404not_found (i pro dokumenty, které vaše aplikace nevytvořila), template_not_found
409not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress
413pdf_too_large, too_large, quota
422idempotency_key_reused
429rate_limited, s hlavičkou Retry-After

Převod aplikace

Aplikace se může přesunout k jiné organizaci registrované v Dazr, v části Převést aplikaci v nastavení aplikace. Se zapnutým API Dazr Sign se může přesunout jen k ověřené organizaci a vlastník nebo administrátor tam musí převod do 14 dnů přijmout. Každý krok popisuje dokumentace pro vývojáře Dazr Identity.