Referencia de la API

Autenticación

Todas las peticiones usan una API key por organización en el encabezado Authorization. Las llaves son de servidor: nunca las expongas en el navegador ni en una app móvil.

GET /v1/leads
Authorization: Bearer kelpi_sk_live_a7f3…

La llave queda ligada a una sola organización, así que todos los recursos que devuelve la API ya vienen acotados a tus datos — no hay que pasar un organizationId en ninguna llamada. Cada llave se puede revocar de forma independiente desde el panel, y registra su último uso.

Convenciones

Envolvente de respuesta

Toda respuesta exitosa devuelve la carga bajo data. Las colecciones agregan meta con el total para paginar.

{
  "data": [ … ],
  "meta": { "total": 1284, "limit": 20, "offset": 0 }
}

Paginación

Por limit (máx. 100, default 20) y offset. Para exportaciones completas, ordena por createdAt asc y recorre con offset hasta agotar meta.total.

Fechas

Todas las marcas de tiempo son ISO 8601 en UTC (2026-08-12T23:01:19.000Z). Los filtros de rango aceptan tanto YYYY-MM-DD como ISO completo.

Límite de tasa

100 peticiones por minuto por llave. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al excederlo se devuelve 429 con código rate_limited.

Trazabilidad de campaña en WhatsApp

Campaña en Google o Meta → landing → el usuario toca “WhatsApp” → la conversación arranca sin referrer y la campaña se pierde.

WhatsApp no propaga document.referrer ni los parámetros de la URL cuando se abre desde un wa.me. Kelpi lo resuelve trasladando la atribución al único canal que sí sobrevive el salto: el texto del primer mensaje.

1. 1El píxel de Kelpi vive en la landing y captura la sesión de clic: utm_*, gclid, fbclid, referrer, URL de aterrizaje y user agent.
2. 2Al tocar el botón de WhatsApp, el píxel acuña un token de referencia corto y lo anexa al mensaje prellenado: Hola, quiero informes · #K7F2M9.
3. 3El mensaje llega a Kelpi. El pipeline de entrada extrae y descarta el token antes de que el agente lo lea — el prospecto nunca ve una conversación contaminada.
4. 4El token se resuelve contra la sesión de clic y la atribución completa se estampa en el lead, en el objeto attribution.
5. 5A partir de ahí, toda conversación, cita, handoff y conversión de ese lead hereda la campaña. Es lo que alimenta /v1/analytics/campaigns.

La ventana de atribución es configurable por organización — 30 días por defecto — y el modelo puede fijarse en last touch o first touch.

Anuncios de clic a WhatsApp de Meta

Cuando el tráfico viene de un anuncio Click-to-WhatsApp, no hace falta el token: Meta entrega el ctwa_clid en el webhook de la conversación y Kelpi lo resuelve directamente contra la campaña y el anuncio. Ambas rutas aterrizan en el mismo objeto attribution.

Píxel y conversiones de servidor

Instalación

Una etiqueta en todas las páginas del sitio. No requiere cookies de terceros.

<script src="{host}/api/embed/klpi.js"
        data-token="pk_live_9c21…" async></script>

El valor de {host} se entrega junto con las credenciales.

Botón de WhatsApp con atribución

Reemplaza el href de wa.me por esta llamada. Devuelve la URL ya firmada con el token de referencia.

// Enlaza el CTA con la sesión de clic actual
klpi('whatsapp', {
  phone:   '5218112345678',
  message: 'Hola, quiero informes de Torres Valle Oriente'
});

Eventos de embudo

El píxel acepta eventos de bajo riesgo desde el navegador. Los eventos sensibles — checkout_started, payment_method_added, purchase_succeeded — deben enviarse servidor a servidor y firmados, para que el monto no sea manipulable desde el cliente.

Leads

El recurso central: los prospectos con su origen de campaña ya resuelto.

