Vai al contenuto

Inviare la prima pratica

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.

Prerequisiti

  • Un JWT Bearer token valido oppure un Personal Access Token
  • L'ID organizzazione (organizationId)
  • Un documento pronto per il caricamento

Passaggio 1 — Creare una pratica

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.


Passaggio 2 — Caricare un documento

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
FieldTypeDescrizione
filebinaryIl 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.


Passaggio 3 — Aggiungere uno stage di 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.


Passaggio 4 — Aggiungere un destinatario

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.


Passaggio 5 — Posizionare un 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 / positionY sono le coordinate dell'angolo superiore sinistro del campo sulla pagina.
  • allowedSignatureTypes determina quali metodi di firma il destinatario può scegliere. Se si lascia il valore null, si applicano le impostazioni predefinite dell'organizzazione.
  • sortOrder definisce la sequenza con cui i campi vengono presentati al firmatario. Risposta 204 No Content

Passaggio 6 — Inviare la pratica

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}/send

Non è richiesto alcun corpo della richiesta.

Risposta 204 No Content


Passaggio 7 — Verificare lo stato della pratica

È 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"
  ...
}

Passaggio 8 — Scaricare il documento firmato

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).


Prossimi passi

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