# API da BIP: chaves, contatos, eventos e disparos

> Em Configurações → Chaves de API, crie uma chave com os escopos certos e chame https://api.bip.marketing com o cabeçalho x-bip-api-key. POST /api/leads cria ou atualiza contatos, POST /api/events registra eventos, /api/campaigns/trigger dispara uma campanha por API e /api/campaigns/cancel cancela um disparo pendente.

Fonte: https://wiki.bip.marketing/pt-br/api · Atualizado: 2026-10-09

<UseCaseMeta effort="api" channel="email,whatsapp" plan="free" />

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](https://bipmarketing.readme.io).

<Checklist items="Acesso de administrador na conta da BIP, para criar a chave|Um servidor ou back-end que faça chamadas HTTPS (a chave nunca vai para o navegador)|Uma campanha com Disparo por API, se for enviar mensagens|Os campos personalizados e KPIs criados em Configurações, se for enviá-los|Plano pago para campanhas de WhatsApp (o gratuito envia e-mail)" />

## 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, prontos para filtrar em **Segmentos** com o critério **Evento**.
- 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

<Steps items="Crie uma chave de API com os escopos que a integração usa|Seu servidor chama a BIP com a chave no cabeçalho x-bip-api-key|A 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.

<Callout type="warning">
A chave dá acesso à sua conta. Guarde-a no servidor, numa variável de ambiente, e nunca a coloque no código do site ou do app. Para saber o que o visitante faz no site, use o [script do site](/pt-br/script-do-site).
</Callout>

## 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](#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.

<Shot src="/img/api/1-pt-br.png" alt="Criação de chave de API com nome, status, expiração e escopos" url="dash.bip.marketing/…/settings?tab=api-keys" />

<Callout type="tip">
Crie uma chave por integração: uma para o site, outra para o sistema da loja. Assim você desliga uma sem parar as outras.
</Callout>

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

<Shot src="/img/api/2-pt-br.png" alt="Campos personalizados e KPIs em Configurações, aba Geral" url="dash.bip.marketing/…/settings" />

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

```json
{
	"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.

<Copy label="curl" code>
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"]}'
</Copy>

### 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`. Use sempre o mesmo texto, com as mesmas maiúsculas e minúsculas: é ele que você escreve em **Tipo de Evento** no segmento.
- Informe o contato por `leadId` (o `id` que `/api/leads` devolve) ou por `tracker` (o identificador do visitante do [script do site](/pt-br/script-do-site)). O contato precisa existir.
- `value` é texto: `"349.90"`, `"9"`.
- `metadata` guarda os detalhes que você quiser (número do pedido, itens). Cada chave pode virar um filtro de **Metadados** no segmento.

O evento aparece no **Feed** do contato com o tipo, o valor e os detalhes em **Mais Informações**. Em **Segmentos**, o critério **Evento** separa quem tem o evento nos últimos 90 dias: **Tipo de Evento** `purchase`, com a **Origem** em **Any**, reúne quem comprou nesse período. Para marcar quem é cliente de vez, envie também uma tag ou um KPI por `/api/leads`, como na receita de compra em [Pronto para copiar](#pronto-para-copiar).

<Copy label="curl" code>
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"}}'
</Copy>

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

<Shot src="/img/api/5-pt-br.png" alt="Campanha com Disparo por API, modo de disparo e integração via API" url="dash.bip.marketing/…/campaigns/…" />

### 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`).

```json
{
	"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.

<Copy label="curl" code>
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"}'
</Copy>

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

<Copy label="curl" code>
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"}'
</Copy>

## Referência

### Base e autenticação

| Item           | Valor                                                       |
| -------------- | ----------------------------------------------------------- |
| Endereço base  | `https://api.bip.marketing`                                 |
| Chave          | Cabeçalho `x-bip-api-key: SUA_CHAVE_DE_API`                 |
| Chave pela URL | Parâmetro `?api-key=SUA_CHAVE_DE_API` (prefira o cabeçalho) |
| Corpo          | JSON, com `Content-Type: application/json`                  |

### Endpoints

| Método      | Caminho                  | Escopo                                                  | Para quê                                      |
| ----------- | ------------------------ | ------------------------------------------------------- | --------------------------------------------- |
| POST        | `/api/leads`             | `leads:write`                                           | Criar ou atualizar um contato                 |
| POST        | `/api/events`            | `events:write`                                          | Registrar um evento no contato                |
| GET ou POST | `/api/campaigns/trigger` | `campaigns:trigger` (e `leads:write` com `lead` objeto) | Disparar uma campanha por API para um contato |
| GET ou POST | `/api/campaigns/cancel`  | `campaigns:trigger`                                     | Cancelar um disparo com atraso ainda pendente |

### Escopos

| No painel            | Escopo              | O que libera                                                  |
| -------------------- | ------------------- | ------------------------------------------------------------- |
| Escrita de Contatos  | `leads:write`       | `/api/leads` e o `lead` como objeto no trigger                |
| Escrita de Eventos   | `events:write`      | `/api/events`                                                 |
| Disparo de Campanhas | `campaigns:trigger` | `/api/campaigns/trigger` e `/api/campaigns/cancel`            |
| Leitura de Contatos  | `leads:read`        | Leitura de dados do contato; os endpoints deste guia não usam |

### Campos de POST /api/leads

| Campo        | Tipo                          | Como funciona                                                                                                   |
| ------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `email`      | texto                         | Identifica o contato ou soma um e-mail. Envie `email`, `phone` ou `id`.                                         |
| `phone`      | texto                         | Formato internacional, com `+` e código do país: `+5511912345678`.                                              |
| `id`         | texto                         | ID de um contato que já existe.                                                                                 |
| `name`       | texto                         | Obrigatório para contato novo, com pelo menos 2 caracteres.                                                     |
| `tags`       | lista de textos               | Soma tags ao contato.                                                                                           |
| `tagsRemove` | lista de textos               | Remove tags. Escreva como a BIP grava: minúsculas, sem acento, hífen no lugar de espaço (`lembrete-pagamento`). |
| `fields`     | lista de `{ "key", "value" }` | `key` é o nome do campo personalizado. Valor vazio apaga o campo.                                               |
| `kpis`       | objeto `{ "id": número }`     | Soma ao valor atual. Só KPIs criados em Configurações.                                                          |
| `metadata`   | objeto                        | Dados livres; cada chave enviada substitui a anterior.                                                          |
| `note`       | `{ "text", "createdBy" }`     | Adiciona uma nota ao contato. Envie os dois campos.                                                             |
| `tracker`    | texto                         | Liga o visitante do script do site ao contato.                                                                  |

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

| Campo      | Tipo   | Como funciona                                                                                                      |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `type`     | texto  | Obrigatório. Livre: `purchase`, `trial_started`, `nps`. O segmento compara o texto exato.                          |
| `leadId`   | texto  | ID do contato. Envie `leadId` ou `tracker`.                                                                        |
| `tracker`  | texto  | Identificador do visitante, já ligado a um contato.                                                                |
| `value`    | texto  | Valor do evento, como `"349.90"`. Obrigatório quando `type` é `click`. No segmento, aceita os operadores de texto. |
| `metadata` | objeto | Detalhes livres, como número do pedido e itens. No segmento, cada chave é uma **Chave** de **Metadados**.          |
| `url`      | texto  | Página ligada ao evento. A BIP guarda sem `https://` e sem o que vem após `?`.                                     |

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

| O que você envia em `lead`                          | A BIP procura por                                   |
| --------------------------------------------------- | --------------------------------------------------- |
| Texto com `@`                                       | E-mail                                              |
| Texto que começa com `+`, ou só dígitos (7 ou mais) | Telefone (com código do país: `+5511912345678`)     |
| Outro texto                                         | ID do contato e, depois, identificador do visitante |
| Objeto (só no trigger, via POST)                    | Cria ou atualiza o contato e dispara                |

### Códigos de resposta

| Código | Mensagem                                         | O que fazer                                                                                             |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| 200    | —                                                | Deu certo.                                                                                              |
| 400    | `Validation Error`                               | Confira os dados: nome com 2+ caracteres no contato novo, e-mail ou telefone válidos, `type` no evento. |
| 400    | `leadId or tracker is required`                  | Informe o contato do evento.                                                                            |
| 400    | `Campaign is not configured for API triggers`    | Use uma campanha com **Disparo por API**.                                                               |
| 400    | `Campaign is not active`                         | Ative a campanha em **Salvar e Ativar**.                                                                |
| 403    | `API key is not active` / `API key has expired`  | Ligue a chave ou ajuste a expiração em **Chaves de API**.                                               |
| 403    | `API key does not have the required permissions` | Ligue o escopo que falta na chave.                                                                      |
| 404    | `API key not found`                              | Confira se a chave foi copiada inteira.                                                                 |
| 404    | `Lead not found`                                 | O contato não existe: crie com `/api/leads` ou use `lead` como objeto.                                  |
| 404    | `Campaign not found`                             | Confira o ID da campanha.                                                                               |

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

<Copy label="curl" code>
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" }]
    }
  }'
