# Comece pela referência certa

Um índice curto para encontrar o assunto, Markdown para ler e OpenAPI para validar os campos. O mesmo conteúdo serve à equipe e aos assistentes de código.

- [Índice para IA](https://patrociniotech.com/documentacao-api/llms.txt): Links por assunto. Leia somente o que precisa.
- [Contrato OpenAPI](https://patrociniotech.com/documentacao-api/openapi.json): Rotas, autenticação, modelos e respostas da API.
- [Referência completa](https://patrociniotech.com/documentacao-api/llms-full.txt): Todos os guias e exemplos em um arquivo de texto.

## Copiar para a IA da sua equipe

Use a instrução abaixo no assistente que vai trabalhar no seu repositório. Ela não contém credenciais. Informe separadamente as regras do seu negócio e disponibilize segredos pelo ambiente seguro do backend.

Instrução de integração · copiar

```text
Implemente a integração do nosso backend com a API pública da Patrocinio Tech.

Leia primeiro https://patrociniotech.com/documentacao-api/llms.txt e o contrato https://patrociniotech.com/documentacao-api/openapi.json. Consulte os Markdown por assunto; não dependa do HTML. Se sua ferramenta aceitar MCP remoto, a documentação está em https://patrociniotech.com/documentacao-api/mcp (somente leitura, sem chave).

1. Compare a implementação existente com o contrato atual. Não invente rotas, campos, nomes de templates ou códigos de erro.
2. Guarde a chave Bearer somente no backend. Consulte GET /public/v1/numbers, percorra a paginação e escolha explicitamente phone_number_id. Consulte /templates para esse número e confira sendable, api_supported, idioma, variáveis, cabeçalho e botões. Reaproveite as consultas; não as repita antes de cada envio.
3. Telefones de envio devem incluir DDI. Use POST /public/v1/validate com country para cadastros locais; formato válido não prova que o telefone tem WhatsApp. Consulte GET /public/v1/window/{to} com o mesmo phone_number_id escolhido para texto livre. Aceite pendente, recusa e bloqueio são situações diferentes; não transforme importação de lista em consentimento.
4. Persista a operação antes de enviar: Idempotency-Key única por operação, client_ref, número escolhido e payload. Uma nova tentativa da mesma operação usa a mesma chave e o mesmo conteúdo. Se faltar message_id, consulte GET /public/v1/messages/status com Idempotency-Key no header ou client_ref na query. Não confunda unconfirmed/404 com autorização para reenviar; não gere outra chave.
5. Templates de autenticação usam otp_code e botão OTP. Gere, expire e valide o código no sistema emissor; nunca registre o código ou a chave em logs. Documentos e imagens devem cumprir o cabeçalho exigido pelo catálogo.
6. No POST /messages, HTTP 200/status sent significa aceite, não entrega. Persista message_id e acompanhe message.status. Valide X-PT-Signature (sha256=...) com HMAC-SHA256 sobre X-PT-Timestamp + ponto + corpo bruto, confira a tolerância de horário de 300 segundos do exemplo e use comparação em tempo constante. Após validar a assinatura, se data.test === true, responda 2xx sem persistir nem alterar cadastros, para qualquer tipo de evento. Para eventos reais, elimine duplicatas pelo identificador da entrega e trate eventos fora de ordem. Confirme 2xx após persistência durável; processe em fila.
7. Trate success, error.code, error.details, campos inválidos, opt-in, falhas da Meta, 429/Retry-After e tentativas limitadas. A cota de 600 requisições/minuto por chave soma consultas e envios; use os headers X-RateLimit-Remaining/Reset como fotografia, não reserva. Confira health.reasons e health.stale; LIMITED não é sinônimo de limite250. Não some limites de números do mesmo portfólio nem os trate como saldo.
8. Teste isolamento de empresas, duplicidade, timeout, assinatura inválida, entrega fora de ordem e rejeições antes de publicar. Use dados fictícios e apenas um telefone de teste expressamente autorizado. Não dispare campanhas, crie chaves nem altere endpoints reais automaticamente.
9. Consulte consentimento em lote por POST /public/v1/contacts/consent/batch. marketing_allowed indica ausência de bloqueio local, não comprova aceite. accepted com origem inbound registra conversa recebida, não autorização para campanhas; não conte esses contatos como consentimentos comprovados. Registre consentimentos reais por PUT /public/v1/contacts/{to}/consent com event_id, data, origem e referência da prova; não declare aceite de contatos importados sem autorização.
10. Para monitorar promoções e modelos, prepare contact.marketing_opt_out, template.status e template.quality e peça ao administrador para habilitar as assinaturas. POST /public/v1/templates submete modelos à Meta; consulte status=ALL antes de usar. Campanhas do painel são consultadas por GET /public/v1/campaigns e /campaigns/{id}/results, com paginação e totais separados de aceite, entrega, falha e incerteza. counts.read não entra em counts.delivered; use delivered_including_read. opted_out sobrepõe os estados e não deve ser somado ao total de entrega.
11. Em campanhas, dispatch_failed é um contador histórico de ocorrências: pode incluir exclusões e tentativas sem confirmação. Decida pelo status e error_code de cada destinatário. uncertain/send_uncertain nunca autoriza reenvio automático, mesmo sem message_id. Não reenviar sent/delivered/read nem contatos com saída de promoções. Antes de preparar outra campanha, atualize os resultados, revise a causa e revalide consentimento; a exportação é só uma fotografia. Reentregar webhook não reenvia mensagem no WhatsApp. A previsão do painel é para terminar o processamento da fila, não para garantir entrega ao cliente.
12. Campanha paused suspende novas tentativas, mas uma requisição em andamento pode terminar. Webhooks PAUSED/DISABLED/REJECTED do template pausam campanhas no mesmo tenant, WABA, modelo e idioma; qualidade RED apenas avisa. APPROVED nunca retoma sozinho. A retomada pelo painel exige validação atual e inclui somente destinatários ainda sem tentativa; não repete aceitos, falhas tentadas ou uncertain. A API pública de campanhas é somente consulta. Não presuma prazo fixo de liberação da Meta.
13. cancelled encerra a fila por ação do usuário no painel e não permite retomada dessa campanha. Não apaga histórico nem cancela mensagens já aceitas na Meta. Destinatários sem tentativa ficam not_sent; tentativas em andamento sem confirmação ficam uncertain. Uma pausa Meta nunca cancela a campanha automaticamente.
14. pause_reason template_catalog_unavailable ou template_category_unavailable significa que a validação do catálogo/categoria não pôde ser concluída. A fila é preservada, não há confirmação de rejeição ou falha de entrega, e a retomada exige ação no painel após uma consulta bem-sucedida.
15. POST /public/v1/messages aceita delivery_api: cloud (padrão) ou marketing. A URL base e a autenticação da Patrocinio não mudam. marketing é somente para template MARKETING aprovado e conta com ativação concluída na Meta; texto livre, UTILITY e AUTHENTICATION continuam cloud. A rota Meta marketing_messages usa product_policy STRICT, sem fallback silencioso para Cloud API. Não aceite termos nem altere message_activity_sharing automaticamente. Qualidade, limites, bloqueios e opt-out continuam valendo; não prometa mais entrega nem menor preço.
16. Persista delivery_api com a operação. Omitir e informar cloud explicitamente são equivalentes para a Idempotency-Key; mudar cloud/marketing com a mesma chave retorna 409 idempotency_conflict. Não troque rota nem chave para contornar um envio incerto. Leia delivery_api na resposta/status e campaign.delivery_api nos resultados de campanhas. delivery_api_confirmed em status, message.status e destinatários registra apenas a evidência da classificação Meta: marketing_lite confirma marketing, marketing confirma cloud. Histórico sem dado permanece null; seleção ou confirmação da rota não prova entrega. Para comparar rotas, use públicos equivalentes sem sobreposição e o mesmo tempo de observação; read é subconjunto das entregas reais, e delivered_including_read já inclui essas leituras.
17. Trate 422 delivery_api_template_mismatch como incompatibilidade de categoria, marketing_api_not_ready como configuração/permissão pendente e cloud_marketing_disabled como recusa Meta 131063 para marketing pela Cloud API; delivery_api inválido retorna 422 invalid_request. Não repita esses erros em laço nem implemente fallback automático. Na Marketing Messages API, templates novos e modelos sem uso por mais de sete dias precisam de sincronização: leia mensagens.md e a orientação Meta antes do tráfego, sem envio automático de aquecimento nem promessa de entrega.

18. Idempotency-Key é opcional no contrato HTTP e recomendado em todo envio automatizado. client_ref também é opcional: o POST não impõe unicidade nem deduplica por esse campo. Imponha unicidade por empresa no outbox, com uma tarefa por mensagem (ex.: outbox:8421). Bilhete, reembolso e aviso do mesmo pedido são tarefas separadas. Vincule o pedido localmente; cada destinatário de campanha tem sua própria operação.
19. Guarde data.to (destinatário canônico), delivery_api, delivery_api_confirmed e message_id sem apagar o telefone solicitado. O retorno idempotent_replay recupera um aceite antigo; status sent nesse retorno não deve rebaixar o estado atual. Em bilhetes e campanhas, failed substitui sent, nunca delivered/read/played; sent atrasado não desfaz failed. Aplique transições e contadores sob transação, deduplicando eventos por conexão e delivery_id.
20. Se o evento não corresponder à operação, mantenha uma fila de conciliação e alerta, sem marcá-lo processado. Confira empresa, remetente e conflitos entre message_id/client_ref. Não associe pelo telefone. HTTP 200 com unknown_message ainda confirma recepção à Patrocinio: a responsabilidade de reprocessar o evento retido é do receptor.
21. Execute o roteiro https://patrociniotech.com/documentacao-api/validacao.md. Não descarte uma integração existente que já atende os critérios: teste os casos de regressão e implemente somente as lacunas. Falhas de configuração da rota exigem correção, sem fallback; send_uncertain exige conciliação, nunca novo envio automático.

Entregue o que mudou, testes executados, configuração necessária e pendências reais. Diferencie teste local/serviço interno de chamada HTTP autenticada em produção. Se faltar credencial ou definição de negócio, explique sem inventar sucesso.
```

## Conectar a documentação por MCP

Em um cliente compatível com MCP remoto por HTTP, adicione o endereço abaixo. Não exige login nem chave da API: este servidor consulta somente a documentação pública. Envios e consultas da sua conta continuam na API autenticada.

URL · servidor MCP

```text
https://patrociniotech.com/documentacao-api/mcp
```

| Recurso | Como usar |
| --- | --- |
| search\_docs | Busque por assunto ou campo. Retorna até cinco trechos com o endereço da página. |
| read\_doc | Leia o Markdown completo de um assunto pelo nome do arquivo, como webhook.md. |
| get\_openapi | Obtenha o contrato público atual. Falha explicitamente se a origem estiver indisponível. |
| Resources | Índice, páginas em Markdown e especificação OpenAPI também podem ser lidos como recursos MCP. |

O transporte é HTTP sem sessão persistente, com compatibilidade com clientes Streamable HTTP de 2025 e com o protocolo de 2026. O formato de configuração varia por ferramenta. Se o cliente não aceitar MCP remoto, use os links Markdown e OpenAPI: o conteúdo é o mesmo.

> O MCP não envia mensagens, acessa contatos, consulta o banco da sua conta, cria chaves ou altera configurações. Não envie segredos no texto das ferramentas de documentação.

## Ordem de leitura

| Objetivo | Referência |
| --- | --- |
| Preparar acesso e escolher o remetente | [Autenticação](https://patrociniotech.com/documentacao-api/index.md) e [números conectados](https://patrociniotech.com/documentacao-api/numeros.md). |
| Enviar e evitar duplicidade | [Templates](https://patrociniotech.com/documentacao-api/templates.md), [mensagens](https://patrociniotech.com/documentacao-api/mensagens.md) e [erros e limites](https://patrociniotech.com/documentacao-api/erros.md). |
| Escolher Cloud ou Marketing Messages API | [delivery\_api e idempotência](https://patrociniotech.com/documentacao-api/mensagens.md); [comparação de campanhas](https://patrociniotech.com/documentacao-api/campanhas.md) com públicos e períodos equivalentes. |
| Receber e conciliar | [Webhook](https://patrociniotech.com/documentacao-api/webhook.md), [fila de eventos](https://patrociniotech.com/documentacao-api/entregas.md) e consulta de status do envio. |
| Revisar uma integração existente | [Mudanças da API](https://patrociniotech.com/documentacao-api/mudancas.md) e [exemplo completo](https://patrociniotech.com/documentacao-api/exemplo.md). |
| Validar antes de liberar | [Operações, unicidade, status fora de ordem e roteiro de testes Cloud/Marketing.](https://patrociniotech.com/documentacao-api/validacao.md) |

## Antes de liberar envios reais

Use o [roteiro de validação](https://patrociniotech.com/documentacao-api/validacao.md) como critério de entrega. Ele diferencia campos opcionais do contrato, garantias que ficam no seu outbox e evidências de aceite, entrega e processamento do webhook.

Confira o número remetente, os templates disponíveis, a política de consentimento e o tratamento de erros. Teste duplicidade, falha de rede e webhook fora de ordem. Valide a entrega no telefone autorizado: aceite da API não equivale a mensagem recebida.

As páginas e seus arquivos Markdown usam a mesma fonte. O OpenAPI é gerado pelas rotas públicas do backend; não inclui rotas do painel. Nenhuma especificação substitui a consulta autenticada do catálogo de cada empresa.

---

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