# Mudanças da API

Acompanhe alterações nos endpoints, nos campos e nas regras de integração.

## A regra de compatibilidade

Prepare sua integração para novos campos e mensagens de erro, preservando o tratamento dos códigos e formatos já documentados.

| Isso pode mudar sem versão nova | Isso só muda em versão nova |
| --- | --- |
| Campo novo numa resposta. | Remoção ou renomeação de um campo existente. |
| Valor novo num campo de texto livre (ex.: um \`reason\` inédito). | Tipo de um campo mudar. |
| A frase de \`message\` num erro. | O \`code\` de um erro mudar de nome. |
| Endpoint novo. | Endpoint existente sumir. |

> Atenção: **Ignore campos desconhecidos** e trate erros pelo `code`. O texto de `message` pode mudar sem alterar a condição do erro.

Mudança que quebra contrato ganha caminho novo (`/public/v2/`) e a v1 continua no ar. As duas quebras marcadas abaixo aconteceram **antes** de existir cliente integrado além do primeiro, que foi avisado direto; daqui em diante a regra vale.

## Histórico

2026

Novo### Teste de todos os eventos pelo painel

6 de novembro de 2026- Em Integrações → Webhook, escolha entre os cinco eventos habilitados na configuração salva, incluindo `contact.marketing_opt_out`. Cada teste usa dados fictícios e `data.test: true`, assinatura normal e identificador próprio.
- Valide a assinatura e responda 2xx sem gravar ou alterar cadastros quando o marcador for o booleano true. Os exemplos Node.js, PHP e o guia para IA seguem essa regra para todos os eventos. Veja [como testar](https://patrociniotech.com/documentacao-api/webhook.md).
- O teste tem uma tentativa, fica na auditoria e não entra na fila de entregas. Nenhum contato é descadastrado pelo teste na Patrocinio; o receptor também precisa respeitar o marcador.

Novo### Conciliação, consentimento em lote e gestão de templates

6 de novembro de 2026- Consulte um envio sem message\_id por `GET /public/v1/messages/status`, usando client\_ref ou Idempotency-Key. Resultado incerto ou não encontrado não autoriza gerar outra operação. O contrato informa retenção e limitações.
- Nova consulta de até 500 contatos por lote e registro explícito de consentimento com data, origem, referência da prova e event\_id idempotente. Registros legados não ganham provas inventadas. A API não remove recusa nem bloqueio existente.
- Campanhas do painel podem ser consultadas por `/public/v1/campaigns` e `/campaigns/{id}/results`. Totais e destinatários paginados distinguem aceite, entrega, leitura, falha e saída de promoções.
- Criação de templates e upload de amostras disponíveis pela API. Novas assinaturas opcionais: `contact.marketing_opt_out`, `template.status` e `template.quality`. O evento message.received também informa a interação e a saída reconhecida de forma estruturada.
- A consulta de números acrescenta os motivos da restrição e indica leitura antiga. As respostas autenticadas incluem headers de cota. Entregas de webhook aceitam filtros por message\_id e evento e informam a retenção aplicada.

Mudou### Resposta do receptor de webhook

6 de novembro de 2026- O detalhe de entrega preserva um trecho legível de respostas gzip e deflate, com limite também após a descompressão e ocultação de credenciais conhecidas. O nome `last_error` permanece por compatibilidade; ele pode conter a resposta mesmo quando o HTTP foi 200.
- Problemas de leitura do conteúdo comprimido não transformam um HTTP aceito em falha de entrega. A correção vale para novas tentativas; não reenvia eventos antigos nem reconstrói respostas já truncadas.

Novo### Números conectados e referência para IA

6 de novembro de 2026- Novo `GET /public/v1/numbers`: números da empresa, qualidade, capacidade do portfólio e última saúde registrada. Paginação por cursor, até 50 itens, horários por leitura e indicação de indisponibilidade parcial.
- O guia [Integrar com IA](https://patrociniotech.com/documentacao-api/ia.md) reúne instrução copiável, Markdown e OpenAPI. O MCP público oferece busca e leitura da documentação, sem acesso a contas ou ferramentas de envio.
- Históricos de novos envios preservam até dez botões. Recuperação de um aceite usa o conteúdo salvo naquela operação, sem substituí-lo por um template editado depois. Códigos de autenticação continuam mascarados.
- Checkpoints antigos sem cópia completa usam apenas os dados comprovados da operação; não recuperamos texto ou botões antigos consultando o catálogo atual.

Mudou### Validação, consentimento e consulta de entrega

6 de novembro de 2026- O envio recusa campos desconhecidos, índices que não sejam inteiros e URLs de mídia inválidas. O erro `invalid_request` pode incluir `error.details.fields`, com o campo, código e orientação, sem repetir valores sensíveis.
- Telefones precisam incluir o código do país. Para cadastros locais, use `/validate` com `country`; o envio não acrescenta DDI automaticamente.
- A consulta da janela acrescenta `marketing_allowed` e `marketing_block_reason`. Ausência de bloqueio não prova consentimento: aceite pendente continua diferente de aceito, e recusa ou bloqueio impedem marketing.
- O limite é de 600 requisições por minuto por chave, somando envios e consultas de todos os workers. Em `api_rate_limited`, respeite `Retry-After`; o JSON também pode informar `error.details.retry_after_seconds`.
- Use `GET /public/v1/messages/{message_id}/status` para consultar um envio já registrado, sem reenviar. O webhook continua sendo o caminho principal para acompanhar entregas.
- Mudanças de status, qualidade, categoria e componentes invalidam o catálogo de templates entre os processos da API. As assinaturas opcionais de templates foram acrescentadas posteriormente nesta mesma data, conforme a entrada acima.

Novo### Qualidade e contrato do catálogo de templates

7 de outubro de 2026- Cada modelo passa a informar `id`, `quality_score`, `rejected_reason` e `message_send_ttl_seconds`, com valores nulos quando a Meta não os fornece. O OpenAPI descreve a resposta completa.
- Use `status=ALL` para acompanhar análise, aprovação e outros estados. Filtro vazio ou desconhecido retorna `400 invalid_template_status`. A consulta não entrega catálogo parcial como se estivesse completo.
- Aprovação e qualidade continuam independentes. O integrador deve conferir `sendable` e `api_supported` antes de preparar um envio.

Mudou### Horários UTC e estado da conta

7 de outubro de 2026- Os campos `data.occurred_at` e `data.window_expires_at` de `message.received` passam a indicar UTC explicitamente com `Z`. O instante representado não muda.
- A chave da API exige conta ativa ou em avaliação. Suspensão, desativação ou remoção da conta também bloqueiam chamadas autenticadas por chave.

Mudou### Validação de templates, autenticação e proteção contra envio duplicado

6 de outubro de 2026- A listagem de templates aceita `phone_number_id` e informa `parameter_format`, `body.variable_names` e `buttons[].needs_otp`. O envio confere as variáveis, o cabeçalho e os botões antes de chamar a Meta.
- Novo `otp_code` com `otp_index` para templates de autenticação. O código é repetido no corpo e no botão nativo; validade e uso único continuam sob responsabilidade do sistema emissor.
- Uma chave de idempotência usada com conteúdo diferente retorna `idempotency_conflict`. Tentativas com resultado incerto não são reenviadas automaticamente após cinco minutos. Registros antigos sem hash retornam `idempotency_legacy_unverified`.
- A consulta da janela sem `phone_number_id` usa o número padrão do envio. A janela permite escolher o formato; não informa gratuidade.
- O painel permite escolher eventos de status e respostas recebidas sem apagar a seleção existente. O reenvio preserva o identificador da entrega; o consumidor deve deduplicá-lo.

Novo### Idempotência reservada antes do envio, e erros de template separados

11 de agosto de 2026- A `Idempotency-Key` passou a ser reservada antes da chamada à Meta, protegendo também as tentativas concorrentes e as falhas de conexão durante o envio.
- Resposta nova: `409 idempotency_in_flight`, quando outra chamada com a mesma chave ainda está em andamento. Espere alguns segundos e repita **com a mesma chave**.
- Uma recusa confirmada permite corrigir o pedido e reutilizar a chave. Falhas de conexão e resultados sem confirmação mantêm a reserva; confira a regra atual em [idempotência](https://patrociniotech.com/documentacao-api/mensagens.md).
- `invalid_template` se dividiu. Agora existem `template_params_mismatch` (as variáveis não batem: cabeçalho com anexo, botão com link variável ou variável com NOME também precisam ser enviados), `template_not_found` e `template_paused`. Cada um pede uma ação diferente, e a mensagem única mandava investigar as três.
- `marketing_experiment`: a Meta separa parte dos destinatários num grupo que não recebe marketing, para medir o efeito. Não é falha do envio e reenviar não muda.

Novo### Janela de 24h, templates, anexo no envio e resposta do contato

2 de agosto de 2026- `GET /public/v1/window/{to}`: diz se dá para mandar texto livre agora. É a consulta que orienta a escolha entre texto livre e template.
- `GET /public/v1/templates`: lista os seus templates já decompostos em cabeçalho, corpo, rodapé e botões, dizendo o que cada um exige no envio.
- `POST /public/v1/messages` ganhou `header_media`, `header_text`, `button_url_param`, `variable_names` e `reply_to_message_id`. Sem eles, template com anexo (bilhete, comprovante) ou com botão dinâmico não tinha como ser enviado pela API.
- Novo evento de webhook `message.received`: o que o contato respondeu, com o texto, a mídia, a citação e o `window_expires_at`, que é até quando você pode responder dentro da janela de atendimento.

Novo### Consulta e reenvio das entregas do webhook

30 de julho de 2026- `GET /public/v1/deliveries`, com filtro por `status` e paginação por cursor (`before_id`).
- `GET /public/v1/deliveries/{id}`, que traz também o corpo do que o seu endpoint respondeu.
- `POST /public/v1/deliveries/{id}/retry` e `POST /public/v1/deliveries/retry-failed`.
- Especificação OpenAPI pública em `/public/v1/openapi.json`, só das rotas públicas.

Quebra### Formato do evento de status alinhado

30 de julho de 2026- `error` virou OBJETO `{code, message, reason}`, no lugar de uma string com um `error_code` solto ao lado. Quem lia a string precisou passar a ler `error.reason`.
- `recipient` passou a se chamar `to`, o mesmo nome do campo no envio.
- `timestamp` passou a se chamar `occurred_at`, para não confundir com o `X-PT-Timestamp` do header, que tem outro significado.
- Entrou `status_rank`, para o seu lado descartar evento fora de ordem sem inventar regra própria.

Quebra### Assinatura com timestamp e header de autenticação

30 de julho de 2026- A assinatura passou a ser o HMAC de `"timestamp" + "." + corpo`, e não mais só do corpo. Assinar só o corpo deixava a requisição válida para sempre, então quem capturasse uma entrega poderia reenviá-la meses depois.
- Um só padrão de assinatura: a versão antiga foi removida em vez de conviver com a nova.
- Passou a ser possível configurar um **header de autenticação próprio** do seu endpoint, para gateways que recusam antes de olhar a assinatura.

Novo### Correlação, idempotência e fila de entrega

30 de julho de 2026- `client_ref` no envio, devolvido em todo evento de status. Acaba com a tabela de-para entre o id do WhatsApp e o seu registro.
- Header `Idempotency-Key`: repetir a mesma chamada devolve a resposta original em vez de enviar de novo.
- Limite por CHAVE (600 por minuto) no lugar do limite por IP, que estrangulava campanha grande e misturava clientes atrás do mesmo IP.
- O webhook ganhou fila com retentativa de cerca de 31 horas. Antes, endpoint fora do ar significava evento perdido.

Novo### Primeira versão da API pública

28 de julho de 2026- `POST /public/v1/messages`: texto na janela de 24h e template fora dela.
- `POST /public/v1/validate`: confere o formato do número antes do envio.
- Webhook de saída com o evento `message.status`, assinado com HMAC-SHA256.
- Chaves de API por conta, com prefixo visível e revogação.

## Como você fica sabendo

### Antes de acontecer

Mudança que exige ação sua é avisada por e-mail para o responsável da conta, com prazo. Nada que quebre integração entra sem aviso.

### Para acompanhar

Consulte este histórico e a [especificação OpenAPI](https://api.patrociniotech.com/public/v1/openapi.json) para acompanhar os contratos. O [catálogo de erros](https://patrociniotech.com/documentacao-api/erros.md) informa as condições conhecidas e a ação recomendada para cada uma.

---

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