← Inicio

Documentación

API HTTP de ingest, webhooks salientes y configuración en el panel.

Estado del servicio

Activelead evalúa cada lead en el servidor: enviás JSON por POST al endpoint de ingest con la clave del proyecto, recibís una puntuación de riesgo y una decisión sugerida, y opcionalmente recibís el mismo resultado en tu propia URL de webhook. No hay paquete npm aparte: usá HTTPS desde tu backend (Node, PHP, Go, etc.) o los ejemplos de Integrar dentro de la app.

Resumen

Flujo: tu servidor (o un edge de confianza) envía un POST por envío de formulario. Activelead guarda un evento, aplica tu umbral de riesgo y la regla de correo desechable, y devuelve JSON con traceId, riskScore, riskLevel, decision (allowed o blocked), flags y signals (lista de señales que explican el score).

Tu cuenta tiene un saldo de créditos prepagos: cada ingest exitoso descuenta 1 crédito al guardar el evento. Claves inválidas, errores de validación o falta de saldo devuelven errores HTTP sin consumir crédito en evaluaciones completadas.

Dónde configurar en la app

Tras registrarte, abrí Dashboard → tu proyecto → Ajustes: ver o rotar la clave API (formato lsk_live.<publicId>.<secret>), indicar la URL opcional de webhook saliente (HTTPS), copiar el secreto de firma HMAC de webhooks, ajustar el umbral de riesgo (0–100) y activar o no Bloquear correos desechables.

Proyecto → Integrar muestra ejemplos listos (cURL, Node, PHP, navegador) con tu host y clave enmascarada. Proyecto → Eventos lista evaluaciones pasadas; podés exportar CSV estando logueado.

Autenticación

Enviá la clave completa del proyecto en cada ingest. Dos formas equivalentes: Authorization: Bearer lsk_live.<publicId>.<secret>, o X-Api-Key: lsk_live.<publicId>.<secret> (el nombre del encabezado no distingue mayúsculas).

No expongas el secreto en bundles de front ni en repos públicos. Rotá la clave desde Ajustes si se filtra.

bash
# Same key in Authorization or X-Api-Key
curl -sS -X POST "https://activelead.norvik.tech/api/v1/ingest" \
  -H "Authorization: Bearer lsk_live.YOUR_PUBLIC_ID.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"leadId":"example-1"}'

# Alternative header
curl -sS -X POST "https://activelead.norvik.tech/api/v1/ingest" \
  -H "X-Api-Key: lsk_live.YOUR_PUBLIC_ID.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"leadId":"example-1"}'

Endpoint de ingest

Método y ruta: POST /api/v1/ingest (en el mismo origen que tu despliegue de Activelead, p. ej. https://tu-dominio.com/api/v1/ingest).

bash
curl -sS -X POST "https://activelead.norvik.tech/api/v1/ingest" \
  -H "Authorization: Bearer lsk_live.YOUR_PUBLIC_ID.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "form-2026-001",
    "formId": "contact",
    "email": "user@company.com",
    "ip": "203.0.113.10",
    "userAgent": "Mozilla/5.0 (compatible; MySite/1.0)",
    "metadata": { "source": "pricing-page" }
  }'

Campos del JSON de petición

leadId (string, obligatorio): identificador estable de tu lado (id de envío, CRM, etc.). Máx. 256 caracteres.

formId (string, opcional): etiqueta del formulario o embudo. Máx. 256 caracteres.

ip (string, opcional): IPv4/IPv6 del remitente. Si se omite, la API puede usar la IP del cliente según X-Forwarded-For / X-Real-Ip cuando existan.

email (string, opcional): formato de email válido; se usa para comprobar dominios desechables.

userAgent (string, opcional): cadena user-agent del navegador o cliente. Máx. 512 caracteres.

metadata (object, opcional): JSON arbitrario con tu contexto; se guarda en el evento y puede influir en heurísticas si el texto sugiere proxy/VPN.

json
{
  "leadId": "required-stable-id-from-your-system",
  "formId": "optional-form-label",
  "email": "optional@valid.email",
  "ip": "203.0.113.42",
  "userAgent": "optional-user-agent-string",
  "metadata": {
    "campaign": "spring",
    "any": "json-you-need-stored-with-the-event"
  }
}

Límite de tasa y créditos

Por clave API e IP de cliente se aplica un límite de tasa (protección de ráfagas). Si se supera, la API responde 429 con indicación de reintento.

El saldo de créditos prepagos aplica a todos los proyectos de la cuenta. Cada ingest exitoso descuenta 1 crédito. Sin saldo suficiente, el ingest devuelve 402 (insufficient_credits) hasta que recargues en Facturación.

Respuestas y errores

Éxito: HTTP 200, cuerpo { ok: true, data: { traceId, riskScore, riskLevel, decision, flags, signals } } (signals: strings, p. ej. disposable_domain_blocklist, baseline).

Errores: HTTP 4xx/5xx con { ok: false, error: { code, message, details? } }. Códigos frecuentes: validation_error, unauthorized, invalid_api_key, insufficient_credits (HTTP 402 sin saldo de créditos), rate_limited.

json
{
  "ok": true,
  "data": {
    "traceId": "clxxxxxxxxxxxxxxxx",
    "riskScore": 42,
    "riskLevel": "medium",
    "decision": "allowed",
    "flags": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "privateRange": false,
      "disposableEmail": false
    },
    "signals": ["baseline", "public_ip_routing_heuristic"]
  }
}

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough prepaid credits to complete this evaluation"
  }
}

Webhooks salientes (tu servidor)

Si configurás una URL de webhook en Ajustes del proyecto, Activelead hace POST con JSON tras cada ingest exitoso (asíncrono respecto a la respuesta al cliente; reintentos automáticos ante fallos; los fallos finales quedan en auditoría).

Cabeceras: User-Agent Activelead-Webhook/1.0, Content-Type application/json, X-Activelead-Timestamp (segundos Unix) y X-Activelead-Signature con formato v1=<hex>. El HMAC-SHA256 usa el secreto del proyecto (hex de 64 caracteres en Ajustes) sobre la cadena `${timestamp}.${cuerpoUTF8}` con el mismo JSON del POST. Verificá la firma antes de procesar el evento.

json
{
  "type": "activelead.lead.scored",
  "traceId": "clxxxxxxxxxxxxxxxx",
  "projectId": "cuid-project",
  "leadId": "form-2026-001",
  "riskScore": 72,
  "riskLevel": "high",
  "decision": "blocked",
  "sourceIp": "203.0.113.10",
  "flags": {
    "vpn": false,
    "proxy": true,
    "tor": false,
    "privateRange": false,
    "disposableEmail": false
  }
}

Eventos y exportación CSV

Los usuarios autenticados pueden abrir Eventos de un proyecto y descargar CSV (hasta un tope alto de filas por exportación). Incluye traceId, marcas de tiempo, leadId, formId, decision, riskScore, riskLevel, sourceIp, fragmento de userAgent y flags en JSON.

Patrón de URL (requiere sesión): GET /api/app/projects/{slug}/events/export — usá el botón en la UI o el mismo origen con la cookie de sesión.

Buenas prácticas de seguridad

Preferí integración server-side para que el secreto de la API no llegue al navegador. Si llamás desde el cliente, asumí que la clave puede extraerse—mejor un proyecto de bajo privilegio o un proxy en tu backend.

Usá TLS en todas las llamadas y en los webhooks. Rotá claves tras bajas de personal o sospecha de compromiso. Revisá Eventos ante picos o bloqueos inesperados.