</Copy>

<Copy label="TypeScript" code>
// 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 }
}
</Copy>

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

<Copy label="curl" code>
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}}'
</Copy>

<Copy label="TypeScript" code>
// 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 }
  });
}
</Copy>

Com isso, o segmento de clientes sai de um critério só: **KPI** → **Indicador** _Receita_ → **Maior ou igual a** → o valor que você quiser. Para quem comprou nos últimos 90 dias, use o critério **Evento** com **Tipo de Evento** `purchase`; para um pedido específico, some **Metadados** → **Chave** `pedido` → **Igual a** → `LH-10482`.

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

<Copy label="curl" code>
# 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"}'
</Copy>

<Copy label="TypeScript" code>
// 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 });
</Copy>

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.
- **Eventos**: em **Segmentos**, o critério **Evento** com o **Tipo de Evento** que você envia (`purchase`, `nps`) conta quantos contatos registraram esse evento nos últimos 90 dias.
- **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](/pt-br/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](/pt-br/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](/pt-br/campanhas)
- [Webhooks: leve cada envio para o seu sistema](/pt-br/webhooks)
- [Script do site: page views e cliques ligados ao contato](/pt-br/script-do-site)
- [Segmentos: os 11 critérios para filtrar contatos](/pt-br/segmentos)
- [Conectar a Easy Auth à BIP e receber os visitantes do Wi-Fi](/pt-br/wifi-conectar-easy-auth)
- [Referência completa da API](https://bipmarketing.readme.io)