# Templates

Consulte aprovação, qualidade e campos de envio dos modelos vinculados ao seu número.

### GET /public/v1/templates

cURL · listar templates do número

```bash
curl "https://api.patrociniotech.com/public/v1/templates?phone_number_id=SEU_NUMERO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"
```

cURL · acompanhar todos os status

```bash
curl "https://api.patrociniotech.com/public/v1/templates?phone_number_id=SEU_NUMERO_ID&status=ALL" \
  -H "Authorization: Bearer SUA_CHAVE"
```

| Parâmetro | Uso |
| --- | --- |
| phone\_number\_id | ID do número que fará o envio. Se omitido, a listagem usa a conta WhatsApp principal; informe-o quando houver mais de uma conta vinculada. |
| status | Padrão: APPROVED. Use ALL para incluir modelos em análise, rejeitados e pausados. |

> Antes de usar o modelo, confira `sendable: true` e `api_supported: true`. Aprovação na Meta e suporte desta API são verificações diferentes.

A consulta usa cache de até 90 segundos. Ela não é uma confirmação de entrega: o status pode mudar após a consulta e o envio continua sujeito às regras da Meta. Se a consulta falhar ou não puder trazer todas as páginas dentro do limite, retorna `503 templates_unavailable`; uma falha não vira catálogo vazio.

## Como ler o modelo

JSON · um item de data.templates

```json
{
  "id": "123456789012345",
  "name": "entrega_pedido_documento",
  "language": "pt_BR",
  "category": "UTILITY",
  "status": "APPROVED",
  "sendable": true,
  "api_supported": true,
  "api_unsupported_reason": null,
  "quality_score": { "score": "UNKNOWN", "date": null, "reasons": [] },
  "rejected_reason": null,
  "message_send_ttl_seconds": null,
  "parameter_format": "NAMED",
  "header": {
    "format": "DOCUMENT",
    "needs_media": true,
    "needs_text": false
  },
  "body": {
    "text": "Seu pedido {{pedido}} está disponível. Valor: {{valor}}. Consulte os detalhes.",
    "variables_count": 2,
    "variable_names": ["pedido", "valor"]
  },
  "buttons": [{
    "index": 0,
    "type": "URL",
    "text": "Ver pedido",
    "url": "https://suaempresa.com/pedidos/{{1}}",
    "needs_url_param": true,
    "needs_coupon": false,
    "needs_otp": false
  }]
}
```

A listagem retorna esses itens em `data.templates`. O exemplo mostra os campos usados para preparar o envio; a resposta também inclui rodapé e componentes originais da Meta.

| Campo | Como interpretar |
| --- | --- |
| id | Identificador do modelo na Meta. Nome e idioma também identificam a versão usada no envio. |
| status | Situação informada pela Meta. PENDING está em análise; APPROVED indica aprovação. |
| sendable | true somente quando status é APPROVED. Não garante que esta API suporte todos os componentes nem que o envio será entregue. |
| api\_supported | Indica se esta API sabe preencher o formato. Quando false, api\_unsupported\_reason explica a limitação. |
| quality\_score | Objeto com score, date e reasons informados pela Meta, ou null quando indisponível. Qualidade não é aprovação. |
| rejected\_reason | Motivo de rejeição fornecido pela Meta, ou null. A ausência de motivo não significa aprovação. |
| message\_send\_ttl\_seconds | Prazo de entrega configurado no modelo, em segundos, quando informado pela Meta. Não é a validade de um código na sua aplicação. |

## Preencher as variáveis

| Formato | Como preencher |
| --- | --- |
| NAMED | Associe cada nome de `body.variable_names` ao valor correspondente. O exemplo abaixo usa a ordem retornada. |
| POSITIONAL | Envie `variables` na ordem de `{{1}}`, `{{2}}` e seguintes. Omita `variable_names`. |

JSON · trecho do envio com variáveis nomeadas

```json
{
  "template": "entrega_pedido_documento",
  "language": "pt_BR",
  "variable_names": ["pedido", "valor"],
  "variables": ["8421", "R$ 495,75"]
}
```

Use a quantidade de `body.variables_count`. Uma variável repetida no texto recebe o mesmo valor; não envie um valor extra por repetição.

> O texto fixo pode ter quebras de linha. Uma variável não pode conter quebras, tabulações ou mais de quatro espaços consecutivos. Para uma lista, use `AD: A798R5 • B6: MBSERQ`; o WhatsApp ajusta a quebra visual à largura da tela.

## Campos exigidos pelo modelo

| Quando a resposta informa | Preencha no envio |
| --- | --- |
| header.needs\_media: true | O objeto `header_media`, com tipo compatível com o cabeçalho e link do arquivo. |
| header.needs\_text: true | `header_text` |
| buttons\[\].needs\_url\_param: true | `button_url_param` e `button_url_index`, conforme `buttons[].index`. |
| buttons\[\].needs\_coupon: true | `coupon_code` e `coupon_index`. Este é o botão de cupom, não de autenticação. |
| buttons\[\].needs\_otp: true | `otp_code`; `otp_index` deve ser 0 ou omitido. |
| footer | Não é um parâmetro de envio. footer.text mostra o rodapé aprovado; quando não houver rodapé, footer será null. |

