API Dazr Sign: dokumentácia pre vývojárov

Pripravujte a posielajte dokumenty na podpis z vlastného softvéru, v mene ľudí, ktorí ho používajú. Podpisujúci podpisujú v Dazr Sign ako zvyčajne: prihlásenie cez Dazr Identity, postupne, raz.

Ako funguje prístup Každý dokument patrí osobe s účtom Dazr. Vaša aplikácia koná za túto osobu s prístupovým tokenom, ktorý schválila, nikdy sama za seba. Vaša aplikácia vidí len dokumenty, ktoré vytvorila, a osoba ju môže kedykoľvek zastaviť v Dazr Identity.

Rýchly štart

  1. Zapnite API Dazr Sign. V portáli Sign otvorte Vývojári a pre svoju aplikáciu zvoľte Zapnúť API Dazr Sign. Sú tam uvedené všetky aplikácie vašej organizácie, rovnako ako v konzole Dazr Identity, s rovnakým client ID a tajomstvom; každé API sa zapína zvlášť. Môžete tam tiež zaregistrovať novú aplikáciu.
  2. Požiadajte o rozsah sign. Pošlite ľudí zvyčajným tokom Prihlásenia cez Dazr Identity s scope=openid sign (na obnovovací token pridajte offline_access). Obrazovka súhlasu uvádza, že vaša aplikácia môže v ich mene pripravovať a posielať dokumenty na podpis a vidieť ich stav. Funguje to len so zapnutým API Dazr Sign; žiadať aj o údaje ľudí (profile, email a ďalšie) vyžaduje navyše zapnuté API Dazr Identity.
  3. Volajte API s prístupovým tokenom. Základná adresa je https://sign.dazr.eu/api/sign/v1. Posielajte Authorization: Bearer <access token> a JSON.
  4. Vytvorte a odošlite dokument. Nahrajte PDF s textovými značkami a zoznamom príjemcov a potom ho odošlite, alebo otvorte okno prípravy, aby polia umiestnila 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

Polia napíšte do PDF ako text. Každá značka sa nahradí poľom rovnakej alebo väčšej veľkosti a text značky sa premaľuje, takže ho podpisujúci nikdy nevidí.

ZnačkaPole
{{signature:1}}Podpis prvého príjemcu
{{initials:2}}Iniciály druhého príjemcu
{{name:1}} {{date:1}}Meno a dátum podpisu, vyplní Dazr Sign
{{text:2:Company}}Textové pole s popisom Firma
{{checkbox:2:Terms:optional}}Nepovinné začiarkavacie políčko
{{company:1}}Názov firmy (vyplní sa, keď osoba podpisuje za organizáciu)

Číslo je pozícia príjemcu v recipients, začínajúc od 1. Značka pre príjemcu, ktorého ste neuviedli, pridá prázdneho príjemcu na doplnenie v okne prípravy. Pošlite "text_tags": false, ak chcete značky ignorovať. Môžete tiež poslať fields s pozíciami v bodoch (1/72 palca) od ľavého horného rohu strany: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. value pri textovom poli, poli firmy alebo začiarkavacom políčku hodnotu zafixuje: podpisujúci ju vidí a nemôže ju zmeniť.

Vytvorte koncept s "prepare": { "origin": "https://app.example.eu" } a dostanete prepare_url. Otvorte ho vo vyskakovacom okne: osoba v kompaktnom editore umiestni príjemcov a polia a potom klikne na Odoslať alebo Uložiť ako šablónu. Pre podpisujúceho, ktorý je na rade, dá POST /documents/{id}/recipients/{recipient_id}/signing_url vyskakovacie okno na podpis. Oba odkazy platia 10 až 15 minút a fungujú raz. Osoba sa vo vyskakovacom okne v prípade potreby prihlási cez Dazr Identity, a to adresou, na ktorú bol dokument odoslaný.

Po dokončení vyskakovacie okno pošle { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } pomocou postMessage stránke, ktorá ho otvorila, len ak je táto stránka na jednom z originov vyskakovacích okien vašej aplikácie (v predvolenom stave originy vašich URI na presmerovanie), a zatvorí sa. event je sent, saved, cancelled, signed alebo declined. S redirect_uri (jedným z vašich registrovaných URI na presmerovanie) a state sa vyskakovacie okno, ktoré stratilo svojho otvárateľa, vráti tam s rovnakými hodnotami ako parametre dopytu.

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

