API-ul Dazr Sign: documentație pentru dezvoltatori

Pregătiți și trimiteți documente spre semnare din propriul software, în numele persoanelor care îl folosesc. Semnatarii semnează cu Dazr Sign ca de obicei: autentificați cu Dazr Identity, pe rând, o singură dată.

Cum funcționează accesul Fiecare document aparține unei persoane cu cont Dazr. Aplicația dumneavoastră acționează pentru acea persoană cu un token de acces pe care l-a aprobat, niciodată în nume propriu. Aplicația vede doar documentele pe care le-a creat, iar persoana o poate opri oricând în Dazr Identity.

Început rapid

  1. Activați API-ul Dazr Sign. În portalul Sign, deschideți Dezvoltatori și alegeți Activați API-ul Dazr Sign pentru aplicația dumneavoastră. Fiecare aplicație a organizației este listată acolo și în consola Dazr Identity, cu același ID și secret de client; fiecare API se activează separat. Puteți înregistra acolo și o aplicație nouă.
  2. Cereți domeniul de acces sign. Trimiteți oamenii prin fluxul obișnuit Autentificare cu Dazr Identity cu scope=openid sign (adăugați offline_access pentru un token de reîmprospătare). Ecranul de consimțământ spune că aplicația poate pregăti și trimite documente spre semnare în numele lor și le poate vedea statutul. Acest lucru funcționează doar cu API-ul Dazr Sign; pentru a cere și datele persoanelor (profile, email și celelalte) trebuie activat și API-ul Dazr Identity.
  3. Apelați API-ul cu tokenul de acces. Adresa de bază este https://sign.dazr.eu/api/sign/v1. Trimiteți Authorization: Bearer <access token> și JSON.
  4. Creați și trimiteți un document. Încărcați un PDF cu etichete de text și o listă de destinatari, apoi trimiteți-l sau deschideți fereastra de pregătire ca persoana să plaseze câmpurile.
// 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"

Etichete de text

Scrieți câmpurile în PDF ca text. Fiecare etichetă este înlocuită cu un câmp de aceeași dimensiune sau mai mare, iar textul etichetei este acoperit, astfel încât semnatarii să nu îl vadă niciodată.

EtichetăCâmp
{{signature:1}}Semnătura primului destinatar
{{initials:2}}Inițialele celui de-al doilea destinatar
{{name:1}} {{date:1}}Numele și data semnării, completate de Dazr Sign
{{text:2:Company}}Un câmp de text cu eticheta Companie
{{checkbox:2:Terms:optional}}O casetă de bifat opțională
{{company:1}}Numele companiei (completat când persoana semnează în numele unei organizații)

Numărul este poziția destinatarului în recipients, începând de la 1. O etichetă pentru un destinatar pe care nu l-ați listat adaugă un destinatar gol, de completat în fereastra de pregătire. Trimiteți "text_tags": false pentru a ignora etichetele. Puteți trimite și fields cu poziții în puncte (1/72 inch) din colțul din stânga sus al paginii: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. O value pe un câmp de text, companie sau casetă de bifat îl fixează: semnatarul îl vede și nu îl poate schimba.

Creați o ciornă cu "prepare": { "origin": "https://app.example.eu" } și primiți un prepare_url. Deschideți-l într-o fereastră: persoana plasează destinatarii și câmpurile într-un editor compact, apoi apasă Trimiteți sau Salvați ca șablon. Pentru un semnatar care este la rând, POST /documents/{id}/recipients/{recipient_id}/signing_url oferă o fereastră de semnare. Ambele linkuri sunt valabile 10-15 minute și funcționează o singură dată. Persoana se autentifică cu Dazr Identity în fereastră dacă este nevoie, cu adresa la care a fost trimis documentul.

Când a terminat, fereastra trimite { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } cu postMessage paginii care a deschis-o, doar dacă acea pagină se află pe una dintre originile de ferestre ale aplicației dumneavoastră (implicit, originile URI-urilor de redirecționare), și se închide. event este sent, saved, cancelled, signed sau declined. Cu redirect_uri (unul dintre URI-urile de redirecționare înregistrate) și state, o fereastră care și-a pierdut pagina de origine revine acolo cu aceleași valori ca parametri de interogare.

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

Dacă pagina dumneavoastră trimite Cross-Origin-Opener-Policy: same-origin, folosiți în schimb same-origin-allow-popups, altfel fereastra nu poate raporta înapoi.

Semnături calificate

Fiecare semnatar are un level: "advanced" (implicit: adresa de e-mail este confirmată prin autentificarea cu Dazr Identity) sau "qualified". Un semnatar calificat descarcă PDF-ul în Dazr Sign, îl semnează cu propria semnătură electronică calificată (o carte electronică de identitate, o aplicație de semnare precum itsme, un certificat calificat în Adobe Acrobat Reader) și încarcă fișierul semnat. Dazr Sign îl verifică în raport cu listele de încredere ale UE și îl acceptă doar dacă este o semnătură calificată pe exact fișierul pe care l-a furnizat. Dazr nu emite semnături calificate.