Consulte [todos os campos de POST /messages](https://patrociniotech.com/documentacao-api/mensagens.md) para limites de tamanho e exemplos completos.

## Modelos com PDF e sem PDF

Um cabeçalho `DOCUMENT` exige o documento em cada envio. A amostra cadastrada na aprovação não é enviada automaticamente. Sem PDF, use um modelo aprovado sem esse cabeçalho.

JSON · campos do documento no envio

```json
{
  "header_media": {
    "type": "document",
    "link": "https://arquivos.suaempresa.com/bilhetes/8421.pdf",
    "filename": "Bilhete 8421.pdf"
  }
}
```

Use uma URL HTTPS acessível pela Meta sem sessão de navegador e disponível durante o envio. Veja o [exemplo completo com PDF](https://patrociniotech.com/documentacao-api/mensagens.md).

## Código de verificação e expiração

Para confirmar acesso ou uma ação, como saque, use `AUTHENTICATION` com botão OTP. No painel de Templates, o formato disponível é **Copiar código**.

WhatsApp · prévia ilustrativa

```text
Seu código de verificação é *123456*.
Para sua segurança, não o compartilhe.

Expira em 10 minutos.

[Copiar código]
```

| Controle | O que faz |
| --- | --- |
| Prazo no texto | Informa a validade do código ao destinatário. Não executa a validação da sua operação. |
| Validade no seu servidor | Impede usar o código vencido ou já utilizado. Associe-o à pessoa e à operação e limite as tentativas. |
| Prazo de entrega da Meta | Limita as tentativas de entregar a mensagem. Não apaga ou edita uma mensagem já recebida. |

> Atenção: A Patrocinio Tech transporta o código. Seu sistema é responsável por gerar, expirar e validar o código antes de autorizar o saque ou outra ação. Não dependa da aparência do botão para decidir se o código ainda vale.

Veja [como enviar o código pela API](https://patrociniotech.com/documentacao-api/mensagens.md) e a referência da Meta para [templates com Copiar código](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/copy-code-button-authentication-templates).

### E o preenchimento automático com um toque?

A Meta documenta a desativação do botão após o prazo no formato de [preenchimento automático com um toque](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/autofill-button-authentication-templates/), que exige integração com aplicativo Android. Esse formato é diferente do botão Copiar código criado aqui.

## Aprovação e mudanças de status

| Status da Meta | Próximo passo |
| --- | --- |
| APPROVED | Confira api\_supported e preencha os campos exigidos. |
| PENDING | Aguarde a análise da Meta. |
| REJECTED | Consulte o motivo da rejeição no painel de Templates. |
| PAUSED / DISABLED | Confira a qualidade, o motivo e as opções de reativação na Meta. |
| IN\_APPEAL | Aguarde o resultado da contestação na Meta. |
| PENDING\_DELETION / DELETED / ARCHIVED | Não use o modelo para novos envios. |
| LIMIT\_EXCEEDED | Confira o limite indicado pela Meta antes de tentar novamente. |

A categoria e a aprovação pertencem à Meta e podem mudar. Reconsulte a listagem se um modelo antes disponível passar a falhar.

O filtro `status` aceita esses códigos ou `ALL`, sem distinguir maiúsculas de minúsculas. Um filtro vazio ou desconhecido retorna `400 invalid_template_status`.

## Qualidade do modelo

| quality\_score.score | Significado |
| --- | --- |
| GREEN | Qualidade alta informada pela Meta. |
| YELLOW | Qualidade média; acompanhe o desempenho e o conteúdo. |
| RED | Qualidade baixa; revise conteúdo e público antes de ampliar os envios. |
| UNKNOWN / null | Sem avaliação disponível. Não trate como qualidade alta nem como rejeição. |

`quality_score.date` é o horário Unix, em segundos, informado pela Meta para a avaliação, quando disponível. Não é o horário desta consulta. `reasons` preserva as informações de motivo que a Meta disponibilizar. Códigos futuros devem aparecer como desconhecidos na sua interface, sem interromper a leitura do catálogo.

> Aprovações e avisos de qualidade aparecem em Notificações do painel. O webhook público atual oferece `message.status` e `message.received`; ele não publica mudanças de templates. Para acompanhar modelos na integração, consulte este catálogo com `status=ALL`.

## Formatos disponíveis nesta API

`api_supported: false` vem acompanhado de `api_unsupported_reason`, uma explicação em português. A aprovação da Meta, indicada por `sendable`, não substitui essa verificação.

| Recurso | Suporte |
| --- | --- |
| Texto, imagem, vídeo e documento | Disponíveis conforme o cabeçalho aprovado. |
| Link variável | Um botão de link dinâmico por template. |
| Autenticação | Um botão OTP, na posição 0, sem cabeçalho. |
| Cobrança PIX | Template de detalhes do pedido com um botão ORDER\_DETAILS na posição 0. |
| Carrossel, oferta por tempo limitado, localização, GIF e Flow | Indisponíveis neste envio. A tentativa é recusada com template\_format\_unsupported. |

O campo `components` permite inspecionar os dados originais da Meta; ele não amplia os formatos aceitos. Novidades como Direct Send dependem de suporte específico na API. Acompanhe [as mudanças desta integração](https://patrociniotech.com/documentacao-api/mudancas.md).

---

Fonte: https://patrociniotech.com/documentacao-api/templates
Índice para IA: https://patrociniotech.com/documentacao-api/llms.txt