{
  "data": [
    {
      "id": "9f2c1a7e-4b13-4d92-8a0f-1c73e5b8d204",
      "name": "Ana Ramírez",
      "phone": "+528112345678",
      "email": "ana.ramirez@example.mx",
      "temperature": "hot",
      "goalStatus": "in_progress",
      "sourceType": "channel",
      "contactAttempts": 2,
      "lastContactedAt": "2026-08-12T18:44:07.000Z",
      "isOptedOut": false,
      "attribution": {
        "utmSource":   "google",
        "utmMedium":   "cpc",
        "utmCampaign": "torres-valle-oriente-q3",
        "utmContent":  "carrusel-3rec",
        "utmTerm":     "departamentos san pedro",
        "gclid":       "Cj0KCQjw8vqrBhD…",
        "fbclid":      null,
        "ctwaClid":    null,
        "campaignId":  "20841773994",
        "adId":        "697412330051",
        "landingUrl":  "https://tu-sitio.com/preventa?utm_source=google&…",
        "referrer":    "https://www.google.com/",
        "resolvedVia": "whatsapp_ref_token",
        "firstTouchAt": "2026-08-11T16:02:55.000Z",
        "lastTouchAt":  "2026-08-12T18:44:07.000Z"
      },
      "createdAt": "2026-08-11T16:03:12.000Z",
      "updatedAt": "2026-08-12T18:44:07.000Z"
    }
  ],
  "meta": { "total": 1284, "limit": 20, "offset": 0 }
}

Timeline de interacciones

{
  "data": [
    { "touchType": "link_clicked",          "occurredAt": "2026-08-11T16:02:55.000Z",
      "actorType": "campaign",           "metadata": { "utmCampaign": "torres-valle-oriente-q3" } },
    { "touchType": "whatsapp_sent",         "occurredAt": "2026-08-11T16:03:20.000Z",
      "actorType": "agent",              "actorId": "a1c8…" },
    { "touchType": "outbound_call",         "occurredAt": "2026-08-12T18:31:02.000Z",
      "actorType": "agent",              "relatedCallId": "c93f…" },
    { "touchType": "appointment_scheduled", "occurredAt": "2026-08-12T18:44:07.000Z",
      "actorType": "agent" }
  ]
}

Conversaciones

Citas

Conversiones

Analítica agregada

Los KPIs ya calculados, para no reconstruirlos a mano desde los recursos crudos.

{
  "data": [
    {
      "key":                   "torres-valle-oriente-q3",
      "utmSource":             "google",
      "leads":                 214,
      "conversationsStarted":  198,
      "conversationsEngaged":  143,
      "qualifiedLeads":        76,
      "appointmentsScheduled": 41,
      "appointmentsCompleted": 28,
      "handoffs":              12,
      "conversions":           9,
      "revenue":               2340000.00,
      "currency":              "MXN",
      "unattributedLeads":     7
    }
  ],
  "meta": { "from": "2026-07-01", "to": "2026-07-31", "attributionModel": "last_touch" }
}

Agentes

Webhooks

Kelpi notifica en tiempo real hacia el endpoint que registres. Es la vía recomendada para mantener tu dashboard al día sin sondear la API.

{
  "url": "https://tu-servidor.com/webhooks/kelpi",
  "events": ["lead.created", "lead.qualified", "conversation.ended", "conversion.registered"]
}

Catálogo de eventos

Forma del envío

Todos los eventos llegan como POST con el mismo sobre. Tiempo de espera de 10 segundos; responde 2xx rápido y procesa en segundo plano.

POST /webhooks/kelpi
Content-Type: application/json
X-Kelpi-Event: lead.qualified
X-Kelpi-Signature: 4f3ab9c1e07d…

{
  "event": "lead.qualified",
  "timestamp": "2026-08-12T18:44:07.000Z",
  "organizationId": "3b7f…",
  "data": { /* el recurso completo */ }
}

Verificar la firma

X-Kelpi-Signature es el HMAC-SHA256 en hexadecimal del cuerpo crudo, con el secret de la suscripción. Compara en tiempo constante.

const { createHmac, timingSafeEqual } = require('crypto');

function verify(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(signature, 'hex');

  return a.length === b.length && timingSafeEqual(a, b);
}

Catálogos

Tipos de interacción del timeline

inbound_call · outbound_call · link_sent · link_clicked · sms_sent · whatsapp_sent · appointment_scheduled · objection_handled · opt_out · manual_entry · form_opened · form_engaged · checkout_started · payment_method_added · purchase_succeeded · purchase_failed

Errores y límites

Los errores devuelven el código HTTP correspondiente y un cuerpo uniforme.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid query parameters",
    "details": [ { "path": ["limit"], "message": "Number must be less than or equal to 100" } ]
  }
}