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ă.
- Început rapid
- Etichete de text
- Ferestre
- Semnături cu identitate verificată
- Semnături calificate
- Cererea semnăturilor calificate
- Certificate prin Dazr
- Webhookuri
- Referință
- Erori și limite
- Transferuri
Început rapid
- 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ă.
- Cereți domeniul de acces
sign. Trimiteți oamenii prin fluxul obișnuit Autentificare cu Dazr Identity cuscope=openid sign(adăugațioffline_accesspentru 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. - Apelați API-ul cu tokenul de acces. Adresa de bază este
https://sign.dazr.eu/api/sign/v1. TrimitețiAuthorization: Bearer <access token>și JSON. - 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.
Ferestre: pregătire și semnare
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 cu identitate verificată
Unui semnatar cu nivelul "simple" i se poate cere o semnătură cu identitate verificată, o semnătură electronică avansată conform eIDAS: { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. Este dezactivată dacă nu o setați, și doar pentru semnatarii cu nivelul "simple" (altfel 400 invalid_id_verified; un document nu o poate combina cu semnatari calificați: 400 id_verification_with_qualified). Semnatarul semnează ca de obicei, apoi își verifică identitatea cu Dazr Identity: o fotografie a actului de identitate și un selfie, analizate de o persoană de la Dazr, sau o verificare pe care o are deja, cu acordul său. Șabloanele o păstrează pe rol, iar from_template acceptă id_verified pentru fiecare destinatar.
Semnătura contează, iar documentul se finalizează, doar după aprobarea verificării. Până atunci documentul rămâne sent cu waiting_for_id_verification true și fără PDF semnat. Destinatarii au id_verified și id_verification: status (not_signed, to_verify, verifying, review, verified sau rejected), verified_at și name_matches. Webhook-urile adaugă sign.document.id_verified și sign.document.id_rejected. După o respingere, expeditorul poate cere în portalul Sign o nouă semnătură; semnătura nu contează niciodată ca una simplă în schimb.
Fiecare verificare costă EUR 1,50 fără TVA din soldul al organizației aplicației, încasați când semnatarul o pornește sau folosește una existentă (o dată pe verificare și organizație). send răspunde 402 id_verification_payer când aplicația nu are o organizație și 402 id_verification_balance (cu needCents) când soldul nu acoperă semnatarii cu verificarea identității.
Semnături calificate
Fiecare semnatar are un level: "simple" (implicit: o semnătură electronică simplă conform eIDAS, cu adresa de e-mail confirmată prin autentificarea în Dazr Identity, un jurnal de audit detaliat și un PDF sigilat) sau "qualified". "advanced", denumirea folosită înainte de 13 octombrie 2026, este în continuare acceptată și înseamnă "simple"; răspunsurile și webhookurile indică "simple". Un semnatar calificat descarcă PDF-ul în Dazr Sign, îl semnează cu propria semnătură electronică calificată (o carte de identitate electronică sau un certificat calificat în Adobe Acrobat Reader) și încarcă fișierul semnat. Dazr Sign îl verifică în listele de încredere ale UE și îl acceptă doar dacă este o semnătură calificată exact pe fișierul pe care l-a furnizat. Dazr nu emite certificate.
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.
Cererea semnăturilor calificate
Proprietarii și administratorii unei organizații pot cere o semnătură electronică calificată de la toate persoanele care semnează: pentru documentele create de o aplicație (pagina aplicației din Dezvoltatori, în portalul Sign) sau pentru documentele trimise de membrii organizației (Setări, în portalul Sign). Dazr Sign aplică regula pe server. Cine semnează fără level semnează calificat, "level": "simple" returnează 422 qualified_signature_required cu index-ul destinatarului, rolurile din șabloane devin calificate (cererea unui rol simplu la from_template returnează 400 qualified_signature_required), iar un document este finalizat doar după verificarea semnăturii calificate a fiecărei persoane. Documentele arată qes_required.
Certificate prin Dazr
Dazr nu emite certificate, dar poate obține unul de la un prestator calificat de servicii de încredere când această opțiune este activată. Atunci "provider_allowed": true pentru un semnatar calificat îi permite să obțină astfel un certificat calificat dacă nu are. Își confirmă identitatea la prestator (act de identitate, apel video) și apoi semnează pe pagina de semnare cu un cod unic din aplicația prestatorului. Dazr nu păstrează niciodată date de semnare: numele dispozitivului, PIN-ul și codul unic merg la prestator doar pentru acea semnătură. PDF-ul semnat este verificat ca o încărcare. Certificatul aparține semnatarului timp de 3 ani și semnează documente Dazr ulterioare fără cost suplimentar. În certificate, issued_through indică prestatorul (null pentru certificatul propriu al semnatarului).
Această opțiune nu este activată în prezent: provider_allowed este acceptat și nu are efect până când va fi.
Plătește persoana care semnează, pe pagina de semnare (implicit), sau organizația aplicației plătește în avans: "qes_payer": "organisation" pe document sau setarea aplicației. Atunci send răspunde 402 payment_required cu checkout_url (o pagină de plată) și amount (net, vat, total, certificates), iar documentul este trimis imediat ce plata este primită (sign.document.sent). Un certificat plătit în avans pe care nu îl folosește nimeni este rambursat când documentul este finalizat, anulat, refuzat sau expiră. Documentele arată qes_payer: "signer" sau "organisation".
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.
| Cerere | Ce face |
|---|---|
POST /documents | Creează 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_template | Creează o ciornă dintr-un șablon: template_id, recipients ca { role, name, email }, values după ID-ul sau eticheta câmpului. |
GET /documents | Listează 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}/send | Trimite o ciornă. |
POST /documents/{id}/remind | Le reamintește semnatarilor care sunt la rând (cel mult o dată pe oră). |
POST /documents/{id}/void | Anulează un document trimis spre semnare, cu un reason opțional. |
DELETE /documents/{id} | Șterge o ciornă sau un document închis. |
POST /documents/{id}/prepare_url | O nouă fereastră de pregătire pentru o ciornă: origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | O fereastră de semnare pentru un semnatar care este la rând: origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | PDF-ul așa cum a fost trimis. |
GET /documents/{id}/signed.pdf | Copia sigilată, după ce toți au semnat. |
GET /documents/{id}/audit.json | Jurnalul de audit: evenimente, hashuri și semnatari. |
GET /documents/{id}/audit.pdf | Jurnalul de audit separat și sigilat al unui document cu semnatari calificați, după ce toți au semnat. |
POST /uploads | Porneș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 /templates | Salvează 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.
| Stare | Coduri |
|---|---|
400 | invalid_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) |
401 | unauthenticated, invalid_token (expirat sau revocat ori persoana a eliminat aplicația) |
402 | payment_required, cu checkout_url și amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (și pentru documentele pe care nu le-a creat aplicația), template_not_found |
409 | not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress, payment_in_progress |
413 | pdf_too_large, too_large, quota |
422 | idempotency_key_reused, qualified_signature_required (o persoană care semnează cu level simple când sunt cerute semnături calificate) |
429 | rate_limited, cu un antet Retry-After |
502 | payment_unavailable |
- PDF-uri de până la 25 MB și 200 de pagini, fără parolă. Cereri de până la 4 MB; PDF-urile mai mari trec prin
/uploads. - Până la 20 de destinatari și 400 de câmpuri per document, 100 de șabloane per persoană. Documentele și șabloanele se socotesc în spațiul de stocare Dazr al persoanei.
- 120 de cereri pe minut pentru fiecare persoană per aplicație, 30 de documente noi la fiecare 10 minute și 30 de trimiteri pe oră.
- Tokenurile de acces durează 10 minute. Folosiți tokenul de reîmprospătare (
offline_access) pentru a obține unul nou.
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.
- Documentele create de aplicație înainte de transfer rămân la persoanele cărora le aparțin. Aplicația nu le mai vede prin API și nu se mai trimit webhookuri pentru ele.
- URL-ul webhookului și originile pop-up-urilor rămân. Secretul de semnare al webhookului este reînnoit și afișat o singură dată administratorului care acceptă.
- Tokenurile de acces și de reîmprospătare emise înainte de transfer nu mai funcționează, iar persoanele aprobă din nou aplicația la următoarea autentificare. Șabloanele aparțin persoanelor și nu sunt afectate.
- Numărul de documente din portalul Sign pornește din nou de la transfer.