API da BIP: chaves, contatos, eventos e disparos

EsforçoAPICanalE-mail + WhatsAppPlanoGrátis

Seu sistema já sabe quando alguém se cadastra, compra ou paga. Com a API, a BIP fica sabendo na mesma hora: o contato entra atualizado, a compra vai para o histórico e a mensagem certa sai para aquela pessoa. Este guia mostra o caminho para colocar a integração no ar. A referência completa de cada endpoint está em bipmarketing.readme.io.

#O que você vai conseguir

• Contatos criados ou atualizados no momento do cadastro, sem planilha e sem duplicar ninguém.
• Boas-vindas, confirmação ou lembrete para uma pessoa, disparados pelo seu sistema em uma chamada.
• Compras e outros acontecimentos registrados no histórico do contato, com valor e detalhes.
• Lembretes que se cancelam quando o cliente resolve: pagou o pedido, finalizou a compra.
• Tags e KPIs (receita, pedidos, pontos) sempre em dia para montar segmentos.

#Como funciona

1. 1Crie uma chave de API com os escopos que a integração usa
2. 2Seu servidor chama a BIP com a chave no cabeçalho x-bip-api-key
3. 3A BIP atualiza o contato, registra o evento ou dispara a campanha

Todas as chamadas vão para https://api.bip.marketing, com corpo em JSON. A chave identifica a sua conta: você não precisa informar o namespace.

São quatro endpoints:

• POST /api/leads cria ou atualiza um contato.
• POST /api/events registra um evento (uma compra, um cadastro de teste) no histórico do contato.
• POST /api/campaigns/trigger dispara uma campanha de Disparo por API para um contato. Se o contato ainda não existe, a mesma chamada pode criá-lo.
• POST /api/campaigns/cancel cancela um disparo com atraso que ainda não saiu.

A BIP reconhece cada pessoa pelo e-mail ou pelo telefone. Se o contato já existe, os dados novos entram no mesmo perfil: e-mails, telefones e tags são somados, e os campos enviados são atualizados.

#Passo a passo

#1. Crie a chave de API

1. Em Configurações, abra a aba Chaves de API e clique em Adicionar Nova Chave de API.
2. Em Nome, diga quem vai usar a chave. Por exemplo: Loja Horizonte — site.
3. Deixe Ativo ligado. Se quiser que a chave pare de funcionar numa data, ligue Habilitado em Expiração Automática: a BIP sugere um mês a partir de hoje e você ajusta no calendário.
4. Em Escopos, ligue só o que a integração usa. A tabela em Escopos mostra o que cada um libera.
5. Clique em Salvar. O campo Chave de API aparece com o botão de copiar. Copie a chave e guarde no servidor.

Só administradores criam, editam e excluem chaves. Na lista, cada chave mostra os escopos e um ponto verde (ativa) ou vermelho (inativa). Você pode copiar a chave de novo pela lista quando precisar.

dash.bip.marketing/…/settings?tab=api-keys

Captura de tela em breve

#2. Prepare campos e KPIs

A API só grava campos personalizados e KPIs que já existem na conta. Crie antes o que a integração vai enviar.

1. Em Configurações → Geral, vá até Campos e clique em Adicionar Campo para cada dado extra (por exemplo, Plano, do tipo String).
2. Em KPIs, clique em Adicionar KPI e preencha o ID do KPI (por exemplo, receita) e o Nome do KPI (Receita). Na API, você usa o ID.
3. Clique em Salvar.

Tags não precisam de preparo: uma tag nova passa a existir na conta na primeira vez que chega pela API.

dash.bip.marketing/…/settings

Captura de tela em breve

#3. Envie contatos com POST /api/leads

Use quando alguém se cadastra, atualiza o perfil ou vira cliente. A chave precisa do escopo Escrita de Contatos (leads:write).

A BIP procura o contato pelo id, pelo email ou pelo phone. Se encontra, atualiza. Se não encontra, cria, e aí o name é obrigatório.

{
	"name": "Marina Alves",
	"email": "marina.alves@exemplo.com",
	"phone": "+5511912345678",
	"tags": ["cliente", "loja-centro"],
	"fields": [{ "key": "Plano", "value": "Ouro" }],
	"kpis": { "receita": 349.9 },
	"metadata": { "origem_cadastro": "checkout" }
}

O que acontece com cada dado:

• Nome: substitui o nome atual.
• E-mail e telefone: novos valores são somados ao perfil. Telefone sempre com + e código do país.
• Tags: tags soma; tagsRemove tira. A API nunca remove uma tag que você não pediu.
• Campos: key é o nome do campo, como aparece em Configurações. Um value vazio ("", null ou []) apaga o campo do contato. Um valor fora do formato é ignorado só naquele campo.
• KPIs: o valor é somado ao que o contato já tem. Enviar {"receita": 120} para quem tem 349,90 deixa 469,90. Para pontuar contatos, crie um KPI como pontos e some por aqui.
• Metadados: cada chave enviada substitui a anterior; as outras ficam como estão.
• Contato arquivado volta para a lista.

A resposta traz o id do contato e repete os dados enviados. Guarde o id se for registrar eventos depois.

curl -X POST https://api.bip.marketing/api/leads \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"name": "Marina Alves", "email": "marina.alves@exemplo.com", "phone": "+5511912345678", "tags": ["cliente"]}'

#4. Registre eventos com POST /api/events

Use para guardar o que a pessoa fez fora da BIP: uma compra, um teste iniciado, uma nota de satisfação. A chave precisa do escopo Escrita de Eventos (events:write).

• type é livre: purchase, trial_started, nps.
• Informe o contato por leadId (o id que /api/leads devolve) ou por tracker (o identificador do visitante do script do site). O contato precisa existir.
• value é texto: "349.90", "9".
• metadata guarda os detalhes que você quiser (número do pedido, itens).

O evento aparece no Feed do contato com o tipo, o valor e os detalhes em Mais Informações. Para segmentar quem comprou, envie no mesmo momento uma tag ou um KPI por /api/leads, como na receita de compra em Pronto para copiar.

curl -X POST https://api.bip.marketing/api/events \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"type": "purchase", "leadId": "ID_DO_CONTATO", "value": "349.90", "metadata": {"pedido": "LH-10482"}}'

#5. Crie a campanha de Disparo por API

Para mandar uma mensagem a uma pessoa pela API, você usa uma campanha com Disparo por API. Ela não usa segmento: cada chamada escolhe o contato.

1. Em Campanhas, clique em Nova Campanha.
2. Escolha o Canal e o conteúdo: Email com um Modelo de E-mail (e, se quiser, até 3 Webhooks), ou WhatsApp com um template aprovado.
3. Em Tipo de Agendamento, escolha Disparo por API.
4. Em Modo de Disparo, escolha Imediato (a mensagem sai assim que a BIP recebe a chamada) ou Atraso (a BIP espera os segundos de Atraso (Segundos); uma nova chamada para o mesmo contato reinicia o temporizador).
5. Em Janela de Reentrada do Lead, decida se a pessoa pode receber de novo. Por padrão, cada contato recebe a campanha uma vez. Para lembretes que se repetem, ligue Permitir Reentrada do Lead e defina o Período de Espera (Dias).
6. Abra Integração via API: a BIP mostra os comandos prontos, já com o ID da campanha. O ID também está no fim do endereço da página.
7. Clique em Salvar → Salvar e Ativar e confirme em Ativar Disparo por API.

dash.bip.marketing/…/campaigns/…

Captura de tela em breve

#6. Dispare com /api/campaigns/trigger

A chave precisa do escopo Disparo de Campanhas (campaigns:trigger). Envie campaignId e lead.

lead pode ser:

• Texto, para um contato que já existe: o e-mail, o telefone com código do país, o ID do contato ou o identificador do visitante.
• Objeto, para criar ou atualizar o contato e disparar na mesma chamada. Aceita os mesmos dados de /api/leads e exige também o escopo Escrita de Contatos (leads:write).

{
	"campaignId": "ID_DA_CAMPANHA",
	"lead": { "name": "Tiago Pereira", "email": "tiago.pereira@exemplo.com", "tags": ["trial"] }
}

A resposta confirma o contato e o modo: {"campaignId": "…", "leadId": "…", "mode": "immediate"} ou "mode": "delay". O envio acontece logo depois, na fila da campanha.

Para ferramentas que só chamam um endereço, o mesmo endpoint aceita GET, com campaignId, lead e api-key na URL. Nesse caso, identifique o contato pelo e-mail. Para tudo o mais, use POST.

curl -X POST https://api.bip.marketing/api/campaigns/trigger \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"campaignId": "ID_DA_CAMPANHA", "lead": "marina.alves@exemplo.com"}'

#7. Cancele um disparo com /api/campaigns/cancel

Numa campanha com Atraso, a mensagem fica esperando. Se o motivo dela acabou (o cliente pagou, finalizou o pedido), cancele. A chave precisa do escopo Disparo de Campanhas.

• Envie o mesmo campaignId e o contato em lead, como texto.
• A resposta traz "cancelled": true quando havia um envio pendente e ele foi cancelado.
• Traz "cancelled": false quando não havia nada para cancelar: a mensagem já saiu, nunca foi disparada ou a campanha é Imediato. Não é erro: você pode chamar quantas vezes quiser.
• Um disparo cancelado não conta como envio.

