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

# Recibo em PDF via cabeçalho DOCUMENT

> Envie um template Utility de WhatsApp com um PDF de recibo anexado como cabeçalho de documento.

Este guia mostra o padrão de recibo Opção B: a mensagem de WhatsApp inclui um cabeçalho de documento PDF e variáveis no corpo descrevendo o recibo.

Use esse padrão quando o cliente deve receber o documento do recibo diretamente no WhatsApp, em vez de abrir uma página de recibo.

## Antes de começar

Você precisa de:

* Um canal de WhatsApp conectado no Switchbord.
* Um template Utility aprovado com um cabeçalho `DOCUMENT`, por exemplo `payment_receipt_document`.
* Uma URL pública de PDF em HTTPS. A Meta precisa conseguir buscá-la.
* Um id de evento de origem estável para idempotência.

<Warning>
  A URL do documento precisa ser HTTPS e acessível pela Meta. Não use URLs somente internas, localhost, URLs com expiração antes do despacho, ou URLs contendo segredos reutilizáveis.
</Warning>

## Estrutura do template

Um template típico de recibo em documento tem um cabeçalho de documento e um corpo como:

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

O cabeçalho do documento recebe:

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

## Envio direto via 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"
    }
  }'
```

Resposta esperada:

```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
  }
}
```

## Construtor de webhook de entrada

Para mapear um evento externo de pagamento para este template:

1. Abra **Settings → Integrations → Webhooks & API**.
2. Crie um novo webhook de entrada.
3. Selecione o template Utility aprovado `payment_receipt_document`.
4. Mapeie os campos:

| Campo do template        | Modo de origem                | Exemplo de origem                   |
| ------------------------ | ----------------------------- | ----------------------------------- |
| Telefone do destinatário | Caminho no payload            | `customer.phone`                    |
| ID externo               | Caminho no payload            | `receipt.id`                        |
| Link do documento PDF    | Caminho no payload            | `receipt.pdf`                       |
| Nome do arquivo PDF      | Literal ou caminho no payload | `receipt.pdf` ou `receipt.filename` |
| Corpo `{{1}}`            | Caminho no payload            | `customer.first_name`               |
| Corpo `{{2}}`            | Caminho no payload            | `receipt.number`                    |

1. Cole um payload de exemplo e execute o preview de dry-run.
2. Crie o webhook. Novas configs permanecem desabilitadas e em dry-run por padrão até que a promoção real seja suportada.

Payload de exemplo:

```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"
  }
}
```

## Variáveis de corpo nomeadas

O mapeador de webhooks de entrada do Switchbord e o compilador transacional interno suportam parâmetros de corpo nomeados da Meta e os compilam em entradas `parameter_name`. A rota pública `POST /api/v1/template-sends` atualmente aceita apenas variáveis de corpo posicionais, então quem chama a API diretamente deve usar chaves numéricas de corpo ou um array.

## Validação

O Switchbord valida o cabeçalho de documento antes de colocar na fila:

* `link` precisa ser uma URL HTTPS válida.
* `filename`, quando fornecido, precisa ser não vazio.
* As variáveis de corpo obrigatórias precisam resolver para strings não vazias.
* O template selecionado precisa ser Utility aprovado.
* A chave de idempotência precisa ser estável para novas tentativas.

## Solução de problemas

| Sintoma                                            | Verificação                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `400 invalid_media_link`                           | O link do documento não é HTTPS válido ou não pode ser interpretado como uma URL.          |
| `400 invalid_document_filename`                    | Um nome de arquivo foi fornecido, mas resultou em uma string vazia.                        |
| `400 missing_template_name`                        | O mapeamento do webhook não resolveu um template, ou nenhum template foi selecionado.      |
| `401 invalid_signature`                            | A requisição de webhook não foi assinada com o segredo de webhook de uso único.            |
| A entrega pela Meta falha depois de entrar na fila | Confirme que a URL do PDF ainda está acessível pela Meta e retorna o content type correto. |

## Referência relacionada

* [Envios transacionais de templates](/pt-BR/api-reference/transactional-template-sends)
* [Webhooks de entrada](/pt-BR/api-reference/inbound-webhooks)
* [Regras de templates](/pt-BR/whatsapp/template-rules)