Avisos de integração

De vez em quando uma mudança nossa exige que você atualize o seu código: um SDK com correção obrigatória, um payload que ganhou um campo, um endpoint que mudou de forma. Quando isso acontece, nós te avisamos — e só quando isso acontece.

Este canal não é changelog. Novidades, melhorias e notas de versão ficam no widget de release notes do painel. Aqui só entra o que quebra a sua integração se você não agir. A restrição é proposital: um canal que só dispara quando é para agir é um canal que você lê. Se virasse "toda release", você aprenderia a ignorar — e aí não atualizaria.

Você só recebe o que te afeta

Um aviso não é enviado para a base inteira. O público é resolvido no momento do disparo, cruzando duas coisas:

1. Qual SDK e qual versão a sua conta roda. Os SDKs oficiais enviam o header X-Bzapper-Client: bzapper-<linguagem>/<versão> em toda requisição.
2. Quais recursos a sua conta de fato usa. Uma correção no envio de documento não incomoda quem só manda texto.

Exemplo real: quando as versões 0.4.0, 0.5.0 e 0.6.0 do SDK Python saíram com o envio de mídia quebrado, o aviso foi só para contas que rodavam uma dessas versões e enviavam mídia. Quem já estava na 0.6.1, ou quem só usava texto e OTP, não recebeu nada.

Integração por HTTP puro

Se você chama a API sem um SDK oficial, não há versão para nós identificarmos — o header não é enviado. Você continua alcançável pelo eixo de recursos usados, e recebe os avisos que dizem respeito a payloads e endpoints.

Por onde o aviso chega

Canal	Quando
Painel	Sempre. Banner no topo, some quando você marca como lido.
E-mail	Sempre, para os admins da conta.
Notificação do navegador	Se você ativou em Configurações → Avisos de integração.
WhatsApp	Só com telefone verificado e opt-in explícito, nas mesmas configurações.
Webhook	Evento advisory.published, se você o assinou.

O WhatsApp exige verificação e opt-in por princípio: mandar mensagem para um número que ninguém confirmou é exatamente o disparo não solicitado que ensinamos você a evitar. Não fazemos com o nosso número o que pedimos que você não faça com o seu.

Ler pela API

from bzapper import Client

bz = Client("bz_live_...")

for a in bz.list_advisories()["advisories"]:
    print(a["title"])
    print("O que fazer:", a["action"])
    bz.mark_advisory_read(a["id"])

Cada aviso traz:

Campo	O que é
id	Identificador estável do aviso.
title	A manchete.
impact	O que quebra, em concreto.
action	O que você tem que fazer. É o campo que importa.
link	Documentação com o detalhe.
published_at	Quando o aviso saiu.

Nos outros SDKs: listAdvisories() / markAdvisoryRead(id) (Node, PHP, Java) e ListAdvisories(ctx) / MarkAdvisoryRead(ctx, id) (Go).

Automatizar a reação

Assine o evento advisory.published (ver Webhooks) para reagir sozinho — abrir um ticket, avisar o time no Slack, disparar um bot de atualização de dependência:

{
  "event_type": "advisory.published",
  "payload": {
    "advisory_id": "sdk-python-media-typeerror",
    "title": "SDK Python: atualize para 0.6.1 — envio de mídia está quebrado",
    "impact": "Toda chamada de envio de mídia falha com TypeError…",
    "action": "Atualize para a 0.6.1 ou mais recente: pip install --upgrade bzapper",
    "link": "https://docs.bzapper.com.br/sdks/python",
    "published_at": "2026-08-31T12:00:00Z"
  }
}

Como manter sua conta identificável

Mantenha o SDK oficial e não altere o header X-Bzapper-Client. É por ele que sabemos que você roda a versão afetada — e, quando você atualiza, é por ele que paramos de te incomodar.