Ak vaša stránka posiela Cross-Origin-Opener-Policy: same-origin, použite namiesto toho same-origin-allow-popups, inak vyskakovacie okno nemôže odpovedať.

Kvalifikované podpisy

Každý podpisujúci má level: "advanced" (predvolené: e-mailová adresa je potvrdená prihlásením cez Dazr Identity) alebo "qualified". Podpisujúci s kvalifikovaným podpisom stiahne PDF v Dazr Sign, podpíše ho vlastným kvalifikovaným elektronickým podpisom (elektronický občiansky preukaz, podpisová aplikácia ako itsme, kvalifikovaný certifikát v Adobe Acrobat Reader) a nahrá podpísaný súbor. Dazr Sign ho overí podľa dôveryhodných zoznamov EÚ a prijme ho, len ak ide o kvalifikovaný podpis presne na súbore, ktorý vydal. Dazr kvalifikované podpisy nevydáva.

Úroveň nastavte pre každého príjemcu: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Podpisujúci s kvalifikovaným podpisom nemá pole na iniciály. name_rule pri dokumente určuje, čo sa stane, keď sa meno v certifikáte líši od mena príjemcu: "warn" (predvolené: prijaté, s name_matches false) alebo "block" (odmietnuté). Šablóny si uchovávajú úroveň každej roly a from_template môže rolu zvýšiť na "qualified".

Každý podpis zostáva platný: neskoršie podpisy a záverečná pečať Dazr sa pridávajú ako prírastkové aktualizácie a auditná stopa takého dokumentu je samostatné zapečatené PDF na GET /documents/{id}/audit.pdf. Príjemcovia v dokumentoch a webhookoch majú level a po tom, čo podpisujúci s kvalifikovaným podpisom podpíše, aj 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 alebo CAdES) a name_matches. Akákoľvek iná hodnota level vráti 400 invalid_level.

Vyžadovanie kvalifikovaných podpisov

Vlastníci a administrátori organizácie môžu vyžadovať kvalifikovaný elektronický podpis od všetkých, ktorí podpisujú: pri dokumentoch, ktoré vytvára aplikácia (stránka aplikácie v časti Vývojári na portáli Sign), alebo pri dokumentoch, ktoré odosielajú členovia organizácie (Nastavenia na portáli Sign). Dazr Sign to vynucuje na serveri. Kto podpisuje bez level, podpisuje kvalifikovane, "level": "advanced" vráti 422 qualified_signature_required s index príjemcu, roly zo šablón sa zmenia na kvalifikované (žiadosť o zdokonalenú rolu pri from_template vráti 400 qualified_signature_required) a dokument sa dokončí, až keď je overený kvalifikovaný podpis každej podpisujúcej osoby. Dokumenty uvádzajú qes_required.

Certifikáty cez Dazr

Tam, kde to Dazr Sign ponúka, umožní "provider_allowed": true pri kvalifikovane podpisujúcej osobe získať kvalifikovaný certifikát od poskytovateľa dôveryhodných služieb, s ktorým Dazr spolupracuje, ak žiadny nemá. Osoba potvrdí totožnosť u poskytovateľa (doklad totožnosti, videohovor) a potom podpíše na stránke podpisu jednorazovým kódom z aplikácie poskytovateľa. Dazr nikdy neuchováva podpisové údaje: názov zariadenia, PIN a jednorazový kód idú k poskytovateľovi len pre ten jeden podpis. Podpísané PDF sa kontroluje ako nahraný súbor. Certifikát patrí podpisujúcej osobe na 3 roky a bez príplatku podpisuje ďalšie dokumenty Dazr. V certificate uvádza issued_through poskytovateľa (null pri vlastnom certifikáte).

Platí podpisujúca osoba na stránke podpisu (predvolené), alebo organizácia aplikácie platí vopred: "qes_payer": "organisation" pri dokumente alebo nastavenie aplikácie. Potom send odpovie 402 payment_required s checkout_url (platobná stránka) a amount (net, vat, total, certificates) a dokument sa odošle, hneď ako platba dorazí (sign.document.sent). Predplatený certifikát, ktorý nikto nevyužije, sa vráti, keď je dokument dokončený, zrušený, odmietnutý alebo vyprší. Dokumenty uvádzajú qes_payer: "signer" alebo "organisation".

