# 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### 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