Vai al contenuto

Workflow con destinatario automatico

Un destinatario automatico consente a NSE di applicare una firma o un sigillo a un documento senza alcuna interazione umana. Anziché inviare un link di firma a una persona, il passaggio di firma viene eseguito automaticamente lato server utilizzando un certificato di sigillo preconfigurato.


Prerequisiti

  • Un certificato di sigillo è configurato in Impostazioni dell'organizzazione → Certificati di sigillo
  • Il valore signatureProfile deve corrispondere esattamente al friendly name del certificato di eSealing configurato
  • Il feature flag "AutomaticRemoteSignature" è abilitato sull'organizzazione
  • Un JWT Bearer token valido oppure un Personal Access Token
  • L'ID organizzazione (organizationId)
  • Un documento pronto per il caricamento

Panoramica delle API

Passaggio 1 — Creare la pratica

POST /api/v1/organizations/{organizationId}/envelopes
Content-Type: application/json
{
  "name": "Automatic Signing Envelope",
  "expiration": {
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "mode": "absolute"
  }
}

Salvare l'id restituito nella risposta come envelopeId.

Passaggio 2 — Caricare il documento

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data
file=@document.pdf

Salvare l'id restituito nella risposta come fileId.

Passaggio 3 — Creare lo stage

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
Content-Type: application/json
{
  "name": "Automatic Seal",
  "requiredRecipientCompletions": 1,
  "type": "automatic"
}

Salvare l'id restituito nella risposta come stageId.

Passaggio 4 — Aggiungere il destinatario automatico

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
Content-Type: application/json
{
    "languageCode": "en",
    "signatureProfile": "<profile-name>",
    "type": "Automatic"
}

Salvare l'id restituito nella risposta come recipientId.

Passaggio 5 — Aggiungere il task di firma

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks
Content-Type: application/json
{
  "tasks": [
    {
      "field": {
        "fieldType": "AutomaticSignature",
        "id": "1234",
        "page": 1,
        "positionX": 50,
        "positionY": 200,
        "width": 200,
        "height": 60
      },
      "recipientId":"7117de33-1234-1234-1234-51809e7a3e20",
      "sortOrder":1
    }
  ]  
}

Passaggio 6 — Inviare la pratica

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

Lo stage viene eseguito immediatamente dopo l'invio. Il sigillo viene applicato automaticamente e la pratica si completa senza alcuna interazione umana.


Download dei documenti firmati

Una volta completata la pratica, è possibile recuperare gli artifact tramite:

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts

Successivamente si può scaricare un artifact specifico (documento firmato o audit trail) utilizzando il relativo artifactId:

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}