> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ricevuta PDF tramite header DOCUMENT

> Invia un modello Utility WhatsApp con un PDF di ricevuta allegato come header documento.

Questa guida mostra il pattern di ricevuta dell'Opzione B: il messaggio WhatsApp include un header documento PDF e variabili nel corpo che descrivono la ricevuta.

Usa questo pattern quando il cliente deve ricevere il documento della ricevuta direttamente in WhatsApp invece di aprire una pagina di ricevuta.

## Prima di iniziare

Ti serve:

* Un canale WhatsApp collegato in Switchbord.
* Un modello Utility approvato con un header `DOCUMENT`, ad esempio `payment_receipt_document`.
* Un URL PDF pubblico HTTPS. Meta deve poter recuperarlo.
* Un id evento a monte stabile per l'idempotenza.

<Warning>
  L'URL del documento deve essere HTTPS e raggiungibile da Meta. Non usare URL solo interni, localhost, URL con scadenza che espirano prima dell'invio, o URL contenenti segreti riutilizzabili.
</Warning>

## Struttura del modello

Un tipico modello di ricevuta documento ha un header documento e un corpo come:

```text theme={null}
Ciao {{1}}, la ricevuta {{2}} è allegata a questo messaggio.
```

L'header documento riceve:

```json theme={null}
{
  "link": "https://cdn.example.com/receipts/R-1001.pdf",
  "filename": "R-1001.pdf"
}
```

## Invio diretto tramite API

```bash theme={null}
curl -X POST https://api.switchbord.ai/api/v1/template-sends \
  -H "Authorization: Bearer $SWITCHBORD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-receipt-pdf-R-1001" \
  -d '{
    "templateName": "payment_receipt_document",
    "templateLocale": "it",
    "recipient": {
      "phoneE164": "+393331234567",
      "externalId": "traveller-123",
      "name": "Giulia Rossi"
    },
    "variables": {
      "header": {
        "document": {
          "link": "https://cdn.example.com/receipts/R-1001.pdf",
          "filename": "R-1001.pdf"
        }
      },
      "body": {
        "1": "Giulia",
        "2": "R-1001"
      }
    },
    "metadata": {
      "source": "booking-system",
      "eventType": "payment.receipt.pdf_ready"
    }
  }'
```

Risposta prevista:

```json theme={null}
{
  "data": {
    "contactId": "contact_123",
    "conversationId": "conversation_123",
    "messageId": "message_123",
    "clientMessageId": "payment-receipt-pdf-R-1001",
    "status": "queued",
    "reused": false,
    "idempotent": true
  }
}
```

## Builder per webhook in entrata

Per mappare un evento di pagamento esterno su questo modello:

1. Apri **Impostazioni → Integrazioni → Webhook e API**.
2. Crea un nuovo webhook in entrata.
3. Seleziona il modello Utility approvato `payment_receipt_document`.
4. Mappa i campi:

| Campo del modello     | Modalità sorgente                | Sorgente di esempio                     |
| --------------------- | -------------------------------- | --------------------------------------- |
| Telefono destinatario | Percorso nel payload             | `customer.phone`                        |
| ID esterno            | Percorso nel payload             | `receipt.id`                            |
| Link al documento PDF | Percorso nel payload             | `receipt.pdf`                           |
| Nome del file PDF     | Letterale o percorso nel payload | `receipt.pdf` oppure `receipt.filename` |
| Corpo `{{1}}`         | Percorso nel payload             | `customer.first_name`                   |
| Corpo `{{2}}`         | Percorso nel payload             | `receipt.number`                        |

1. Incolla un payload di esempio ed esegui l'anteprima dry-run.
2. Crea il webhook. Le nuove configurazioni restano disabilitate e in dry-run di default finché la promozione live non è supportata.

Payload di esempio:

```json theme={null}
{
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia"
  },
  "receipt": {
    "id": "payment-receipt-pdf-R-1001",
    "number": "R-1001",
    "filename": "R-1001.pdf",
    "pdf": "https://cdn.example.com/receipts/R-1001.pdf"
  }
}
```

## Variabili del corpo con nome

Il mapper dei webhook in entrata e il compilatore transazionale interno di Switchbord supportano i parametri del corpo con nome di Meta e li compilano in voci `parameter_name`. La route pubblica `POST /api/v1/template-sends` attualmente accetta solo variabili del corpo posizionali, quindi i chiamanti API diretti dovrebbero usare chiavi numeriche del corpo o un array.

## Validazione

Switchbord valida l'header del documento prima di accodare l'invio:

* `link` deve essere un URL HTTPS valido.
* `filename`, se fornito, deve essere non vuoto.
* Le variabili del corpo richieste devono risolvere a stringhe non vuote.
* Il modello selezionato deve essere Utility approvato.
* La chiave di idempotenza deve essere stabile per i tentativi ripetuti.

## Risoluzione dei problemi

| Sintomo                                      | Verifica                                                                                                 |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `400 invalid_media_link`                     | Il link del documento non è HTTPS valido o non può essere interpretato come URL.                         |
| `400 invalid_document_filename`              | È stato fornito un nome file ma è risolto in una stringa vuota.                                          |
| `400 missing_template_name`                  | La mappatura del webhook non ha risolto un modello, oppure nessun modello è stato selezionato.           |
| `401 invalid_signature`                      | La richiesta webhook non è stata firmata con il segreto webhook one-time.                                |
| La consegna Meta fallisce dopo l'accodamento | Verifica che l'URL del PDF sia ancora raggiungibile da Meta e restituisca il tipo di contenuto corretto. |

## Riferimenti correlati

* [Invii di modelli transazionali](/it/api-reference/transactional-template-sends)
* [Webhook in entrata](/it/api-reference/inbound-webhooks)
* [Regole dei modelli](/it/whatsapp/template-rules)