API de Dados de Concorrentes: do Painel ao BI e ao Slack

Detecção que fica presa no painel morre. A promoção do concorrente que aparece no canal do time às 9h07, ou num dashboard de pricing do lado da sua margem, decide alguma coisa. É essa a diferença que uma API de dados de concorrentes faz: tirar a inteligência competitiva da aba que ninguém abre no dia corrido e colocá-la no fluxo onde o time já trabalha, o BI, o Slack, o warehouse.

Este guia mostra o que a API pública do Batedor expõe, como funcionam os webhooks de saída e os canais prontos de Slack, Telegram e WhatsApp, e três montagens práticas: dashboard de pricing no Metabase, alerta no canal do time e o cruzamento da promoção do rival com a sua curva de vendas. O público é o dono de loja que tem um analista (interno ou de agência) capaz de fazer uma chamada HTTP. Não precisa de mais do que isso.

Por que dado preso no painel morre

Painel é ótimo pra investigar e péssimo pra interromper. Quando você quer entender o histórico de cupons de um concorrente, a timeline resolve. Mas a decisão de pricing de terça-feira de manhã não acontece dentro de uma ferramenta de monitoramento: acontece numa planilha de margem, num dashboard de BI, numa conversa de Slack ou WhatsApp. Se o dado competitivo não estiver nesses lugares, ele chega atrasado ou não chega.

Há também um problema de composição. O sinal do concorrente sozinho diz pouco: “o rival lançou cupom de 20%” só vira decisão quando encostado no seu número, sua margem naquele SKU, sua venda diária, seu CAC. Esse cruzamento ninguém faz de cabeça; ele mora no BI. Já escrevemos sobre como transformar dados de concorrentes em decisão comercial; a integração é o encanamento que torna essa rotina automática em vez de heroica.

O que a API de dados de concorrentes entrega (e o que não entrega)

A chave é criada em Conta > Integrações, na seção “API keys”. Ela tem o formato bdr_ seguido de um prefixo e um segredo, aparece uma única vez na criação (depois é irrecuperável: perdeu, revoga e cria outra) e vai no header Authorization: Bearer de cada chamada. Dá pra criar uma chave por sistema, com rótulo e validade opcional, e a página mostra quando e de qual IP cada chave foi usada pela última vez. Revogação vale na hora.

Ressalva honesta: a v1 é somente leitura e cobre concorrentes e detecções. Ela não expõe a série histórica completa de métricas de rede social nem endpoints de escrita, e obviamente não tem a sua curva de vendas, essa vem do seu ERP ou da sua plataforma. A API entrega a metade competitiva do cruzamento; a sua metade, quem leva pro BI é você.

Webhooks de saída: o evento vai até você

Consultar a API de hora em hora funciona pra dashboard, mas é lento pra alerta. Pra isso existem os webhooks de saída, cadastrados na mesma página de Integrações: você informa uma URL sua (ou um webhook do Zapier/Make) e escolhe quais eventos quer receber. São seis: campaign.detected (nova detecção classificada), movement.detected (movimento estratégico que a IA considerou relevante ao comparar snapshots do concorrente), crawl.completed, crawl.failed, report.completed e notification.

Cada entrega é um POST em JSON com o evento, os dados, um id de entrega e o número da tentativa. O corpo é assinado com HMAC-SHA256 usando o secret gerado no cadastro, e a assinatura vai no header X-Batedor-Signature: seu endpoint recalcula o HMAC e compara antes de confiar no conteúdo. Se a entrega falhar ou demorar mais de 8 segundos, o Batedor tenta de novo, até 3 tentativas com intervalo crescente, e registra cada tentativa num log que a própria página exibe (último status HTTP e último erro).

Três usos que pagam a configuração

1. Dashboard de pricing no Metabase

Um job agendado (cron de hora em hora resolve) chama /public/v1/campaigns com startDate do dia e grava as detecções numa tabela do seu banco. No Metabase, você plota frequência de campanha e profundidade de desconto por concorrente, semana a semana, do lado da sua margem por categoria. É a materialização dos KPIs de inteligência competitiva num lugar onde o comercial olha todo dia, sem depender de alguém lembrar de abrir o painel.

2. Alerta no canal onde o time já está

Aqui existem dois caminhos, e o mais curto não exige código nenhum. Em Conta > Notificações, o Batedor tem canais prontos: Slack (via Incoming Webhook), Telegram (via bot), WhatsApp, além de e-mail, Discord e webhook genérico, com direito a um resumo automático das últimas 24 horas. A disponibilidade de Slack, Telegram e WhatsApp varia por plano (veja os planos). O segundo caminho é o webhook de saída apontando pro seu backend, que formata a mensagem do seu jeito: só as detecções de cupom acima de X%, só os concorrentes do grupo “diretos”, com o link do post e a sua margem daquele SKU na mesma mensagem.

3. Promoção do rival sobre a sua curva de vendas

Esse é o cruzamento que mais muda decisão. Cada campaign.detected tem timestamp; no BI, marque esses eventos sobre a sua receita diária. Exemplo: loja de suplementos vê o rival soltar cupom de 20% na semana do Dia dos Pais. Sem dado, o reflexo é cobrir o cupom e queimar margem. Com dois ou três ciclos anotados no BI, você responde a pergunta que importa: quando esse concorrente faz promoção, a minha venda cai de verdade? Se não cai, a resposta certa é não reagir, e isso vale dinheiro. Se cai, você reage com número, não com susto.

Como montar em uma tarde

Se você ainda não monitora ninguém, dá pra começar pelo trial de 14 dias, sem cartão: cadastre dois ou três concorrentes, deixe as primeiras detecções chegarem e só então gaste a tarde do analista plugando BI e canal. Encanamento sem água não testa nada.