EzySign
/Docs

Getting Started

Questa guida ti porta da zero alla prima richiesta di firma in pochi minuti. EzySign è un servizio di firma elettronica semplice (FES) erogato come API: il tuo backend dialoga con il nostro tramite chiamate HTTPS autenticate, mentre il firmatario riceve un link a una pagina ospitata da noi (o sotto il tuo brand) e firma con OTP via email o SMS.

1. Ottieni una chiave API

Le chiavi API sono associate al tuo tenant. Per generarne una contatta il supporto o accedi al pannello amministrativo. Ogni chiave ha la forma:

esf_<prefix>_<secret>
  • prefix: 8 caratteri pubblici, utili per identificare la chiave nei log.
  • secret: 32 caratteri, mostrati una sola volta al momento dell'emissione. Conservali in un secret store (Vault, AWS Secrets Manager, k8s Secret).
Sicurezza: non incorporare mai la chiave nel codice client (browser, app mobile). Le chiamate alle API EzySign devono partire dal tuo backend.

2. Verifica l'ambiente

Effettua una prima chiamata di health check per verificare connettività e validità della chiave:

curl -i https://api.ezysign.net/api/v1/dossiers \
  -H "X-API-Key: esf_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • 200 OK con un array (anche vuoto): la chiave è valida.
  • 401 Unauthorized: chiave mancante o non valida.
  • 429 Too Many Requests: rate limit superato (vedi API Reference).

3. Prepara il documento

EzySign accetta esclusivamente file PDF. Il file viene trasmesso in body codificato in base64. Limiti:

  • Dimensione massima del payload JSON: 25 MB
  • Numero massimo di punti di firma (signPoints): 20
  • Validità link firma: configurabile da 1 a 720 ore (default 168 = 7 giorni)

Se non specifichi signPoints, EzySign aggiunge automaticamente un riquadro di firma sull'ultima pagina del documento.

4. Crea il primo dossier

Il payload minimo richiede firmatario, canale OTP e documento:

POST /api/v1/dossiers
Content-Type: application/json
X-API-Key: esf_...

{
  "signer": {
    "firstName": "Mario",
    "lastName": "Rossi",
    "email": "[email protected]"
  },
  "otpChannel": "email",
  "document": {
    "name": "Contratto.pdf",
    "contentBase64": "JVBERi0xLjQK..."
  },
  "callbackUrl": "https://miosito.it/webhooks/ezysign"
}

Risposta tipica (200 OK):

{
  "id": "8c1e4f2a-...",
  "status": "sent",
  "signerUrl": "https://ezysign.net/sign/abc123...",
  "signedDocumentUrl": null,
  "evidenceUrl": null,
  "createdAt": "2026-04-27T10:00:00.000Z",
  "sentAt":    "2026-04-27T10:00:00.000Z",
  "viewedAt":  null,
  "signedAt":  null,
  "expiresAt": "2026-05-04T10:00:00.000Z"
}

L'OTP viene inviato immediatamente sul canale richiesto. Lo signerUrl può essere comunicato al firmatario in autonomia (es. nella tua interfaccia), oppure puoi affidarti alla sola email/SMS che inviamo noi: il link è già contenuto nel messaggio.

5. Ricevi notifiche di stato (webhook)

Se imposti callbackUrl nel payload, EzySign invierà eventi sul ciclo di vita del dossier al tuo endpoint, firmati con HMAC SHA-256. Vedi Webhooks per struttura, header di firma ed esempi di verifica.

6. Prossimi passi

  • Quickstart — esempi completi in più linguaggi.
  • API Reference — tutti gli endpoint e i codici risposta.
  • Note legali — valore probatorio della firma, conservazione, GDPR.