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.
Links por assunto. Leia somente o que precisa.
Rotas, autenticação, modelos e respostas da API.
Todos os guias e exemplos em um arquivo de texto.
Copiar para a IA da sua equipe (link para esta seção)
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.
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.Conectar a documentação por MCP (link para esta seção)
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.
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.
Ordem de leitura (link para esta seção)
| Objetivo | Referência |
|---|---|
| Preparar acesso e escolher o remetente | Autenticação e números conectados. |
| Enviar e evitar duplicidade | Templates, mensagens e erros e limites. |
| Receber e conciliar | Webhook, fila de eventos e consulta de status do envio. |
| Revisar uma integração existente | Mudanças da API e exemplo completo. |
Antes de liberar envios reais (link para esta seção)
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.