curl -X POST https://api.bip.marketing/api/campaigns/cancel \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"campaignId": "ID_DA_CAMPANHA", "lead": "marina.alves@exemplo.com"}'

#Referência

#Base e autenticação

#Endpoints

#Escopos

#Campos de POST /api/leads

Formato dos campos personalizados: Data em aaaa-mm-dd ou dd/mm/aaaa; Número com ponto decimal; Booleano true ou false; Localização com o nome da cidade; Telefone com + e código do país; Array como lista JSON.

#Campos de POST /api/events

#Como a BIP lê o lead em trigger e cancel

#Códigos de resposta

#Regras que valem sempre

• Contato novo precisa de name com pelo menos 2 caracteres e de e-mail ou telefone válido.
• O trigger só funciona em campanhas de Disparo por API ativadas.
• Por padrão, cada contato recebe uma campanha uma vez. Uma nova tentativa aparece como Rejeitado nas estatísticas. Para repetir, ligue Permitir Reentrada do Lead.
• No modo Atraso, cada contato tem no máximo um envio esperando por campanha. Nova chamada reinicia o temporizador.
• No BIP Lite, cada disparo de campanha para um contato conta como um envio do mês. Criar contatos, registrar eventos e cancelar disparos não contam.
• Quem saiu da lista (opt-out) não recebe a mensagem, mesmo disparada pela API.

#Pronto para copiar

#Cadastrou no site → boas-vindas em uma chamada

O Nimbus App manda um e-mail de boas-vindas assim que alguém cria a conta. Uma campanha de Disparo por API em modo Imediato, com o e-mail de boas-vindas, e uma chamada com lead como objeto: a BIP cria o contato e envia. O campo Plano (String) precisa existir em Configurações. A chave precisa de Disparo de Campanhas e Escrita de Contatos.

curl -X POST https://api.bip.marketing/api/campaigns/trigger \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{
    "campaignId": "ID_DA_CAMPANHA",
    "lead": {
      "name": "Tiago Pereira",
      "email": "tiago.pereira@exemplo.com",
      "tags": ["trial"],
      "fields": [{ "key": "Plano", "value": "Trial" }]
    }
  }'

// No servidor do Nimbus App, logo depois de criar a conta do usuário
const API_KEY = process.env.BIP_API_KEY ?? 'SUA_CHAVE_DE_API';
export async function enviarBoasVindas(usuario: { nome: string; email: string }) {
  const res = await fetch('https://api.bip.marketing/api/campaigns/trigger', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-bip-api-key': API_KEY },
    body: JSON.stringify({
      campaignId: 'ID_DA_CAMPANHA',
      lead: {
        name: usuario.nome,
        email: usuario.email,
        tags: ['trial'],
        fields: [{ key: 'Plano', value: 'Trial' }]
      }
    })
  });
  if (!res.ok) throw new Error(`BIP ${res.status}: ${await res.text()}`);
  return res.json(); // { campaignId, leadId, mode }
}

#Compra → evento purchase

A Loja Horizonte registra cada pedido pago. Primeiro, atualiza o contato com a tag cliente e soma os KPIs receita e pedidos (crie os dois em Configurações). Depois, registra o evento purchase com o valor e o número do pedido. A chave precisa de Escrita de Contatos e Escrita de Eventos.

curl -X POST https://api.bip.marketing/api/leads \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"name": "Marina Alves", "email": "marina.alves@exemplo.com", "tags": ["cliente"], "kpis": {"receita": 349.9, "pedidos": 1}}'
curl -X POST https://api.bip.marketing/api/events \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"type": "purchase", "leadId": "ID_DO_CONTATO", "value": "349.90", "metadata": {"pedido": "LH-10482", "itens": 3}}'

