POST /v1/envelopes

{
  "template": "tpl_mutual_nda",
  "variables": {
    "client": { "name": "Acme Robotics" }
  },
  "recipients": [
    { "role": "client", "name": "Jane Doe",
      "email": "jane@acme.dev" }
  ],
  "delivery": "embedded"
}

201 env_8Gm2kQ4rT1 · sent → completed · sealed

Contratti in entrata, firmati in uscita.

Bona Fide è la firma elettronica come API. Trasformi un modello e i Suoi dati in una busta pronta da firmare, faccia firmare le persone nel Suo prodotto o su una pagina ospitata e riceva un PDF sigillato che chiunque può verificare.

Guida rapida Riferimento API

Come si combinano le parti

Modelli

Carichi un PDF (o un file Word) e posizioni i campi, oppure scriva il contratto in modalità Documento. Le variabili sono un JSON Schema, quindi l’API convalida i Suoi dati prima che venga inviato qualsiasi cosa. Una volta pubblicate, le versioni sono immutabili.

Buste

Una sola chiamata POST /v1/envelopes compone un modello con le Sue variabili e avvia l’instradamento ai destinatari in base a ruolo e ordine. Simulazioni, chiavi di idempotenza e deduplicazione tramite externalId sono integrate.

La firma, a modo Suo

Link via e-mail, una pagina ospitata o il web component <bf-signing> (con wrapper React e Vue) all’interno della Sua app, con sessioni di breve durata e monouso create dal Suo backend.

Prove che chiunque può controllare

Ogni documento completato riceve una marca temporale PAdES da un’autorità di marcatura temporale pubblica e la sua impronta entra in un albero di Merkle le cui radici Bona Fide firma con Ed25519. Chiunque può verificare una copia, senza bisogno di un account.

Il ciclo di vita in sintesi

Progetti un modello nella dashboard o tramite l’API, poi pubblichi una versione.
Invii una busta: POST /v1/envelopes con l’id del modello, le Sue variabili e un destinatario per ruolo.
Firma: i destinatari ricevono un link via e-mail, oppure Lei crea una sessione di firma e la integra (delivery: "embedded").
Completamento: quando l’ultimo destinatario firma, riceve un webhook envelope.completed con tutti i valori inseriti.
Sigillo: il PDF sigillato (con il suo certificato di completamento) è pronto quando arriva envelope.sealed.
Verifica: chiunque può trascinare il PDF sulla pagina di verifica o chiamare l’API pubblica di verifica.

Perché l’API è piacevole da usare

Errori su cui si può agire. Ogni errore è problem+json secondo RFC 9457; gli errori di validazione riportano un JSON Pointer per ciascun problema, ad esempio /variables/client/email.
Nuovi tentativi sicuri. Invii una Idempotency-Key con le richieste POST: un nuovo tentativo restituisce di nuovo la prima risposta.
Modalità di prova gratuita e illimitata. Le chiavi bf_test_ creano buste con filigrana che non vengono mai fatturate. Veda Autenticazione.
Webhook che seguono uno standard. Le consegne sono firmate secondo Standard Webhooks, ritentate per tre giorni e possono essere ripetute.
OpenAPI 3.1, generato dal codice. Il riferimento e i file scaricabili openapi.json / openapi.yaml sono generati dagli stessi contratti zod con cui l’API esegue la validazione.

Prossimi passi

Guida rapidaChiave API, busta da un modello, firma e webhook di completamento in dieci minuti.

ConcettiModelli, ruoli, campi, buste, destinatari, sessioni e organizzazioni.

Firma integrataPorti l’esperienza di firma all’interno del Suo prodotto con .

VerificaCome funzionano sigillo e ancoraggio, e come controllare personalmente un documento.

L’API si trova all’indirizzo https://api.bonafidesign.com. Tutti i percorsi in questa documentazione sono relativi a esso.