API y webhooks

Con API y webhooks, tus propios sistemas (ERP, almacén de datos, backend de tu web, herramientas de automatización) trabajan con tu workspace de NextCRM:

• la API REST lee y modifica leads, contactos, tareas y notas, y lee embudos, envíos de formularios, campañas y miembros del equipo;
• los webhooks avisan a tu servidor en cuanto ocurre algo, por ejemplo un lead nuevo o un cambio de etapa.

Nota: Solo los Admins del Workspace pueden abrir Ajustes > API y webhooks. El acceso a la API está incluido en los planes Business, Agency y Enterprise. En otros planes, las claves y endpoints existentes siguen visibles, pero no se pueden crear nuevos y las llamadas a la API se rechazan.

Dónde obtener cada valor

Todo procede del propio NextCRM; no necesitas ninguna cuenta de terceros.

Valor	Dónde obtenerlo
Clave de API	Ajustes > API y webhooks > Crear clave de API. La clave completa solo se muestra una vez; cópiala en tu integración (por ejemplo n8n, Zapier, Make o tu propio código) como token Bearer.
Secreto de firma	Se muestra una vez al añadir un endpoint de webhook, y de nuevo después de Renovar secreto. Guárdalo en el servidor que recibe los webhooks.
URL del endpoint	Procede de tu propio sistema o herramienta de automatización, por ejemplo la URL de producción de un nodo Webhook de n8n. Debe usar https.

Orden de configuración: crear una clave de API con los permisos que necesites > hacer una primera llamada > añadir un endpoint de webhook con sus eventos > verificar la firma en tu servidor > enviar un evento de prueba.

Crear una clave de API

1. Haz clic en tu tarjeta de perfil en la parte inferior de la barra lateral, elige Configuración, abre la tarjeta API y webhooks (abrir API y webhooks) y quédate en la pestaña Claves de API.
2. Haz clic en Crear clave de API.
3. Introduce un Nombre que indique dónde se usa la clave, por ejemplo "Sincronización ERP".
4. En Permisos, elige Leer y/o Escribir por área. Elige solo lo que la integración necesita de verdad.
5. Si quieres, fija una caducidad en Caduca (30, 90 o 365 días, o una fecha).
6. Haz clic en Crear clave y copia la clave enseguida con Copiar.

Advertencia: La clave solo se muestra una vez. NextCRM guarda únicamente una huella (hash) de ella, así que nadie - ni siquiera el soporte - puede volver a mostrarla. Si se pierde, revócala y crea una nueva.

La lista muestra cada clave con su prefijo (por ejemplo ncrm_live_1a2b3c4d), sus permisos, quién la creó, cuándo se usó por última vez y cuándo caduca. Revocar bloquea la clave de inmediato.

Qué puede hacer una clave

Una clave actúa en nombre de tu workspace con los derechos de un Admin del Workspace, limitada a los permisos elegidos:

Permiso	Permite
Leads (leer / escribir)	Listar y leer leads; crear, modificar, mover a una etapa, asignar, mover a la Papelera y restaurar
Contactos (leer / escribir)	Listar, leer, crear, modificar y eliminar contactos
Tareas (leer / escribir)	Listar y leer tareas; crear, modificar, completar y archivar
Embudos y etapas (leer)	Leer embudos con sus etapas
Envíos de formularios (leer)	Leer formularios y sus envíos
Campañas (leer)	Leer campañas y sus resultados
Notas y actividades (leer / escribir)	Leer las notas y el historial de un lead; añadir notas y registrar llamadas
Miembros del equipo (leer)	Leer nombres, correos y roles de los miembros (para asignar leads y tareas)
Webhooks (leer / escribir)	Leer, registrar y eliminar endpoints de webhook

Se aplican las mismas reglas que en la app: límites del plan (un lead nuevo por encima de tu límite de leads activos va a la Bandeja de leads), la Papelera (los leads en la Papelera deben restaurarse antes de modificarlos; eliminar por la API siempre mueve a la Papelera) y los datos nunca pasan a otro workspace. Lo que solo pueden hacer las personas - gestionar el equipo, los roles, la facturación o las claves de API y eliminar definitivamente - no es posible con una clave. Además, una clave deja de funcionar cuando quien la creó ya no es Admin del Workspace.

Cada cambio hecho con una clave aparece en el historial del lead como API key <nombre>.

Haz tu primera llamada

Envía la clave en la cabecera Authorization. La URL base es https://…/api/v1.

curl https://…/api/v1/leads?limit=10 \
  -H "Authorization: Bearer ncrm_live_..."

Crear un lead:

curl -X POST https://…/api/v1/leads \
  -H "Authorization: Bearer ncrm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2a10-order-4711" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","value":12000}'

La referencia completa con todos los endpoints, campos y un ejemplo con curl está en la pestaña Documentación de la API, de forma pública en https://…/api/v1/docs y como archivo OpenAPI 3.1 en https://…/api/v1/openapi.json.

