Questa guida illustra l'invio di una richiesta di firma tramite l'API NSE v1. Al termine si sarà creata una pratica, caricato un documento, aggiunto un firmatario, posizionato un campo Firma e inviata la pratica — tutto tramite API.
- Un JWT Bearer token valido oppure un Personal Access Token
- L'ID organizzazione (
organizationId) - Un documento pronto per il caricamento
Il primo passo consiste nel creare una pratica. Si tratta del contenitore dei documenti e dei destinatari. Viene creata in stato draft e resta modificabile fino all'invio.
Nella maggior parte delle integrazioni si assegna almeno un nome e si imposta una scadenza. In questo esempio si utilizza una scadenza relativa — 14 giorni dopo l'invio (espressa in secondi).
POST /api/v1/organizations/{organizationId}/envelopes{
"name": "Lease Agreement",
"expiration": {
"mode": "relative",
"afterSendInSeconds": 1209600
}
}Risposta 201 Created
{
"id": "a1b2c3d4-1234-1234-1234-ef1234567890"
}Salvare l'id restituito: è l'envelopeId da utilizzare in tutte le chiamate successive.
Caricare il PDF che il destinatario dovrà firmare. Questo endpoint utilizza multipart/form-data, non JSON.
Nota: la dimensione massima del file è di 10 MB e una pratica può contenere al massimo 10 documenti.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data| Field | Type | Descrizione |
|---|---|---|
file | binary | Il file PDF da allegare |
Risposta 201 Created
{
"id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}Salvare l'id restituito: è il fileId, utilizzato per il posizionamento del campo Firma.
Uno stage rappresenta un passaggio del workflow di firma. I destinatari appartenenti allo stesso stage firmano in parallelo; gli stage vengono eseguiti in sequenza. Per questo esempio è sufficiente un solo stage con un solo firmatario.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages{
"name": "Signers",
"requiredRecipientCompletions": 1,
"type": "signer"
}Risposta 201 Created
{
"id": "5c367bac-1234-1234-1234-08f3025e28ab"
}Salvare l'id restituito: è lo stageId.
Aggiungere allo stage appena creato la persona che firmerà il documento.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients{
"givenName": "John",
"surname": "Doe",
"email": "john.doe@example.com",
"notificationChannels": [
"email"
]
}Risposta 201 Created
{
"id": "4e861e0f-1234-1234-1234-58bd9928b4a8"
}Salvare l'id restituito: è il recipientId, utilizzato per il posizionamento del campo Firma.
Aggiungere ora tutti i campi che devono comparire sul documento e indicare chi deve firmarlo. Questa chiamata sostituisce completamente tutti i task del file, pertanto è necessario inviare ogni volta l'elenco completo.
Ogni task racchiude una definizione di field insieme al recipientId e a un sortOrder.
PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/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": "4e861e0f-1234-1234-1234-58bd9928b4a8",
"sortOrder": 1
}
]
}Alcuni aspetti da tenere presenti:
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
Una volta completata la configurazione, inviare la pratica. Questa operazione porta la pratica da draft a sent e attiva l'e-mail di invito al destinatario.
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/sendNon è richiesto alcun corpo della richiesta.
Risposta 204 No Content
È 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": "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 elementi disponibili:
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts{
"artifacts": [
{
"id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
"name": "LeaseAgreement.pdf",
"type": "CompletedFile"
},
{
"id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
"name": "Audit Trail.pdf",
"type": "AuditTrail"
}
]
}Scaricare un artifact specifico:
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}Restituisce il file come flusso binario (application/pdf).
Questa guida ha illustrato il flusso essenziale. Il riferimento completo delle API descrive le ulteriori opzioni disponibili in ciascun passaggio, tra cui:
- Pratica: promemoria automatici, date di scadenza assolute
- Stage: firma in parallelo, stage di sola approvazione (
Approver), copia per conoscenza (CarbonCopy) - Destinatari: autenticazione SMS/OTP, codici di accesso, configurazione dei certificati QES
- Campi: campi di testo, caselle di controllo, elenchi a discesa, conferme di lettura e altro ancora