Webhooky

Nastavte URL webhooku pre svoju aplikáciu v portáli Sign v časti Vývojári. Podpisové tajomstvo dostanete raz. Dazr Sign posiela sign.document.sent, viewed, signed, completed, declined, voided a expired pre dokumenty, ktoré vaša aplikácia vytvorila, so stavom dokumentu a jeho príjemcov, nikdy s jeho obsahom. Neúspešné doručenia sa opakujú po 5 minútach, 30 minútach, 2, 6, 12 a 24 hodinách; protokol doručení ukazuje každý pokus a umožňuje jeden znova odoslať.

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

Referencia

Všetky cesty začínajú https://sign.dazr.eu/api/sign/v1. Časy sú vo formáte ISO 8601 v UTC.

PožiadavkaČo robí
POST /documentsVytvorí koncept z PDF: file v base64, nahranie multipart (file plus data ako JSON) alebo upload_id. Voliteľné: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateVytvorí koncept zo šablóny: template_id, recipients ako { role, name, email }, values podľa ID poľa alebo popisu.
GET /documentsVypíše dokumenty vašej aplikácie pre túto osobu, od najnovších: limit (až 100), cursor, status.
GET /documents/{id}Dokument s jeho stavom, príjemcami a poliami.
POST /documents/{id}/sendOdošle koncept.
POST /documents/{id}/remindPripomenie sa podpisujúcim, ktorí sú na rade (najviac raz za hodinu).
POST /documents/{id}/voidZruší dokument odoslaný na podpis, s voliteľným reason.
DELETE /documents/{id}Odstráni koncept alebo uzavretý dokument.
POST /documents/{id}/prepare_urlNové okno prípravy pre koncept: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlOkno na podpis pre podpisujúceho, ktorý je na rade: origin, redirect_uri, state.
GET /documents/{id}/original.pdfPDF tak, ako bolo odoslané.
GET /documents/{id}/signed.pdfZapečatená kópia, keď všetci podpíšu.
GET /documents/{id}/audit.jsonAuditná stopa: udalosti, hashe a podpisujúci.
GET /documents/{id}/audit.pdfSamostatná zapečatená auditná stopa dokumentu s podpisujúcimi s kvalifikovaným podpisom, keď všetci podpíšu.
POST /uploadsZačne nahrávanie po častiach pre PDF väčšie než 4 MB: size. Potom PUT /uploads/{upload_id}/parts/{n} so surovými bajtmi každej časti.
GET /templatesŠablóny osoby s ich rolami a poliami.
GET /templates/{id}Jedna šablóna.
POST /templatesUloží jeden z dokumentov vašej aplikácie ako šablónu: document_id, name.
DELETE /templates/{id}Odstráni šablónu.

Pri vytváraní dokumentu pošlite hlavičku Idempotency-Key: rovnaký kľúč a telo počas 24 hodín vráti rovnaký dokument (hlavička Idempotent-Replayed: true) namiesto druhého.

Chyby a limity

Chyby majú stav HTTP a telo ako { "error": { "code": "not_found", "message": "..." } }, niekedy s podrobnosťami, naprí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, invalid_provider_allowed, invalid_qes_payer, qualified_signature_required (from_template)
401unauthenticated, invalid_token (vypršal alebo bol zrušený, alebo osoba vašu aplikáciu odobrala)
402payment_required, s checkout_url a amount
403insufficient_scope, sign_api_disabled
404not_found (aj pre dokumenty, ktoré vaša aplikácia nevytvorila), 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 (podpisujúca osoba s level advanced, keď sa vyžadujú kvalifikované podpisy)
429rate_limited, s hlavičkou Retry-After
502payment_unavailable

Prevod aplikácie

Aplikácia sa môže presunúť k inej organizácii registrovanej v Dazr, v časti Previesť aplikáciu v nastaveniach aplikácie. So zapnutým API Dazr Sign sa môže presunúť len k overenej organizácii a vlastník alebo administrátor tam musí prevod do 14 dní prijať. Každý krok opisuje dokumentácia pre vývojárov Dazr Identity.