Reglas para cualquier integración

• Respuestas con la forma { "data": ..., "meta": { ... } }; errores { "error": { "code", "message", "details" } } con la lista de campos en los errores de validación. Las fechas van en ISO 8601, UTC.
• Paginación: las listas devuelven meta.next_cursor; envíalo como cursor para obtener la página siguiente (limit hasta 100).
• Idempotencia: envía una cabecera Idempotency-Key con las solicitudes POST. Un reintento con la misma clave devuelve el primer resultado en lugar de crear un duplicado (durante 24 horas).
• Límites de solicitudes: 120 por minuto por clave y 600 por workspace. Por encima, la API responde 429 con la cabecera Retry-After: espera esos segundos.
• Mantenimiento: durante una actualización de NextCRM la API responde 503 MAINTENANCE con Retry-After. Los webhooks se retienen y se entregan después.
• Solo desde el servidor: llama a la API desde tu servidor. Los navegadores no pueden llamarla (sin CORS) y una clave de API nunca debe ir en una web o app.

Webhooks

1. Abre la pestaña Webhooks y haz clic en Añadir endpoint.
2. Introduce la URL del endpoint de tu servidor. Debe empezar por https:// y ser accesible desde internet; las direcciones internas, privadas y de metadatos de la nube se rechazan.
3. Elige los Eventos que quieres y haz clic en Guardar endpoint.
4. Copia el secreto de firma (se muestra una vez) y guárdalo en tu servidor.
5. Haz clic en Enviar evento de prueba para comprobar que tu servidor responde.

Eventos disponibles: lead.created, lead.updated, lead.stage_changed, lead.assigned, lead.trashed, lead.restored, task.created, task.completed, form.submitted, contact.created, contact.updated, campaign.sent, call.logged, nps.responded, customer.renewal_updated, customer.at_risk, booking.created, booking.rescheduled, booking.canceled, quote.sent, quote.accepted, quote.declined y automation.webhook.

Los eventos de presupuesto incluyen los importes como enteros en la unidad más pequeña de la moneda (por ejemplo, céntimos): subtotal_minor es la suma de las líneas tras los descuentos por línea, discount_minor el descuento sobre todo el presupuesto, tax_minor el impuesto y total_minor el importe a pagar. El total_minor de cada línea es su importe tras el descuento de línea, antes del descuento del presupuesto y del impuesto.

Los leads creados por una importación de archivo envían un lead.created por cada lead importado cuando termina la importación, con "context": { "source": "import", "import_batch_id": "..." } junto a data.

Cada entrega es un POST con el evento en JSON (id, type, created_at, actor, data) y estas cabeceras: X-NextCRM-Event, X-NextCRM-Delivery, X-NextCRM-Timestamp y X-NextCRM-Signature.

Verificar la firma

X-NextCRM-Signature tiene la forma t=1760860800,v1=5f2b.... Calcula el HMAC-SHA256 de <t>.<cuerpo sin procesar de la solicitud> con tu secreto de firma y compáralo con v1. Rechaza las solicitudes cuya marca de tiempo tenga más de 5 minutos.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return header.split(",").some((part) => part === `v1=${expected}`);
}

Reintentos, historial de entregas y renovación

• Responde con cualquier estado 2xx en menos de 10 segundos. Si no, NextCRM reintenta con pausas cada vez mayores (1, 2, 4, ... minutos), hasta 8 intentos.
• El Historial de entregas muestra cada entrega con su estado, intentos y código de respuesta. Enviar de nuevo vuelve a poner una entrega en cola.
• Tras muchos fallos seguidos, el endpoint se desactiva automáticamente y todos los Admins del Workspace reciben una notificación. Corrige el endpoint y haz clic en Activar.
• Renovar secreto crea un secreto de firma nuevo. El anterior sigue firmando durante 24 horas para que puedas cambiar sin perder eventos.

Lora y la API

Lora puede explicar la API, abrir esta página y listar tus endpoints de webhook. Nunca crea, muestra ni revoca claves de API ni ve un secreto de firma: eso lo haces tú en esta página.

Solución de problemas

Respuesta	Significado
401 INVALID_API_KEY, API_KEY_REVOKED, API_KEY_EXPIRED	La clave es incorrecta, está revocada o ha caducado. Crea una nueva.
403 INSUFFICIENT_SCOPE	La clave no tiene el permiso para esta llamada. Crea una clave con el permiso necesario.
403 API_KEY_OWNER_NOT_ADMIN	Quien creó la clave ya no es Admin del Workspace. Un admin actual debe crear una clave nueva.
402 FEATURE_NOT_IN_PLAN	El plan no incluye acceso a la API.
409 LEAD_IN_TRASH	Restaura primero el lead (POST /leads/{id}/restore).
422 VALIDATION_FAILED	Consulta el campo y el motivo en error.details.
429 RATE_LIMITED	Espera los segundos de Retry-After y continúa.