# API de la BIP: claves, contactos, eventos y disparos

> En Ajustes → Claves de API, crea una clave con los alcances correctos y llama a https://api.bip.marketing con el encabezado x-bip-api-key. POST /api/leads crea o actualiza contactos, POST /api/events registra eventos, /api/campaigns/trigger dispara una campaña por API y /api/campaigns/cancel cancela un envío pendiente.

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

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

Tu sistema ya sabe cuándo alguien se registra, compra o paga. Con la API, la BIP se entera en ese mismo instante: el contacto queda actualizado, la compra entra en su historial y el mensaje correcto le llega a esa persona. Esta guía muestra cómo poner la integración en marcha. La referencia completa de cada endpoint está en [bipmarketing.readme.io](https://bipmarketing.readme.io).

<Checklist items="Acceso de administrador a la cuenta de la BIP, para crear la clave|Un servidor o back end que haga llamadas HTTPS (la clave nunca va al navegador)|Una campaña con Disparo por API, si vas a enviar mensajes|Los campos personalizados y KPIs creados en Ajustes, si vas a enviarlos|Un plan de pago para campañas de WhatsApp (el gratuito envía email)" />

## Lo que vas a lograr

- Contactos creados o actualizados en el momento del registro, sin hojas de cálculo y sin duplicar a nadie.
- Bienvenidas, confirmaciones o recordatorios para una persona, disparados por tu sistema en una sola llamada.
- Compras y otras acciones registradas en el historial del contacto, con valor y detalles, listas para filtrar en **Segmentos** con el criterio **Evento**.
- Recordatorios que se cancelan solos cuando el cliente cumple: pagó el pedido, terminó la compra.
- Etiquetas y KPIs (ingresos, pedidos, puntos) siempre al día para armar segmentos.

## Cómo funciona

<Steps items="Crea una clave de API con los alcances que usa la integración|Tu servidor llama a la BIP con la clave en el encabezado x-bip-api-key|La BIP actualiza el contacto, registra el evento o dispara la campaña" />

Todas las llamadas van a `https://api.bip.marketing`, con cuerpo en JSON. La clave identifica tu cuenta: no necesitas indicar el namespace.

Son cuatro endpoints:

- **`POST /api/leads`** crea o actualiza un contacto.
- **`POST /api/events`** registra un evento (una compra, un registro de prueba) en el historial del contacto.
- **`POST /api/campaigns/trigger`** dispara una campaña de **Disparo por API** para un contacto. Si el contacto todavía no existe, la misma llamada puede crearlo.
- **`POST /api/campaigns/cancel`** cancela un disparo con retraso que todavía no salió.

La BIP reconoce a cada persona por el **email** o por el **teléfono**. Si el contacto ya existe, los datos nuevos entran en el mismo perfil: los emails, teléfonos y etiquetas se suman, y los campos enviados se actualizan.

<Callout type="warning">
La clave da acceso a tu cuenta. Guárdala en el servidor, en una variable de entorno, y nunca la pongas en el código del sitio o de la app. Para saber qué hace el visitante en tu sitio, usa el [script del sitio](/es-es/script-del-sitio).
</Callout>

## Paso a paso

### 1. Crea la clave de API

1. En **Ajustes**, abre la pestaña **Claves de API** y haz clic en **Añadir nueva clave de API**.
2. En **Nombre**, indica quién va a usar la clave. Por ejemplo: _Loja Horizonte — sitio web_.
3. Deja **Activo** encendido. Si quieres que la clave deje de funcionar en una fecha, enciende **Habilitado** en **Caducidad automática**: la BIP sugiere un mes a partir de hoy y tú lo ajustas en el calendario.
4. En **Alcances**, enciende solo lo que usa la integración. La tabla de [Alcances](#alcances) muestra qué habilita cada uno.
5. Haz clic en **Guardar**. Aparece el campo **Clave de API** con el botón de copiar. Copia la clave y guárdala en el servidor.

Solo los administradores crean, editan y eliminan claves. En la lista, cada clave muestra sus alcances y un punto verde (activa) o rojo (inactiva). Puedes volver a copiar la clave desde la lista cuando la necesites.

<Shot src="/img/api/1-es-es.png" alt="Creación de una clave de API con nombre, estado, caducidad y alcances" url="dash.bip.marketing/…/settings?tab=api-keys" />

<Callout type="tip">
Crea una clave por integración: una para el sitio web, otra para el sistema de la tienda. Así puedes desactivar una sin detener las demás.
</Callout>

### 2. Prepara campos y KPIs

La API solo guarda campos personalizados y KPIs que ya existen en la cuenta. Crea antes lo que la integración va a enviar.

1. En **Ajustes** → **General**, ve a **Campos** y haz clic en **Añadir campo** para cada dato extra (por ejemplo, _Plano_, un campo de tipo Cadena para el plan del cliente).
2. En **KPIs**, haz clic en **Añadir KPI** y completa el **ID de KPI** (por ejemplo, `receita`, para los ingresos) y el **Nombre del KPI** (_Receita_). En la API, usas el ID.
3. Haz clic en **Guardar**.

Las etiquetas no necesitan preparación: una etiqueta nueva pasa a existir en la cuenta la primera vez que llega por la API.

<Shot src="/img/api/2-es-es.png" alt="Campos personalizados y KPIs en Ajustes, pestaña General" url="dash.bip.marketing/…/settings" />

### 3. Envía contactos con POST /api/leads

Úsalo cuando alguien se registra, actualiza su perfil o se convierte en cliente. La clave necesita el alcance **Escritura de leads** (`leads:write`).

La BIP busca el contacto por `id`, `email` o `phone`. Si lo encuentra, lo actualiza. Si no lo encuentra, lo crea, y en ese caso `name` es obligatorio.

```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" }
}
```

Qué pasa con cada dato:

- **Nombre**: reemplaza el nombre actual.
- **Email y teléfono**: los valores nuevos se suman al perfil. El teléfono, siempre con `+` y el código de país.
- **Etiquetas**: `tags` suma; `tagsRemove` quita. La API nunca quita una etiqueta que no pediste.
- **Campos**: `key` es el nombre del campo, tal como aparece en Ajustes. Un `value` vacío (`""`, `null` o `[]`) borra el campo del contacto. Un valor con formato incorrecto se ignora solo en ese campo.
- **KPIs**: el valor se **suma** a lo que el contacto ya tiene. Enviar `{"receita": 120}` a quien tiene 349,90 deja 469,90. Para puntuar contactos, crea un KPI como `puntos` y ve sumando por aquí.
- **Metadatos**: cada clave enviada reemplaza a la anterior; las demás quedan como están.
- **Contacto archivado**: vuelve a la lista.

La respuesta trae el `id` del contacto y repite los datos enviados. Guarda el `id` si vas a registrar eventos después.

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

### 4. Registra eventos con POST /api/events

Úsalo para guardar lo que la persona hizo fuera de la BIP: una compra, una prueba iniciada, una nota de satisfacción. La clave necesita el alcance **Escritura de eventos** (`events:write`).

- `type` es libre: `purchase`, `trial_started`, `nps`. Usa siempre el mismo texto, con las mismas mayúsculas y minúsculas: es lo que escribes en **Tipo de evento** en el segmento.
- Indica el contacto por `leadId` (el `id` que devuelve `/api/leads`) o por `tracker` (el identificador del visitante del [script del sitio](/es-es/script-del-sitio)). El contacto tiene que existir.
- `value` es texto: `"349.90"`, `"9"`.
- `metadata` guarda los detalles que quieras (número de pedido, artículos). Cada clave puede convertirse en un filtro de **Metadatos** en el segmento.

El evento aparece en el **Feed** del contacto con el tipo, el valor y los detalles en **Más información**. En **Segmentos**, el criterio **Evento** separa a quienes tienen el evento en los últimos 90 días: **Tipo de evento** `purchase`, con la **Fuente** en **Any**, reúne a quienes compraron en ese período. Para marcar a alguien como cliente de forma permanente, envía también una etiqueta o un KPI por `/api/leads`, como en la receta de compra de [Listo para copiar](#listo-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: TU_CLAVE_DE_API" \
  -d '{"type": "purchase", "leadId": "ID_DEL_CONTACTO", "value": "349.90", "metadata": {"pedido": "LH-10482"}}'
</Copy>

### 5. Crea la campaña de Disparo por API

Para enviarle un mensaje a una persona por la API, usas una campaña con **Disparo por API**. No usa segmento: cada llamada elige el contacto.

1. En **Campañas**, haz clic en **Nueva campaña**.
2. Elige el **Canal** y el contenido: **Email** con una **Plantilla de email** (y, si quieres, hasta 3 **Webhooks**), o **WhatsApp** con una plantilla aprobada.
3. En **Tipo de Programación**, elige **Disparo por API**.
4. En **Modo de Disparo**, elige **Inmediato** (el mensaje sale en cuanto la BIP recibe la llamada) o **Retraso** (la BIP espera los segundos de **Retraso (Segundos)**; una nueva llamada para el mismo contacto reinicia el temporizador).
5. En **Ventana de Reingreso del Lead**, decide si la persona puede volver a recibirla. Por defecto, cada contacto recibe la campaña una vez. Para recordatorios que se repiten, enciende **Permitir Reingreso del Lead** y define el **Período de Espera (Días)**.
6. Abre **Integración vía API**: la BIP muestra los comandos listos, ya con el ID de la campaña. El ID también está al final de la dirección de la página.
7. Haz clic en **Guardar** → **Guardar y Activar** y confirma en **Activar Disparo por API**.

<Shot src="/img/api/5-es-es.png" alt="Campaña con Disparo por API, modo de disparo e integración vía API" url="dash.bip.marketing/…/campaigns/…" />

### 6. Dispara con /api/campaigns/trigger

La clave necesita el alcance **Disparo de Campañas** (`campaigns:trigger`). Envía `campaignId` y `lead`.

`lead` puede ser:

- **Texto**, para un contacto que ya existe: el email, el teléfono con código de país, el ID del contacto o el identificador del visitante.
- **Objeto**, para crear o actualizar el contacto y disparar en la misma llamada. Acepta los mismos datos que `/api/leads` y exige también el alcance **Escritura de leads** (`leads:write`).

```json
{
	"campaignId": "ID_DE_LA_CAMPAÑA",
	"lead": { "name": "Tiago Pereira", "email": "tiago.pereira@exemplo.com", "tags": ["trial"] }
}
```

La respuesta confirma el contacto y el modo: `{"campaignId": "…", "leadId": "…", "mode": "immediate"}` o `"mode": "delay"`. El envío ocurre enseguida, en la cola de la campaña.

Para herramientas que solo llaman a una dirección, el mismo endpoint acepta **GET**, con `campaignId`, `lead` y `api-key` en la URL. En ese caso, identifica el contacto por el email. Para todo lo demás, usa 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: TU_CLAVE_DE_API" \
  -d '{"campaignId": "ID_DE_LA_CAMPAÑA", "lead": "marina.alves@exemplo.com"}'
</Copy>

### 7. Cancela un disparo con /api/campaigns/cancel

En una campaña con **Retraso**, el mensaje queda en espera. Si su motivo desapareció (el cliente pagó, terminó el pedido), cancélalo. La clave necesita el alcance **Disparo de Campañas**.

- Envía el mismo `campaignId` y el contacto en `lead`, como texto.
- La respuesta trae `"cancelled": true` cuando había un envío pendiente y se canceló.
- Trae `"cancelled": false` cuando no había nada que cancelar: el mensaje ya salió, nunca se disparó o la campaña es **Inmediato**. No es un error: puedes llamarlo cuantas veces quieras.
- Un disparo cancelado no cuenta como envío.

<Copy label="curl" code>
curl -X POST https://api.bip.marketing/api/campaigns/cancel \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: TU_CLAVE_DE_API" \
  -d '{"campaignId": "ID_DE_LA_CAMPAÑA", "lead": "marina.alves@exemplo.com"}'
</Copy>

## Referencia

### Base y autenticación

| Elemento        | Valor                                                          |
| --------------- | -------------------------------------------------------------- |
| Dirección base  | `https://api.bip.marketing`                                    |
| Clave           | Encabezado `x-bip-api-key: TU_CLAVE_DE_API`                    |
| Clave en la URL | Parámetro `?api-key=TU_CLAVE_DE_API` (prefiere el encabezado)  |
| Cuerpo          | JSON, con `Content-Type: application/json`                     |

### Endpoints

| Método     | Ruta                     | Alcance                                                  | Para qué                                        |
| ---------- | ------------------------ | -------------------------------------------------------- | ----------------------------------------------- |
| POST       | `/api/leads`             | `leads:write`                                            | Crear o actualizar un contacto                  |
| POST       | `/api/events`            | `events:write`                                           | Registrar un evento en el contacto              |
| GET o POST | `/api/campaigns/trigger` | `campaigns:trigger` (y `leads:write` con `lead` objeto)  | Disparar una campaña por API para un contacto   |
| GET o POST | `/api/campaigns/cancel`  | `campaigns:trigger`                                      | Cancelar un disparo con retraso aún pendiente   |

### Alcances

| En el panel          | Alcance             | Qué habilita                                                      |
| -------------------- | ------------------- | ----------------------------------------------------------------- |
| Escritura de leads   | `leads:write`       | `/api/leads` y el `lead` como objeto en el trigger                |
| Escritura de eventos | `events:write`      | `/api/events`                                                     |
| Disparo de Campañas  | `campaigns:trigger` | `/api/campaigns/trigger` y `/api/campaigns/cancel`                |
| Lectura de leads     | `leads:read`        | Lectura de datos del contacto; los endpoints de esta guía no lo usan |

### Campos de POST /api/leads

| Campo        | Tipo                          | Cómo funciona                                                                                                        |
| ------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `email`      | texto                         | Identifica el contacto o suma un email. Envía `email`, `phone` o `id`.                                               |
| `phone`      | texto                         | Formato internacional, con `+` y el código de país: `+5511912345678`.                                               |
| `id`         | texto                         | ID de un contacto que ya existe.                                                                                     |
| `name`       | texto                         | Obligatorio para un contacto nuevo, con al menos 2 caracteres.                                                       |
| `tags`       | lista de textos               | Suma etiquetas al contacto.                                                                                          |
| `tagsRemove` | lista de textos               | Quita etiquetas. Escríbelas como las guarda la BIP: minúsculas, sin acentos, guion en lugar de espacio (`lembrete-pagamento`). |
| `fields`     | lista de `{ "key", "value" }` | `key` es el nombre del campo personalizado. Un valor vacío borra el campo.                                           |
| `kpis`       | objeto `{ "id": número }`     | Se suma al valor actual. Solo KPIs creados en Ajustes.                                                               |
| `metadata`   | objeto                        | Datos libres; cada clave enviada reemplaza a la anterior.                                                            |
| `note`       | `{ "text", "createdBy" }`     | Agrega una nota al contacto. Envía los dos campos.                                                                   |
| `tracker`    | texto                         | Vincula al visitante del script del sitio con el contacto.                                                           |

Formato de los campos personalizados: Fecha en `aaaa-mm-dd` o `dd/mm/aaaa`; Número con punto decimal; Booleano `true` o `false`; Ubicación con el nombre de la ciudad; Teléfono con `+` y el código de país; Array como lista JSON.

### Campos de POST /api/events

| Campo      | Tipo   | Cómo funciona                                                                        |
| ---------- | ------ | ------------------------------------------------------------------------------------ |
| `type`     | texto  | Obligatorio. Libre: `purchase`, `trial_started`, `nps`. El segmento compara el texto exacto. |
| `leadId`   | texto  | ID del contacto. Envía `leadId` o `tracker`.                                         |
| `tracker`  | texto  | Identificador del visitante, ya vinculado a un contacto.                             |
| `value`    | texto  | Valor del evento, como `"349.90"`. Obligatorio cuando `type` es `click`. En el segmento, acepta los operadores de texto. |
| `metadata` | objeto | Detalles libres, como el número de pedido y los artículos. En el segmento, cada clave es una **Clave** de **Metadatos**. |
| `url`      | texto  | Página vinculada al evento. La BIP la guarda sin `https://` y sin lo que va después de `?`. |

### Cómo lee la BIP el lead en trigger y cancel

| Lo que envías en `lead`                             | La BIP busca por                                     |
| --------------------------------------------------- | ---------------------------------------------------- |
| Texto con `@`                                       | Email                                                |
| Texto que empieza con `+`, o solo dígitos (7 o más) | Teléfono (con código de país: `+5511912345678`)      |
| Otro texto                                          | ID del contacto y, después, identificador del visitante |
| Objeto (solo en el trigger, vía POST)               | Crea o actualiza el contacto y dispara               |

### Códigos de respuesta

| Código | Mensaje                                          | Qué hacer                                                                                                     |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| 200    | —                                                | Todo salió bien.                                                                                              |
| 400    | `Validation Error`                               | Revisa los datos: nombre con 2 caracteres o más en el contacto nuevo, email o teléfono válidos, `type` en el evento. |
| 400    | `leadId or tracker is required`                  | Indica el contacto del evento.                                                                                |
| 400    | `Campaign is not configured for API triggers`    | Usa una campaña con **Disparo por API**.                                                                      |
| 400    | `Campaign is not active`                         | Activa la campaña con **Guardar y Activar**.                                                                  |
| 403    | `API key is not active` / `API key has expired`  | Enciende la clave o ajusta la caducidad en **Claves de API**.                                                 |
| 403    | `API key does not have the required permissions` | Enciende en la clave el alcance que falta.                                                                    |
| 404    | `API key not found`                              | Revisa que la clave se haya copiado completa.                                                                 |
| 404    | `Lead not found`                                 | El contacto no existe: créalo con `/api/leads` o usa `lead` como objeto.                                      |
| 404    | `Campaign not found`                             | Revisa el ID de la campaña.                                                                                   |

### Reglas que siempre se aplican

- Un contacto nuevo necesita un `name` con al menos 2 caracteres y un email o teléfono válido.
- El trigger solo funciona en campañas de **Disparo por API** activadas.
- Por defecto, cada contacto recibe una campaña una vez. Un nuevo intento aparece como **Rechazada** en las estadísticas. Para repetir, enciende **Permitir Reingreso del Lead**.
- En el modo **Retraso**, cada contacto tiene como máximo un envío en espera por campaña. Una nueva llamada reinicia el temporizador.
- En BIP Lite, cada disparo de campaña para un contacto cuenta como un envío del mes. Crear contactos, registrar eventos y cancelar disparos no cuentan.
- Quien se dio de baja (opt-out) no recibe el mensaje, aunque se dispare por la API.

## Listo para copiar

### Se registró en el sitio → bienvenida en una llamada

Nimbus App envía un email de bienvenida en cuanto alguien crea su cuenta. Una campaña de **Disparo por API** en modo **Inmediato**, con el email de bienvenida, y una llamada con `lead` como objeto: la BIP crea el contacto y envía. El campo _Plano_ (Cadena) tiene que existir en Ajustes. La clave necesita **Disparo de Campañas** y **Escritura de leads**.

<Copy label="curl" code>
curl -X POST https://api.bip.marketing/api/campaigns/trigger \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: TU_CLAVE_DE_API" \
  -d '{
    "campaignId": "ID_DE_LA_CAMPAÑA",
    "lead": {
      "name": "Tiago Pereira",
      "email": "tiago.pereira@exemplo.com",
      "tags": ["trial"],
      "fields": [{ "key": "Plano", "value": "Trial" }]
    }
  }'
</Copy>

<Copy label="TypeScript" code>
// En el servidor de Nimbus App, justo después de crear la cuenta del usuario
const API_KEY = process.env.BIP_API_KEY ?? 'TU_CLAVE_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_DE_LA_CAMPAÑA',
      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

Loja Horizonte registra cada pedido pagado. Primero, actualiza el contacto con la etiqueta `cliente` y suma los KPIs `receita` (ingresos) y `pedidos` (crea los dos en Ajustes). Después, registra el evento `purchase` con el valor y el número de pedido. La clave necesita **Escritura de leads** y **Escritura 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: TU_CLAVE_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: TU_CLAVE_DE_API" \
  -d '{"type": "purchase", "leadId": "ID_DEL_CONTACTO", "value": "349.90", "metadata": {"pedido": "LH-10482", "itens": 3}}'
</Copy>

<Copy label="TypeScript" code>
// En el servidor de Loja Horizonte, cuando se confirma el pago del pedido
const API_KEY = process.env.BIP_API_KEY ?? 'TU_CLAVE_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>

Con esto, el segmento de clientes sale de un solo criterio: **KPI** → **Indicador** _Receita_ → **Mayor o igual a** → el valor que quieras. Para quienes compraron en los últimos 90 días, usa el criterio **Evento** con **Tipo de evento** `purchase`; para un pedido específico, suma **Metadatos** → **Clave** `pedido` → **Es igual a** → `LH-10482`.

### Cancelar el recordatorio cuando paga

Loja Horizonte le recuerda el pago a quien generó un código Pix (el pago instantáneo de Brasil) y no pagó. La campaña _Recordatorio de pago_ usa **Disparo por API** con un **Retraso** de `3600` segundos (una hora). El sistema la dispara cuando se genera el Pix y la cancela cuando entra el pago. Si la persona paga antes de una hora, el recordatorio nunca sale y no cuenta como envío. La clave necesita **Disparo de Campañas**.

<Copy label="curl" code>
# Pix generado: programa el recordatorio
curl -X POST https://api.bip.marketing/api/campaigns/trigger \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: TU_CLAVE_DE_API" \
  -d '{"campaignId": "ID_DE_LA_CAMPAÑA", "lead": "marina.alves@exemplo.com"}'
# Pago confirmado: cancela el recordatorio
curl -X POST https://api.bip.marketing/api/campaigns/cancel \
  -H "Content-Type: application/json" \
  -H "x-bip-api-key: TU_CLAVE_DE_API" \
  -d '{"campaignId": "ID_DE_LA_CAMPAÑA", "lead": "marina.alves@exemplo.com"}'
</Copy>

<Copy label="TypeScript" code>
// En el servidor de Loja Horizonte
const API_KEY = process.env.BIP_API_KEY ?? 'TU_CLAVE_DE_API';
const CAMPANHA_LEMBRETE = 'ID_DE_LA_CAMPAÑA';
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 generado: el recordatorio sale dentro de una hora, si nada cambia
export const agendarLembrete = (email: string) =>
  bip('/api/campaigns/trigger', { campaignId: CAMPANHA_LEMBRETE, lead: email });
// Pago confirmado: { cancelled: true } si el recordatorio todavía estaba en espera
export const cancelarLembrete = (email: string) =>
  bip('/api/campaigns/cancel', { campaignId: CAMPANHA_LEMBRETE, lead: email });
</Copy>

Si el comprador puede no ser contacto todavía, cambia el email del trigger por un `lead` objeto con nombre y email (la clave pasa a necesitar también **Escritura de leads**). Para recordarle a la misma persona en pedidos futuros, enciende **Permitir Reingreso del Lead** en la campaña.

## Cómo medir

- **Respuestas de la API**: guarda en tu sistema el código y el cuerpo de cada respuesta. El `leadId`, el `mode` y el `cancelled` te dicen qué hizo la BIP.
- **Contacto**: en **Leads**, abre el contacto. El **Feed** muestra la creación y las actualizaciones hechas por la API, las etiquetas, los KPIs y cada evento con su tipo y valor. La sección **KPIs** muestra el total acumulado.
- **Fuente**: en **Segmentos**, el criterio **Primera / Última fuente** → **Primera fuente (Tipo)** → API cuenta cuántos contactos llegaron por la integración.
- **Eventos**: en **Segmentos**, el criterio **Evento** con el **Tipo de evento** que envías (`purchase`, `nps`) cuenta cuántos contactos registraron ese evento en los últimos 90 días.
- **Campaña**: en **Campañas**, abre **Ver Estadísticas** de la campaña por API. Ves procesados, entregados, aperturas y clics y, en **Interacciones del destinatario**, el estado de cada persona: **Enviado**, **Rechazada** (ya la había recibido), **Baja** o **Error**.

## Preguntas frecuentes

### ¿Llamar a la API cuenta como envío?

No. Crear y actualizar contactos y registrar eventos no consumen envíos. Lo que cuenta es cada disparo de campaña para un contacto. Un disparo con retraso cancelado antes de salir no cuenta.

### ¿Qué pasa si disparo dos veces para la misma persona?

En el modo **Inmediato**, cada llamada es un nuevo disparo, y la **Ventana de Reingreso del Lead** decide si la persona la recibe de nuevo. Por defecto, la recibe una vez. En el modo **Retraso**, la segunda llamada reinicia el temporizador y sale un solo mensaje.

### ¿Puedo llamar a la API directamente desde el navegador o la app?

No. La clave quedaría a la vista de cualquiera. Llama a la API desde tu servidor. En el sitio, el [script del sitio](/es-es/script-del-sitio) registra las visitas, y tu servidor vincula al visitante con el contacto mediante el campo `tracker`.

### ¿Cuál es la diferencia entre la API y los webhooks?

La API lleva datos de tu sistema a la BIP. Los [webhooks](/es-es/webhooks) hacen el camino inverso: llevan los datos del contacto de la BIP a tu sistema en cada envío de campaña.

## Ver también

- [Campañas: únicas, recurrentes y por API](/es-es/campanas)
- [Webhooks: lleva cada envío a tu sistema](/es-es/webhooks)
- [Script del sitio: páginas vistas y clics vinculados al contacto](/es-es/script-del-sitio)
- [Segmentos: los 11 criterios para filtrar contactos](/es-es/segmentos)
- [Conecta la Easy Auth a la BIP y recibe a los visitantes del Wi-Fi](/es-es/wifi-conectar-easy-auth)
- [Referencia completa de la API](https://bipmarketing.readme.io)