Documentación

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

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) y flags.

La cuota mensual del plan aplica a ingests procesados correctamente. Claves inválidas, errores de validación o agotamiento de cuota devuelven errores HTTP sin consumir una evaluación exitosa cuando corresponde.

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 (recomendado HTTPS), 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 cuota

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.

La suscripción define un máximo de ingests exitosos por mes calendario en todos los proyectos de la cuenta. Si se agota la cuota, el ingest devuelve 429 hasta el siguiente ciclo o un upgrade de plan.

Respuestas y errores

Éxito: HTTP 200, cuerpo { ok: true, data: { traceId, riskScore, riskLevel, decision, flags } }.

Errores: HTTP 4xx/5xx con { ok: false, error: { code, message, details? } }. Códigos frecuentes: validation_error, unauthorized, invalid_api_key, subscription_inactive (HTTP 402 hasta pagar en Facturación), quota_exceeded, 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
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly event quota exceeded for your plan"
  }
}

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; los fallos quedan en auditoría). El tiempo de espera es acotado (unos pocos segundos).

Cabecera User-Agent: Activelead-Webhook/1.0. Content-Type: application/json. Validá HTTPS y autenticá las peticiones en tu lado (p. ej. secreto compartido en query o cabecera propia) si el endpoint es público—hoy no firmamos el cuerpo saliente con un secreto rotativo.

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.