Vai al contenuto

Creare un modello e inviare una pratica a partire da esso

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.

Prerequisiti

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

Parte 1 — Creare il modello

Passaggio 1 — Creare un modello

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.

Passaggio 2 — Caricare un documento nel modello

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


Passaggio 3 — Aggiungere uno stage di firma al modello

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.


Passaggio 4 — Aggiungere un destinatario allo stage

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.


Passaggio 5 — Posizionare un 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 / 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

La configurazione del modello è ora completa.


Parte 2 — Creare una pratica dal modello

Passaggio 6 — Creare una pratica

È 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-envelope

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


Passaggio 7 — Inviare la pratica

Portare la pratica da draft a sent. Questa operazione attiva l'e-mail di invito al destinatario.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send

Non è richiesto alcun corpo della richiesta. Utilizzare createdEnvelopeId come envelopeId.

Risposta 200 OK

{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890",
}

Passaggio 8 — 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": "Standard Lease Agreement",
  "status": "completed",
  "sentAt": "2026-04-20T10:05:00Z"
  ...
}

Passaggio 9 — Scaricare il documento firmato

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