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

EsfuerzoAPICanalEmail + WhatsAppPlanGratis

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.

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

1. 1Crea una clave de API con los alcances que usa la integración
2. 2Tu servidor llama a la BIP con la clave en el encabezado x-bip-api-key
3. 3La 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.

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

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

Captura de pantalla próximamente

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

dash.bip.marketing/…/settings

Captura de pantalla próximamente

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

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

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"]}'

#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.
• Indica el contacto por leadId (el id que devuelve /api/leads) o por tracker (el identificador del visitante del 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).

El evento aparece en el Feed del contacto con el tipo, el valor y los detalles en Más información. Para segmentar a quienes compraron, envía en el mismo momento una etiqueta o un KPI por /api/leads, como en la receta de compra de Listo para copiar.

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

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

dash.bip.marketing/…/campaigns/…

Captura de pantalla próximamente

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

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

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

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

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

#Referencia

#Base y autenticación

#Endpoints

#Alcances

#Campos de POST /api/leads

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

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

#Códigos de respuesta

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

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" }]
    }
  }'

// 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 }
}

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

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}}'

// 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 }
  });
}

Con esto, el segmento de clientes sale de un solo criterio: KPI → Indicador Receita → Mayor o igual a → el valor que quieras.

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

# 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"}'

// 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 });

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.
• 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 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 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
• Webhooks: lleva cada envío a tu sistema
• Script del sitio: páginas vistas y clics vinculados al contacto
• Segmentos: los 10 criterios para filtrar contactos
• Conecta la Easy Auth a la BIP y recibe a los visitantes del Wi-Fi
• Referencia completa de la API