Setați nivelul pentru fiecare destinatar: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Un semnatar calificat nu are câmpuri de inițiale. name_rule pe document spune ce se întâmplă când numele din certificat diferă de numele destinatarului: "warn" (implicit: acceptat, cu name_matches false) sau "block" (refuzat). Șabloanele păstrează nivelul fiecărui rol, iar from_template poate ridica un rol la "qualified".

Fiecare semnătură rămâne validă: semnăturile ulterioare și sigiliul final Dazr sunt adăugate ca actualizări incrementale, iar jurnalul de audit al unui astfel de document este un PDF sigilat separat la GET /documents/{id}/audit.pdf. Destinatarii din documente și webhookuri au level și, după ce un semnatar calificat a semnat, 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 sau CAdES) și name_matches. Orice alt level dă 400 invalid_level.

Webhookuri

Setați un URL de webhook pentru aplicație în portalul Sign, la Dezvoltatori. Primiți secretul de semnare o singură dată. Dazr Sign trimite sign.document.sent, viewed, signed, completed, declined, voided și expired pentru documentele create de aplicația dumneavoastră, cu statutul documentului și al destinatarilor, niciodată cu conținutul. Livrările eșuate sunt reîncercate după 5 minute, 30 de minute, 2, 6, 12 și 24 de ore; jurnalul livrărilor arată fiecare încercare și poate retrimite una.

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

Referință

Toate căile încep cu https://sign.dazr.eu/api/sign/v1. Orele sunt ISO 8601 în UTC.

CerereCe face
POST /documentsCreează o ciornă dintr-un PDF: file în base64, o încărcare multipart (file plus data ca JSON) sau un upload_id. Opțional: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateCreează o ciornă dintr-un șablon: template_id, recipients ca { role, name, email }, values după ID-ul sau eticheta câmpului.
GET /documentsListează documentele aplicației pentru această persoană, cele mai noi primele: limit (până la 100), cursor, status.
GET /documents/{id}Documentul cu statutul, destinatarii și câmpurile sale.
POST /documents/{id}/sendTrimite o ciornă.
POST /documents/{id}/remindLe reamintește semnatarilor care sunt la rând (cel mult o dată pe oră).
POST /documents/{id}/voidAnulează un document trimis spre semnare, cu un reason opțional.
DELETE /documents/{id}Șterge o ciornă sau un document închis.
POST /documents/{id}/prepare_urlO nouă fereastră de pregătire pentru o ciornă: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlO fereastră de semnare pentru un semnatar care este la rând: origin, redirect_uri, state.
GET /documents/{id}/original.pdfPDF-ul așa cum a fost trimis.
GET /documents/{id}/signed.pdfCopia sigilată, după ce toți au semnat.
GET /documents/{id}/audit.jsonJurnalul de audit: evenimente, hashuri și semnatari.
GET /documents/{id}/audit.pdfJurnalul de audit separat și sigilat al unui document cu semnatari calificați, după ce toți au semnat.
POST /uploadsPornește o încărcare pe părți pentru PDF-urile de peste 4 MB: size. Apoi PUT /uploads/{upload_id}/parts/{n} cu octeții bruți ai fiecărei părți.
GET /templatesȘabloanele persoanei, cu rolurile și câmpurile lor.
GET /templates/{id}Un șablon.
POST /templatesSalvează unul dintre documentele aplicației ca șablon: document_id, name.
DELETE /templates/{id}Șterge un șablon.

Trimiteți un antet Idempotency-Key când creați un document: aceeași cheie și același corp în 24 de ore returnează același document (antet Idempotent-Replayed: true) în loc de unul nou.

Erori și limite

Erorile au un statut HTTP și un corp precum { "error": { "code": "not_found", "message": "..." } }, uneori cu detalii precum index.

StatutCoduri
400invalid_field, invalid_recipients, invalid_email, not_pdf, pdf_unreadable, pdf_encrypted, invalid_origin, invalid_redirect_uri, unknown_role, unknown_field
401unauthenticated, invalid_token (expirat sau revocat ori persoana a eliminat aplicația)
403insufficient_scope, sign_api_disabled
404not_found (și pentru documentele pe care nu le-a creat aplicația), 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, cu un antet Retry-After

Transferul unei aplicații

O aplicație poate trece la altă organizație înregistrată pe Dazr, din Transferați aplicația, în setările aplicației. Cu API-ul Dazr Sign activat, poate trece doar la o organizație verificată, iar un proprietar sau administrator de acolo trebuie să accepte în 14 zile. Documentația Dazr Identity pentru dezvoltatori descrie fiecare pas.