Dazr Sign API: documentazione per sviluppatori
Prepari e invii documenti da firmare dal Suo software, a nome delle persone che lo usano. Chi firma lo fa come sempre con Dazr Sign: con accesso tramite Dazr Identity, al proprio turno, una sola volta.
- Guida rapida
- Tag di testo
- Popup
- Firme con identità verificata
- Firme qualificate
- Richiedere firme qualificate
- Certificati tramite Dazr
- Webhook
- Riferimento
- Errori e limiti
- Trasferimenti
Guida rapida
- Attivi la Dazr Sign API. Nel portale Sign apra Sviluppatori e scelga Attiva Dazr Sign API per la Sua app. Ogni app della Sua organizzazione è elencata lì e nella console di Dazr Identity, con lo stesso client ID e lo stesso secret; ogni API si attiva a parte. Lì può anche registrare una nuova app.
- Richieda lo scope
sign. Faccia passare le persone dal consueto flusso Accedi con Dazr Identity conscope=openid sign(aggiungaoffline_accessper un refresh token). La schermata di consenso spiega che la Sua app può preparare e inviare documenti da firmare a loro nome e vederne lo stato. Basta la Dazr Sign API; per chiedere anche i dati delle persone (profile,emaile gli altri) serve anche la Dazr Identity API. - Chiami l’API con il token di accesso. L’indirizzo di base è
https://sign.dazr.eu/api/sign/v1. InviiAuthorization: Bearer <access token>e JSON. - Crei e invii un documento. Carichi un PDF con tag di testo e un elenco di destinatari e lo invii, oppure apra il popup di preparazione per far posizionare i campi alla persona.
// 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"
Tag di testo
Scriva i campi nel PDF come testo. Ogni tag viene sostituito da un campo della stessa dimensione o più grande, e il testo del tag viene coperto, così chi firma non lo vede mai.
| Tag | Campo |
|---|---|
{{signature:1}} | Firma del primo destinatario |
{{initials:2}} | Iniziali del secondo destinatario |
{{name:1}} {{date:1}} | Nome e data della firma, compilati da Dazr Sign |
{{text:2:Company}} | Un campo di testo con l’etichetta Company |
{{checkbox:2:Terms:optional}} | Una casella di controllo facoltativa |
{{company:1}} | Ragione sociale (compilata quando la persona firma per conto di un’organizzazione) |
Il numero è la posizione del destinatario in recipients, a partire da 1. Un tag per un destinatario non indicato aggiunge un destinatario vuoto, da completare nel popup di preparazione. Invii "text_tags": false per ignorare i tag. Può anche inviare fields con posizioni in punti (1/72 di pollice) dall’angolo in alto a sinistra della pagina: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. Un value su un campo di testo, ragione sociale o casella lo fissa: chi firma lo vede ma non può modificarlo.
Popup: preparare e firmare
Crei una bozza con "prepare": { "origin": "https://app.example.eu" } e riceva un prepare_url. Lo apra in un popup: la persona posiziona destinatari e campi in un editor compatto, poi fa clic su Invia o Salva come modello. Per chi firma ed è di turno, POST /documents/{id}/recipients/{recipient_id}/signing_url restituisce un popup di firma. Entrambi i link valgono da 10 a 15 minuti e funzionano una sola volta. Se serve, la persona accede a Dazr Identity nel popup, con l’indirizzo a cui è stato inviato il documento.
Al termine, il popup invia { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } con postMessage alla pagina che lo ha aperto, solo se quella pagina si trova su una delle origini popup della Sua app (di default, le origini dei Suoi redirect URI), e si chiude. event è sent, saved, cancelled, signed o declined. Con redirect_uri (uno dei Suoi redirect URI registrati) e state, un popup che ha perso la pagina di origine torna lì con gli stessi valori come parametri della query.
<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>
Se la Sua pagina invia Cross-Origin-Opener-Policy: same-origin, usi invece same-origin-allow-popups, altrimenti il popup non può comunicare il risultato.
Firme con identità verificata
A una persona con livello "simple" si può chiedere una firma con identità verificata, una firma elettronica avanzata secondo eIDAS: { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. È disattivata se non la imposta, e solo per chi ha livello "simple" (altrimenti 400 invalid_id_verified; un documento non può combinarla con firmatari qualificati: 400 id_verification_with_qualified). La persona firma come sempre, poi verifica la propria identità con Dazr Identity: una foto del documento d’identità e un selfie, esaminati da una persona di Dazr, oppure una verifica che ha già, con il suo consenso. I modelli la conservano per ruolo, e from_template accetta id_verified per destinatario.
La firma vale, e il documento si completa, solo quando la verifica è approvata. Fino ad allora il documento resta sent con waiting_for_id_verification true e senza PDF firmato. I destinatari hanno id_verified e id_verification: status (not_signed, to_verify, verifying, review, verified o rejected), verified_at e name_matches. I webhook aggiungono sign.document.id_verified e sign.document.id_rejected. Dopo un rifiuto, il mittente può chiedere alla persona di firmare di nuovo nel portale Sign; la firma non vale mai come semplice al suo posto.
Ogni verifica costa EUR 1,50 IVA esclusa dal saldo dell’organizzazione dell’app, addebitati quando la persona la avvia o ne usa una esistente (una volta per verifica e organizzazione). send risponde 402 id_verification_payer se l’app non ha un’organizzazione e 402 id_verification_balance (con needCents) se il saldo non copre i firmatari con verifica dell’identità.
Firme qualificate
Ogni firmatario ha un level: "simple" (predefinito: una firma elettronica semplice secondo eIDAS, con l’indirizzo email confermato con l’accesso a Dazr Identity, un audit trail dettagliato e un PDF sigillato) o "qualified". "advanced", il nome usato prima del 13 ottobre 2026, è ancora accettato e significa "simple"; risposte e webhook indicano "simple". Un firmatario qualificato scarica il PDF in Dazr Sign, lo firma con la propria firma elettronica qualificata (una carta d’identità elettronica o un certificato qualificato in Adobe Acrobat Reader) e carica il file firmato. Dazr Sign lo verifica sugli elenchi di fiducia dell’UE e lo accetta solo se è una firma qualificata esattamente sul file consegnato. Dazr non rilascia certificati.
Imposti il livello per ogni destinatario: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Chi firma con firma qualificata non ha campi per le sigle. name_rule sul documento stabilisce cosa succede se il nome sul certificato è diverso da quello del destinatario: "warn" (predefinito: accettata, con name_matches false) o "block" (rifiutata). I modelli conservano il livello di ogni ruolo, e from_template può alzare un ruolo a "qualified".
Ogni firma resta valida: le firme successive e il sigillo finale di Dazr vengono aggiunti come aggiornamenti incrementali, e l’audit trail di questi documenti è un PDF sigillato separato in GET /documents/{id}/audit.pdf. I destinatari nei documenti e nei webhook hanno level e, dopo la firma qualificata, 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 o CAdES) e name_matches. Qualsiasi altro level restituisce 400 invalid_level.
Richiedere firme qualificate
Proprietari e amministratori di un’organizzazione possono richiedere una firma elettronica qualificata a chiunque firmi: per i documenti creati da un’app (la pagina dell’app in Sviluppatori nel portale Sign) o per i documenti inviati dai membri dell’organizzazione (Impostazioni nel portale Sign). Dazr Sign lo applica sul server. Chi firma senza level firma in modo qualificato, "level": "simple" restituisce 422 qualified_signature_required con l’index del destinatario, i ruoli dei modelli diventano qualificati (chiedere un ruolo semplice a from_template restituisce 400 qualified_signature_required) e un documento si completa solo quando la firma qualificata di ogni firmatario è stata verificata. I documenti mostrano qes_required.
Certificati tramite Dazr
Dazr non rilascia certificati, ma può procurarne uno presso un prestatore di servizi fiduciari qualificato quando questa opzione è attiva. Allora "provider_allowed": true su un firmatario qualificato che non ne ha gli permette di ottenere così un certificato qualificato. Conferma la propria identità presso il prestatore (documento d’identità, videochiamata) e poi firma nella pagina di firma con un codice monouso dall’app del prestatore. Dazr non conserva mai credenziali di firma: nome del dispositivo, PIN e codice monouso vanno al prestatore solo per quella firma. Il PDF firmato viene verificato come un caricamento. Il certificato resta del firmatario per 3 anni e firma i successivi documenti Dazr senza costi aggiuntivi. In certificate, issued_through indica il prestatore (null per il certificato proprio del firmatario).
Questa opzione al momento non è attiva: provider_allowed viene accettato e non ha effetto finché non lo sarà.
Paga chi firma nella pagina di firma (impostazione predefinita), oppure l’organizzazione dell’app paga in anticipo: "qes_payer": "organisation" sul documento, o l’impostazione dell’app. In tal caso send risponde 402 payment_required con checkout_url (una pagina di pagamento) e amount (net, vat, total, certificates), e il documento viene inviato appena arriva il pagamento (sign.document.sent). Un certificato prepagato che nessuno usa viene rimborsato quando il documento è completato, annullato, rifiutato o scaduto. I documenti mostrano qes_payer: "signer" o "organisation".
Webhook
Imposti un URL webhook per la Sua app nel portale Sign, in Sviluppatori. Vede il secret di firma una sola volta. Dazr Sign invia sign.document.sent, viewed, signed, completed, declined, voided ed expired per i documenti creati dalla Sua app, con lo stato del documento e dei destinatari, mai il contenuto. Le consegne non riuscite vengono ritentate dopo 5 minuti, 30 minuti, 2, 6, 12 e 24 ore; il registro delle consegne mostra ogni tentativo e permette di reinviarne 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: [...] } } }
Riferimento
Tutti i percorsi iniziano con https://sign.dazr.eu/api/sign/v1. Gli orari sono in ISO 8601, UTC.
| Richiesta | Cosa fa |
|---|---|
POST /documents | Crea una bozza da un PDF: file in base64, un caricamento multipart (file più data come JSON) o un upload_id. Facoltativi: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare. |
POST /documents/from_template | Crea una bozza da un modello: template_id, recipients come { role, name, email }, values per ID o etichetta del campo. |
GET /documents | Elenca i documenti della Sua app per questa persona, dai più recenti: limit (fino a 100), cursor, status. |
GET /documents/{id} | Il documento con stato, destinatari e campi. |
POST /documents/{id}/send | Invia una bozza. |
POST /documents/{id}/remind | Ricorda la firma a chi è di turno (al massimo una volta all’ora). |
POST /documents/{id}/void | Annulla un documento in attesa di firma, con un reason facoltativo. |
DELETE /documents/{id} | Elimina una bozza o un documento chiuso. |
POST /documents/{id}/prepare_url | Un nuovo popup di preparazione per una bozza: origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | Un popup di firma per chi firma ed è di turno: origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | Il PDF così come è stato inviato. |
GET /documents/{id}/signed.pdf | La copia sigillata, quando tutti hanno firmato. |
GET /documents/{id}/audit.json | L’audit trail: eventi, hash e firmatari. |
GET /documents/{id}/audit.pdf | L’audit trail separato e sigillato di un documento con firme qualificate, quando tutti hanno firmato. |
POST /uploads | Avvia un caricamento a parti per PDF oltre 4 MB: size. Poi PUT /uploads/{upload_id}/parts/{n} con i byte di ogni parte. |
GET /templates | I modelli della persona, con ruoli e campi. |
GET /templates/{id} | Un modello. |
POST /templates | Salva come modello uno dei documenti della Sua app: document_id, name. |
DELETE /templates/{id} | Elimina un modello. |
Invii un’intestazione Idempotency-Key quando crea un documento: la stessa chiave e lo stesso corpo entro 24 ore restituiscono lo stesso documento (intestazione Idempotent-Replayed: true) invece di crearne un secondo.
Errori e limiti
Gli errori hanno uno stato HTTP e un corpo come { "error": { "code": "not_found", "message": "..." } }, a volte con dettagli come index.
| Stato | Codici |
|---|---|
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 (scaduto o revocato, oppure la persona ha rimosso la Sua app) |
402 | payment_required, con checkout_url e amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (anche per i documenti che la Sua app non ha creato), 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 (chi firma con level simple quando sono richieste firme qualificate) |
429 | rate_limited, con un’intestazione Retry-After |
502 | payment_unavailable |
- PDF fino a 25 MB e 200 pagine, senza password. Richieste fino a 4 MB; i PDF più grandi passano da
/uploads. - Fino a 20 destinatari e 400 campi per documento, 100 modelli per persona. Documenti e modelli contano nello spazio Dazr della persona.
- 120 richieste al minuto per persona per app, 30 nuovi documenti ogni 10 minuti e 30 invii all’ora.
- I token di accesso durano 10 minuti. Usi il refresh token (
offline_access) per ottenerne uno nuovo.
Trasferire un’app
Un’app può passare a un’altra organizzazione registrata su Dazr, con Trasferisci app nelle impostazioni dell’app. Con la Dazr Sign API attiva può passare solo a un’organizzazione verificata, e chi la possiede o la amministra deve accettare entro 14 giorni. La documentazione per sviluppatori di Dazr Identity descrive ogni passaggio.
- I documenti creati dalla Sua app prima del trasferimento restano alle persone a cui appartengono. L’app non li vede più tramite l’API e non vengono inviati webhook per loro.
- L’URL del webhook e le origini dei popup restano. Il secret di firma del webhook viene rinnovato e mostrato una volta sola a chi accetta.
- I token di accesso e di aggiornamento emessi prima del trasferimento smettono di funzionare, e le persone approvano di nuovo l’app al prossimo accesso. I modelli appartengono alle persone e non cambiano.
- I conteggi dei documenti nel portale Sign ripartono dal trasferimento.