Dazr Sign API: documentazione per sviluppatori

Guida rapida

  1. 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.
  2. Richieda lo scope sign. Faccia passare le persone dal consueto flusso Accedi con Dazr Identity con scope=openid sign (aggiunga offline_access per 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, email e gli altri) serve anche la Dazr Identity API.
  3. Chiami l’API con il token di accesso. L’indirizzo di base è https://sign.dazr.eu/api/sign/v1. Invii Authorization: Bearer <access token> e JSON.
  4. 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.

TagCampo
{{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.

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.

RichiestaCosa fa
POST /documentsCrea 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_templateCrea una bozza da un modello: template_id, recipients come { role, name, email }, values per ID o etichetta del campo.
GET /documentsElenca 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}/sendInvia una bozza.
POST /documents/{id}/remindRicorda la firma a chi è di turno (al massimo una volta all’ora).
POST /documents/{id}/voidAnnulla un documento in attesa di firma, con un reason facoltativo.
DELETE /documents/{id}Elimina una bozza o un documento chiuso.
POST /documents/{id}/prepare_urlUn nuovo popup di preparazione per una bozza: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlUn popup di firma per chi firma ed è di turno: origin, redirect_uri, state.
GET /documents/{id}/original.pdfIl PDF così come è stato inviato.
GET /documents/{id}/signed.pdfLa copia sigillata, quando tutti hanno firmato.
GET /documents/{id}/audit.jsonL’audit trail: eventi, hash e firmatari.
GET /documents/{id}/audit.pdfL’audit trail separato e sigillato di un documento con firme qualificate, quando tutti hanno firmato.
POST /uploadsAvvia un caricamento a parti per PDF oltre 4 MB: size. Poi PUT /uploads/{upload_id}/parts/{n} con i byte di ogni parte.
GET /templatesI modelli della persona, con ruoli e campi.
GET /templates/{id}Un modello.
POST /templatesSalva 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.

StatoCodici
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 (scaduto o revocato, oppure la persona ha rimosso la Sua app)
402payment_required, con checkout_url e amount
403insufficient_scope, sign_api_disabled
404not_found (anche per i documenti che la Sua app non ha creato), 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 (chi firma con level simple quando sono richieste firme qualificate)
429rate_limited, con un’intestazione Retry-After
502payment_unavailable

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.