Recibo em PDF via cabeçalho DOCUMENT

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.

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.

Estrutura do template

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

Ciao {{1}}, la ricevuta {{2}} è allegata a questo messaggio.

O cabeçalho do documento recebe:

{
  "link": "https://cdn.example.com/receipts/R-1001.pdf",
  "filename": "R-1001.pdf"
}

Envio direto via API

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:

{
  "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:

Abra Settings → Integrations → Webhooks & API.
Crie um novo webhook de entrada.
Selecione o template Utility aprovado payment_receipt_document.
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`

Cole um payload de exemplo e execute o preview de dry-run.
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:

{
  "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

Link de recibo de pagamento via botão de URL Lançamento em dry-run de webhook de entrada

Primeiros passos

Funcionalidades

WhatsApp

Guias

Contribuindo

Plataforma

Operações

Segurança e Conformidade

Recibo em PDF via cabeçalho DOCUMENT

Antes de começar

Estrutura do template

Envio direto via API

Construtor de webhook de entrada

Variáveis de corpo nomeadas

Validação

Solução de problemas

Referência relacionada

​Antes de começar

​Estrutura do template

​Envio direto via API

​Construtor de webhook de entrada

​Variáveis de corpo nomeadas

​Validação

​Solução de problemas

​Referência relacionada

Antes de começar

Estrutura do template

Envio direto via API

Construtor de webhook de entrada

Variáveis de corpo nomeadas

Validação

Solução de problemas

Referência relacionada