I modelli consentono di definire un workflow di firma riutilizzabile — documento, stage, destinatari e posizionamento dei campi — e di generare pratiche a partire da esso all'occorrenza. Questa guida illustra l'intera configurazione di un modello e mostra come creare una pratica a partire da esso.
- Un JWT Bearer token valido oppure un Personal Access Token
- L'ID organizzazione (
organizationId) - Un documento pronto per il caricamento
Creare il contenitore del modello. Assegnare un nome per poterlo identificare successivamente. Facoltativamente è possibile impostare anche la scadenza.
POST /api/v1/organizations/{organizationId}/templates{
"name": "Standard Lease Agreement",
"expiration": {
"expiresAt": "2026-04-25T09:16:24.350Z",
"mode": "absolute"
}
}Risposta 201 Created
{
"id": "f7e6d5c4-1234-1234-1234-ba9876543210"
}Salvare l'id restituito: è il templateId da utilizzare in tutte le chiamate successive di questa sezione.
Allegare il PDF che i firmatari riceveranno. Questo endpoint utilizza multipart/form-data, non JSON.
POST /api/v1/organizations/{organizationId}/templates/{templateId}/files
Content-Type: multipart/form-data| Field | Type | Descrizione |
|---|---|---|
file | binary | Il file PDF da allegare |
Risposta 201 Created
{
"id": "9c8b7a69-1234-1234-1234-987654321000"
}Salvare l'id restituito: è il fileId, utilizzato per il posizionamento dei campi Firma.
Uno stage rappresenta un passaggio del workflow. I destinatari appartenenti allo stesso stage firmano in parallelo; gli stage vengono eseguiti in sequenza.
POST /api/v1/organizations/{organizationId}/templates/{templateId}/stages{
"name": "First",
"requiredRecipientCompletions": 1,
"type": "signer"
}Risposta 201 Created
{
"id": "b2a1f0e9-1234-1234-1234-726150403020"
}Salvare l'id restituito: è lo stageId.
Aggiungere un destinatario allo stage. In un modello il destinatario rappresenta tipicamente un ruolo: i dati di contatto effettivi possono essere sovrascritti al momento della creazione di una pratica a partire dal modello.
POST /api/v1/organizations/{organizationId}/templates/{templateId}/stages/{stageId}/recipients{
"givenName": "John",
"surname": "Doe",
"email": "john.doe@sample.com",
"notificationChannels": [
"email"
]
}Risposta 201 Created
{
"id": "1a2b3c4d-1234-1234-1234-ef0123456789"
}Salvare l'id restituito: è il recipientId, utilizzato per il posizionamento del campo Firma.
Definire dove deve comparire la firma e assegnarla al destinatario. Questa chiamata sostituisce completamente tutti i task relativi ai campi del file, pertanto è necessario inviare ogni volta l'elenco completo.
PUT /api/v1/organizations/{organizationId}/templates/{templateId}/files/{fileId}/tasks{
"tasks": [
{
"field": {
"fieldType": "Signature",
"id": "field-001",
"page": 1,
"positionX": 100,
"positionY": 650,
"width": 200,
"height": 60,
"allowedSignatureTypes": [
{ "signatureType": "ClickToSignSignature" },
{ "signatureType": "DrawToSignSignature" }
]
},
"recipientId": "1a2b3c4d-1234-1234-1234-ef0123456789",
"sortOrder": 1
}
]
}positionX/positionYsono le coordinate dell'angolo superiore sinistro del campo sulla pagina.allowedSignatureTypesdetermina quali metodi di firma il destinatario può scegliere. Se si lascia il valorenull, si applicano le impostazioni predefinite dell'organizzazione.sortOrderdefinisce la sequenza con cui i campi vengono presentati al firmatario. Risposta204 No Content
La configurazione del modello è ora completa.
È possibile istanziare una nuova pratica dal modello con una singola chiamata. Il documento, gli stage, i destinatari e il posizionamento dei campi del modello vengono copiati automaticamente nella nuova pratica. Non è richiesto alcun corpo della richiesta.
POST /api/v1/organizations/{organizationId}/templates/{templateId}/create-envelopeRisposta 200 OK
{
"createdEnvelopeId": "a1b2c3d4-1234-1234-1234-ef1234567890"
}Il valore createdEnvelopeId restituito è un normale ID di pratica. Da questo momento è possibile lavorare con la pratica come con qualsiasi altra: facoltativamente si può modificarla prima dell'invio oppure inviarla immediatamente.
Portare la pratica da draft a sent. Questa operazione attiva l'e-mail di invito al destinatario.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/sendNon è richiesto alcun corpo della richiesta. Utilizzare createdEnvelopeId come envelopeId.
Risposta 200 OK
{
"id": "a1b2c3d4-1234-1234-1234-ef1234567890",
}È possibile interrogare periodicamente questo endpoint per monitorare l'avanzamento.
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}Risposta 200 OK
{
"id": "a1b2c3d4-1234-1234-1234-ef1234567890",
"name": "Standard Lease Agreement",
"status": "completed",
"sentAt": "2026-04-20T10:05:00Z"
...
}Quando la pratica è completed, è possibile recuperare il file firmato e l'audit trail.
Elencare gli artifact disponibili:
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts{
"artifacts": [
{
"id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
"name": "LeaseAgreement_signed.pdf",
"type": "CompletedFile"
},
{
"id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
"name": "AuditTrail.pdf",
"type": "AuditTrail"
}
]
}Scaricare un artifact specifico:
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}Restituisce il file come flusso binario (application/pdf).