# Inviare una pratica massiva

Questa guida illustra come inviare lo stesso documento a un ampio gruppo di destinatari utilizzando l'API Bulk Envelope di NSE. Al termine si sarà creata una pratica massiva, caricato un documento, definita una fase di firma massiva per i destinatari dell'invio massivo, aggiunta una seconda fase per un destinatario standard (non massivo), posizionati i campi firma per entrambi e inviata la pratica massiva.

Una pratica massiva è utile quando lo stesso documento (per esempio un contratto di una campagna o l'accettazione di una policy) deve essere inviato individualmente a molti destinatari, mantenendo eventualmente il passaggio attraverso uno o più approvatori o firmatari fissi e non massivi.

## Prerequisiti

- Un **token JWT Bearer** oppure un **Personal Access Token** valido
- Il proprio **ID organizzazione** (`organizationId`)
- Un documento pronto per il caricamento


## Passaggio 1 — Creare una pratica massiva

Iniziare creando la pratica massiva. Come per una pratica normale, viene creata nello stato `draft` e resta modificabile fino al momento dell'invio.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes
```

```json
{
  "name": "Bulk contract for Q1 campaign",
  "expiration": {
    "mode": "Absolute",
    "expiresAt": "2026-08-15T06:20:36.459164+00:00"
  }
}
```

**Risposta `201 Created`**

```json
{
  "id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}
```

Salvare l'`id` restituito: è il `bulkEnvelopeId` da utilizzare in tutte le chiamate successive.

## Passaggio 2 — Caricare un documento

Caricare il PDF che verrà inviato a ogni destinatario. Questo endpoint utilizza `multipart/form-data`, non JSON.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files
Content-Type: multipart/form-data
```

| Campo | Tipo | Descrizione |
|  --- | --- | --- |
| `file` | binary | Il file PDF da allegare |


**Risposta `201 Created`**

```json
{
  "id": "c4f81b3d-1234-1234-1234-2d9f4c1b6a05"
}
```

Salvare l'`id` restituito: è il `fileId`, utilizzato durante il posizionamento dei campi firma.

## Passaggio 3 — Aggiungere la fase di firma massiva

Creare la fase che conterrà i destinatari dell'invio massivo. Impostando `mode` su `Bulk` si indica al sistema che ogni destinatario aggiunto a questa fase riceverà una propria copia della pratica, da firmare in modo indipendente.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages
```

```json
{
  "name": "Bulk Stage",
  "requiredRecipientCompletions": 1,
  "type": "Signer",
  "mode": "Bulk"
}
```

**Risposta `201 Created`**

```json
{
  "id": "9f534128-1234-1234-1234-ddd212a60d68"
}
```

Salvare l'`id` restituito: è il `bulkStageId`.

## Passaggio 4 — Aggiungere i destinatari per invio massivo

Aggiungere i destinatari che riceveranno ciascuno una copia individuale della pratica. Ripetere questa chiamata una volta per ogni destinatario.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{bulkStageId}/recipients
```

**Destinatario 1**

```json
{
  "languageCode": "en",
  "givenName": "John",
  "surname": "Doe",
  "email": "john.doe@example.com"
}
```

**Risposta `201 Created`**

```json
{
  "id": "01750358-1234-1234-1234-b8ccbd123e79"
}
```

**Destinatario 2**

```json
{
  "languageCode": "en",
  "givenName": "Jane",
  "surname": "Doe",
  "email": "jane.doe@example.com"
}
```

**Risposta `201 Created`**

```json
{
  "id": "2b8a6e71-1234-1234-1234-7f3c5d8a2b64"
}
```

## Passaggio 5 — Aggiungere la fase standard (opzionale)

Oltre alla fase massiva, è possibile aggiungere una seconda fase per un destinatario standard (non massivo), per esempio un approvatore interno che deve firmare ogni singola pratica generata a partire dai destinatari dell'invio massivo. Poiché questa fase non è contrassegnata come massiva, lo stesso destinatario viene riportato in ciascuna delle singole pratiche create per i destinatari della fase massiva ed è tenuto a firmare in ognuna di esse.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages
```

```json
{
  "name": "Standard Stage",
  "requiredRecipientCompletions": 1,
  "type": "Signer",
  "mode": "Standard"
}
```

**Risposta `201 Created`**

```json
{
  "id": "6d3e9a17-1234-1234-1234-8e1b4f7c2a93"
}
```

Salvare l'`id` restituito: è il `standardStageId`.

Aggiungere ora l'unico destinatario di questa fase:

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{standardStageId}/recipients
```

```json
{
  "languageCode": "en",
  "givenName": "Joe",
  "surname": "Public",
  "email": "joe.public@example.com"
}
```

**Risposta `201 Created`**

```json
{
  "id": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28"
}
```

Salvare l'`id` restituito: è il `standardRecipientId`.

## Passaggio 6 — Posizionare i campi firma (opzionale)

Aggiungere i campi che devono comparire sul documento per ciascuna fase. Questa chiamata sostituisce integralmente tutte le attività del file, pertanto è necessario inviare ogni volta l'elenco completo.

Un campo può essere associato a un'intera fase (`stageId`) oppure a un destinatario specifico (`recipientId`):

- Utilizzare `stageId` per la **fase massiva**: lo stesso campo viene applicato a ogni destinatario aggiunto a quella fase, ciascuno sulla propria copia del documento.
- Utilizzare `recipientId` per la **fase standard**: il campo è associato a quel singolo destinatario, che lo firma su ogni pratica individuale generata dalla fase massiva.


```http
PUT /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files/{fileId}/tasks
```

```json
{
  "tasks": [
    {
      "field": {
        "fieldType": "Signature",
        "id": "signature1",
        "page": 1,
        "positionX": 100,
        "positionY": 200,
        "width": 200,
        "height": 50,
        "required": true,
        "allowedSignatureTypes": [
          { "signatureType": "ClickToSignSignature" }
        ]
      },
      "stageId": "9f534128-1234-1234-1234-ddd212a60d68",
      "sortOrder": 1
    },
    {
      "field": {
        "fieldType": "Signature",
        "id": "signature2",
        "page": 1,
        "positionX": 100,
        "positionY": 300,
        "width": 200,
        "height": 50,
        "required": true,
        "allowedSignatureTypes": [
          { "signatureType": "ClickToSignSignature" }
        ]
      },
      "recipientId": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28",
      "sortOrder": 1
    }
  ]
}
```

Alcuni aspetti da tenere presenti:

- `stageId` su un'attività appartenente a una fase **massiva** significa che il campo viene generato su ogni copia individuale creata per i destinatari di quella fase: non è necessario ripetere l'attività per ciascun destinatario dell'invio massivo.
- `recipientId` su un'attività vincola il campo a un destinatario specifico e viene tipicamente utilizzato per le fasi standard, non massive.
- `positionX` / `positionY` sono le coordinate dell'angolo superiore sinistro del campo sulla pagina.
- `allowedSignatureTypes` determina quali metodi di firma il destinatario può scegliere. Se lasciato a `null`, vengono applicati i valori predefiniti dell'organizzazione.
- `sortOrder` stabilisce la sequenza con cui i campi vengono presentati al firmatario.


**Risposta `204 No Content`**

## Passaggio 7 — Inviare la pratica massiva

Una volta completata la configurazione, inviare la pratica massiva. Questa operazione genera una pratica individuale per ogni destinatario dell'invio massivo, porta ciascuna di esse da `draft` a `sent` e attiva l'invio delle e-mail di invito.

```http
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/send
```

Non è richiesto alcun corpo della richiesta.

**Risposta `200 OK`**

```json
{
  "id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}
```