API de captación

Manda leads a tu CRM de ZEVRA desde tu sitio web, tus formularios o cualquier sistema, de servidor a servidor.

Qué es

La API de captación es la puerta de entrada de leads que no llegan por Meta, por un portal ni por tu sitio en ZEVRA: el formulario de tu propio sitio web, un chatbot de terceros, un Zapier o Make, el sistema de tu call center. Cada lead que mandas aparece en tu CRM con su origen, se asigna al asesor que toque según tus reglas de Captación y dispara los mismos automatismos que cualquier otro canal (tarea de primer contacto, planes de seguimiento, Agente IA si la línea está activa).

Es una API HTTP sencilla: un solo endpoint, POST https://api.zevra.co/v1/leads, con JSON de ida y de vuelta.

Servidor a servidor

La llave de API identifica a tu organización. Por eso la solicitud la hace tu servidor, nunca el navegador del visitante: la API no manda cabeceras CORS y no las va a mandar. Si tu formulario vive en un sitio estático, pásalo por una función serverless, un endpoint de tu backend o una automatización (Zapier, Make, n8n) que guarde la llave por ti.

Todo lo que necesitas saber cabe en estas páginas:

Autenticación

Cómo obtener tu llave y cómo mandarla.

Idempotencia

Reintenta sin duplicar leads.

Modo de prueba

Valida sin escribir nada en tu CRM.

Errores

Cada código, qué significa y qué hacer.

Límites

Solicitudes por minuto y tamaños máximos.

Ejemplos

curl, Node.js, PHP y Zapier.

Referencia

El endpoint completo, generado desde la especificación.

Obtener la llave

En el dashboard entra a Captación.
Abre el canal API y crea un origen (o abre el que ya tengas). Cada origen es una llave; puedes tener una por sitio o por sistema para saber de dónde llega cada lead.
Pulsa Nueva llave. La llave completa (zvr_live_...) se muestra una sola vez: cópiala a la configuración de tu servidor en ese momento. Después solo verás su prefijo.
Si la pierdes o sospechas que se filtró, usa Revocar llave y crea otra. Una llave revocada responde 401 invalid_key desde ese instante.

En el mismo panel está Solicitudes recibidas: el registro de cada solicitud que llegó con esa llave, con su request_id, su estado y el lead que creó o enriqueció. Es tu primer lugar para depurar.

Tu primera solicitud

Empieza con el modo de prueba, que no escribe nada:

curl -X POST https://api.zevra.co/v1/leads \
  -H "Authorization: Bearer zvr_live_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -H "X-Zevra-Dry-Run: true" \
  -d '{
    "nombre": "Ana Ruiz",
    "telefono": "+52 55 0000 0001",
    "email": "ana@ejemplo.com",
    "mensaje": "Quiero agendar una visita este fin de semana.",
    "propiedad": { "codigo": "ZVR-0123" }
  }'

Si todo está bien, la respuesta es 200 con "status": "dry_run" y "would": "create" (o "enrich" si ese teléfono ya está en tu CRM). Quita la cabecera X-Zevra-Dry-Run y vuelve a mandarla: ahora recibes 201 con "status": "created", el lead_id y un lead_url que abre el lead en el dashboard.

{
  "lead_id": "7b1d9c1e-2f4a-4d0b-9a3c-5e6f7a8b9c0d",
  "status": "created",
  "lead_url": "https://dashboard.zevra.co/dashboard/leads?leadId=7b1d9c1e-2f4a-4d0b-9a3c-5e6f7a8b9c0d",
  "request_id": "req_4f1c9a2b7d3e8c5a6b0f1e2d"
}

El cuerpo de la solicitud

Campo	Obligatorio	Descripción
`nombre`	sí	Nombre del prospecto, hasta 200 caracteres.
`telefono`	no	Al menos 10 dígitos; acepta espacios, guiones y `+52`. Es el campo con el que detectamos si el lead ya existe.
`email`	no	Correo del prospecto.
`mensaje`	no	Lo que escribió, hasta 2 000 caracteres. Se guarda como nota.
`propiedad`	no	Un objeto con exactamente una de estas llaves: `codigo` (`ZVR-0123`), `external_code` (tu código propio) o `id` (UUID). Debe existir en tu catálogo.
`extras`	no	Hasta 20 pares llave-valor (texto, número o booleano) que se guardan en las notas del lead: el nombre del formulario, el presupuesto, la campaña.

El cuerpo completo no puede pasar de 64 000 bytes. Todos los detalles están en la referencia.

Crear o enriquecer

Si el telefono ya existe en tu organización, la API no crea un lead duplicado: enriquece el que ya está (rellena solo los campos vacíos, nunca sobrescribe lo que capturó tu equipo, y no lo reasigna) y responde 200 con "status": "enriched" y "matched_on": "telefono". El mensaje y los extras se agregan como una nota nueva, así que el asesor sí se entera de que el prospecto volvió a escribir.

Si quieres saber de antemano cuál de los dos va a pasar, manda la misma solicitud en modo de prueba.

Reintentos seguros

Las redes fallan. Para que un reintento nunca te cree dos leads, manda una cabecera Idempotency-Key con un identificador único por envío (por ejemplo, el id del registro en tu formulario). Si repites la misma llave con el mismo cuerpo dentro de 24 horas, recibes la respuesta original con "replay": true en lugar de un lead nuevo. Cómo funciona en detalle: Idempotencia.