// No servidor da Loja Horizonte, quando o pagamento do pedido é confirmado
const API_KEY = process.env.BIP_API_KEY ?? 'SUA_CHAVE_DE_API';
async function bip(path: string, body: unknown) {
  const res = await fetch(`https://api.bip.marketing${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-bip-api-key': API_KEY },
    body: JSON.stringify(body)
  });
  if (!res.ok) throw new Error(`BIP ${res.status}: ${await res.text()}`);
  return res.json();
}
export async function registrarCompra(pedido: { id: string; total: number; itens: number; nome: string; email: string }) {
  const contato = await bip('/api/leads', {
    name: pedido.nome,
    email: pedido.email,
    tags: ['cliente'],
    kpis: { receita: pedido.total, pedidos: 1 }
  });
  await bip('/api/events', {
    type: 'purchase',
    leadId: contato.id,
    value: pedido.total.toFixed(2),
    metadata: { pedido: pedido.id, itens: pedido.itens }
  });
}

Com isso, o segmento de clientes sai de um critério só: KPI → Indicador Receita → Maior ou igual a → o valor que você quiser.

#Cancelar o lembrete quando pagar

A Loja Horizonte lembra quem gerou um Pix e não pagou. A campanha Lembrete de pagamento usa Disparo por API com Atraso de 3600 segundos (uma hora). O sistema dispara quando o Pix é gerado e cancela quando o pagamento entra. Se a pessoa pagar antes de uma hora, o lembrete nunca sai e não conta como envio. A chave precisa de Disparo de Campanhas.

# Pix gerado: agenda o lembrete
curl -X POST https://api.bip.marketing/api/campaigns/trigger \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"campaignId": "ID_DA_CAMPANHA", "lead": "marina.alves@exemplo.com"}'
# Pagamento confirmado: cancela o lembrete
curl -X POST https://api.bip.marketing/api/campaigns/cancel \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: SUA_CHAVE_DE_API" \
  -d '{"campaignId": "ID_DA_CAMPANHA", "lead": "marina.alves@exemplo.com"}'

// No servidor da Loja Horizonte
const API_KEY = process.env.BIP_API_KEY ?? 'SUA_CHAVE_DE_API';
const CAMPANHA_LEMBRETE = 'ID_DA_CAMPANHA';
async function bip(path: string, body: unknown) {
  const res = await fetch(`https://api.bip.marketing${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-bip-api-key': API_KEY },
    body: JSON.stringify(body)
  });
  if (!res.ok) throw new Error(`BIP ${res.status}: ${await res.text()}`);
  return res.json();
}
// Pix gerado: o lembrete sai daqui a uma hora, se nada mudar
export const agendarLembrete = (email: string) =>
  bip('/api/campaigns/trigger', { campaignId: CAMPANHA_LEMBRETE, lead: email });
// Pagamento confirmado: { cancelled: true } se o lembrete ainda estava esperando
export const cancelarLembrete = (email: string) =>
  bip('/api/campaigns/cancel', { campaignId: CAMPANHA_LEMBRETE, lead: email });

Se o comprador pode ainda não ser contato, troque o e-mail do trigger por um lead objeto com nome e e-mail (a chave passa a precisar também de Escrita de Contatos). Para lembrar a mesma pessoa em pedidos futuros, ligue Permitir Reentrada do Lead na campanha.

#Como medir

• Respostas da API: guarde no seu sistema o código e o corpo de cada resposta. O leadId, o mode e o cancelled contam o que a BIP fez.
• Contato: em Contatos, abra o contato. O Feed mostra a criação e as atualizações feitas pela API, as tags, os KPIs e cada evento com tipo e valor. A seção KPIs mostra o total acumulado.
• Origem: em Segmentos, o critério Primeira / Última Origem → Primeira Origem (Tipo) → API conta quantos contatos chegaram pela integração.
• Campanha: em Campanhas, abra Ver Estatísticas da campanha por API. Você vê processados, entregues, aberturas e cliques e, em Interações do Destinatário, o status de cada pessoa: Enviado, Rejeitado (já tinha recebido), Optou por sair ou Erro.

#Perguntas frequentes

#Chamar a API conta como envio?

Não. Criar e atualizar contatos e registrar eventos não consomem envios. Conta cada disparo de campanha para um contato. Um disparo com atraso cancelado antes de sair não conta.

#O que acontece se eu disparar duas vezes para a mesma pessoa?

No modo Imediato, cada chamada é um novo disparo, e a Janela de Reentrada do Lead decide se a pessoa recebe de novo. Por padrão, recebe uma vez. No modo Atraso, a segunda chamada reinicia o temporizador e sai uma mensagem só.

#Posso chamar a API direto do navegador ou do app?

Não. A chave ficaria visível para qualquer pessoa. Chame a API do seu servidor. No site, o script do site registra as visitas, e o seu servidor liga o visitante ao contato com o campo tracker.

#Qual a diferença entre a API e os webhooks?

A API leva dados do seu sistema para a BIP. Os webhooks fazem o caminho contrário: levam os dados do contato da BIP para o seu sistema a cada envio de campanha.

#Veja também

• Campanhas: única, recorrente e por API
• Webhooks: leve cada envio para o seu sistema
• Script do site: page views e cliques ligados ao contato
• Segmentos: os 10 critérios para filtrar contatos
• Conectar a Easy Auth à BIP e receber os visitantes do Wi-Fi
• Referência completa da API