Salta ai contenuti
bona fidedocs

Sessioni e link di firma

I destinatari firmano sulla pagina di firma di Bona Fide: la pagina ospitata su https://sign.bonafidesign.com/s/… oppure la stessa pagina integrata nel Suo prodotto con <bf-signing>. I destinatari non hanno bisogno di un account. Ciò che consente loro di accedere è una sessione di firma.

Sessioni di firma

Sezione intitolata “Sessioni di firma”

La consegna via e-mail crea le sessioni al posto Suo (il link nell’e-mail). Per la firma integrata o consegnata da Lei, ne crei una dal Suo backend:

Finestra del terminale
curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'
{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}
Campo Note
recipient Un destinatario della busta che può ancora firmare (non in CC, non concluso)
mode embedded (predefinito) o hosted. Gli url ospitati hanno la forma …/s/<token>, verso cui reindirizzare o da inviare personalmente
allowedOrigins Fino a 10 origini autorizzate a incorporare la pagina integrata in un frame
returnUrl Dove la pagina ospitata reindirizza il firmatario quando ha terminato
ttlSeconds Da 60 a 3600, predefinito 600

Le sessioni sono monouso: una volta che il destinatario ha inviato, la sessione è consumata, e una sessione usata o scaduta risponde 410 Gone. Ne crei una nuova ogni volta che la Sua pagina viene visualizzata. Le sessioni si possono creare solo mentre la busta è sent e l’annullamento della busta le chiude tutte.

I passaggi del firmatario

Sezione intitolata “I passaggi del firmatario”

La pagina di firma (e qualsiasi interfaccia personalizzata costruita sulla stessa API) segue questi passaggi:

  1. Scambio: POST /v1/signing/exchange { "token": "bfs_…" } restituisce un token di accesso di breve durata (bfa_…) conservato in memoria. Non vengono usati cookie, quindi il blocco dei cookie di terze parti non ha importanza in un iframe.
  2. Caricamento: GET /v1/signing/session restituisce la vista del firmatario (titolo della busta, mittente, ruolo e campi del destinatario, valori precompilati, informativa per il consumatore) e registra recipient.viewed la prima volta. GET /v1/signing/document è il PDF da visualizzare.
  3. Verifica (solo con email_otp): POST /v1/signing/otp invia via e-mail un codice di sei cifre (valido 10 minuti) e POST /v1/signing/otp/verify lo controlla. Un codice errato restituisce verified: false con i tentativi rimasti. Il campo verification.verified della vista è già true quando il metodo del destinatario non richiede un codice.
  4. Invio: POST /v1/signing/submit con i values dei campi (firme disegnate, digitate o caricate), il consenso all’informativa e viewedDocumentHash: lo SHA-256 dell’esatto PDF che è stato mostrato. Se nel frattempo il documento è cambiato, l’invio viene rifiutato (409).
  5. Oppure rifiuto: POST /v1/signing/decline { "reason": "…" } chiude la busta (envelope.declined).

È il turno del destinatario solo quando tutti i gruppi di instradamento precedenti hanno terminato; prima di allora la vista ha canSign: false e un invio risponde 409 not-your-turn.

Verifica del firmatario

Sezione intitolata “Verifica del firmatario”

Ogni destinatario ha un metodo di verification: quello del ruolo (impostato nel pannello dei ruoli dell’editor di modelli), a meno che la busta non lo sostituisca per il singolo destinatario (nella schermata di invio o con recipients[].verification).

Metodo Che cosa fa il firmatario Quando usarlo
none (predefinito) Apre il link di firma univoco e firma Il link gli viene inviato via e-mail: lo ha solo chi ha accesso a quella casella di posta
email_otp Apre il link, poi inserisce un codice di sei cifre inviato via e-mail allo stesso indirizzo Quando si vuole una seconda prova, recente, al momento della firma (contratti di valore elevato, caselle di posta condivise)
integrator_asserted Firma nel Suo prodotto, che ne garantisce l’identità (externalUserId) Firma integrata dietro il Suo sistema di accesso

none è il valore predefinito perché il link che Bona Fide invia via e-mail è di per sé univoco per il destinatario e non indovinabile: aprirlo dimostra il controllo dell’indirizzo e-mail, che è l’attribuzione su cui si basano le leggi sulla firma elettronica (ESIGN / UETA negli Stati Uniti, firme elettroniche semplici ai sensi di eIDAS). Anche i prodotti analoghi lo usano come impostazione predefinita. I modelli pubblicati con email_otp lo mantengono e un email_otp esplicito continua a funzionare ovunque.

Due flussi non si affidano mai al solo link:

  • Link di firma sempre attivi (/l/…): il visitatore digita il proprio indirizzo, quindi conferma sempre un codice inviato via e-mail prima che venga creata una busta, qualunque cosa preveda il modello.
  • Sessioni create da Lei (POST /v1/envelopes/{id}/sessions): non portano alcuna prova dell’indirizzo e-mail. Questo è compito del Suo sistema di accesso, quindi per queste sessioni usi integrator_asserted (con externalUserId) oppure email_otp.

Il certificato di completamento registra, per ogni firmatario, che cosa è stato effettivamente usato:

Registrato come Quando
Link via e-mail (link univoco inviato a indirizzo) none, firmato dal link ricevuto via e-mail
Link via e-mail + codice monouso (inviato a indirizzo) email_otp, firmato dal link ricevuto via e-mail
Link di firma + codice monouso (inviato a indirizzo) Un visitatore di un link sempre attivo
Codice monouso (inviato a indirizzo) email_otp in una sessione creata da Lei
Sessione di firma emessa dal mittente none in una sessione creata da Lei
Asserzione dell’integratore integrator_asserted

Il riepilogo pubblico della verifica mostra le stesse etichette senza l’indirizzo.

Lingue

Sezione intitolata “Lingue”

La pagina di firma, le sue e-mail (richiesta, promemoria, codici, completamento, annullamento), la pagina del link sempre attivo e la pagina di stato degli osservatori sono disponibili in 50 lingue. Un firmatario le vede in questo ordine di preferenza:

  1. la lingua scelta dal menu delle lingue della pagina (memorizzata su quel dispositivo);
  2. <bf-signing locale="…"> (firma integrata) o ?locale= su un link ospitato;
  3. il locale del destinatario, impostato alla creazione della busta (recipients[].locale, oppure locale sulla busta per tutti quelli che non ne hanno uno proprio);
  4. la lingua del browser.

Le e-mail hanno bisogno di una lingua prima che qualcuno apra una pagina, quindi usano il locale del destinatario e, in sua assenza, sono in inglese. I link sempre attivi inviano l’e-mail con il codice nella lingua mostrata dalla pagina del visitatore.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

I tag simili vengono accettati e memorizzati come la lingua a cui corrispondono (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); qualsiasi altro valore è un errore di validazione. Le informative sul consenso tradotte indicano che si applica il testo inglese e il firmatario può passare a quest’ultimo; la lingua in cui l’informativa è stata letta viene registrata con la firma (consentLocale nell’evento di audit recipient.signed).

Codice Lingua Nome nativo
ar Arabo العربية da destra a sinistra
hy Armeno Հայերեն
bn Bengalese বাংলা
bg Bulgaro Български
zh-Hans Cinese (semplificato) 简体中文
zh-Hant Cinese (tradizionale) 繁體中文
hr Croato Hrvatski
cs Ceco Čeština
da Danese Dansk
nl Olandese Nederlands
en-GB Inglese (Regno Unito) English (UK)
en-US Inglese (Stati Uniti) English (US)
et Estone Eesti
fil Filippino Filipino
fi Finlandese Suomi
fr Francese Français
fr-CA Francese (Canada) Français (Canada)
de Tedesco Deutsch
el Greco Ελληνικά
he Ebraico עברית da destra a sinistra
hi Hindi हिन्दी
hu Ungherese Magyar
id Indonesiano Bahasa Indonesia
it Italiano Italiano
ja Giapponese 日本語
ko Coreano 한국어
lv Lettone Latviešu
lt Lituano Lietuvių
ms Malese Bahasa Melayu
mr Marathi मराठी
nb Norvegese Norsk bokmål
fa Persiano (farsi) فارسی da destra a sinistra
pl Polacco Polski
pt-BR Portoghese (Brasile) Português (Brasil)
pt-PT Portoghese (Portogallo) Português (Portugal)
ro Rumeno Română
ru Russo Русский
sr-Latn Serbo (alfabeto latino) Srpski
sk Slovacco Slovenčina
sl Sloveno Slovenščina
es-419 Spagnolo (America Latina) Español (Latinoamérica)
es-ES Spagnolo (Spagna) Español (España)
sw Swahili Kiswahili
sv Svedese Svenska
te Telugu తెలుగు
th Thailandese ไทย
tr Turco Türkçe
uk Ucraino Українська
ur Urdu اردو da destra a sinistra
vi Vietnamita Tiếng Việt
Sezione intitolata “Link di firma sempre attivi”

Un link di firma è un URL permanente per contratti che molte persone firmano allo stesso modo: una liberatoria, un contratto di collaborazione, le condizioni di un progetto pilota. Ogni visitatore che lo completa riceve la propria busta.

Finestra del terminale
curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'
  • visitorRole è il ruolo di firmatario che assume il visitatore. I link supportano un visitatore e al massimo un controfirmatario: con mode: "auto" la controfirma avviene automaticamente con il sigillo della piattaforma Bona Fide, con mode: "person" la busta viene instradata all’email indicata. Ogni altro ruolo non CC resterebbe senza destinatario, quindi questi modelli vengono rifiutati.
  • Il visitatore inserisce nome, e-mail e le variabili del modello, poi conferma un codice ricevuto via e-mail prima che venga creato qualsiasi cosa (POST /v1/links/{id}/start, poi POST /v1/links/{id}/verify).
  • limits limita l’uso per e-mail al giorno (predefinito 3), per IP all’ora (predefinito 20), al giorno in totale e per dominio e-mail. Con dedupe (attivo per impostazione predefinita), un indirizzo e-mail che ha già firmato riceve 409 already-signed.
  • PATCH /v1/signing-links/{id} sospende (active: false), riattiva o sposta il link su una versione più recente; l’eliminazione di un link mantiene le buste che ha creato. Ogni utilizzo emette signing_link.used.