API de Nexora CRM

Autenticación

Crea una clave en Panel → API, elige sus permisos (por ejemplo contactos:read) y envíala en cada solicitud:

Authorization: Bearer nx_live_xxxxxxxxxxxxxxxx

Recursos

Filtros en GET: subaccount_id, id, limit (máx. 200). POST requiere subaccount_id.

Ejemplos

# Exportar contactos en CSV (hasta 5000 filas)
curl "https://TU-DOMINIO/api/public/v1/contactos?format=csv&limit=5000" -H "Authorization: Bearer nx_live_..." -o contactos.csv

# Registro de auditoría (permiso auditoria:read)
curl https://TU-DOMINIO/api/public/v1/auditoria?limit=100 -H "Authorization: Bearer nx_live_..."

# Listar contactos
curl https://TU-DOMINIO/api/public/v1/contactos?limit=20 \
  -H "Authorization: Bearer nx_live_..."

# Crear contacto
curl -X POST https://TU-DOMINIO/api/public/v1/contactos \
  -H "Authorization: Bearer nx_live_..." -H "Content-Type: application/json" \
  -d '{"subaccount_id":"UUID","name":"Ana Torres","email":"ana@correo.com","tags":["web"]}'

# Mover una oportunidad de etapa
curl -X PATCH "https://TU-DOMINIO/api/public/v1/oportunidades?id=UUID" \
  -H "Authorization: Bearer nx_live_..." -H "Content-Type: application/json" \
  -d '{"stage":"Ganado"}'

// JavaScript
const res = await fetch("https://TU-DOMINIO/api/public/v1/tickets", {
  method: "POST",
  headers: { Authorization: "Bearer nx_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ subaccount_id: "UUID", subject: "Necesito ayuda", priority: "alta" }),
});
const { data } = await res.json();

Webhooks de Salida

Eventos: contacto_nuevo, oportunidad_movida, pago, ticket_creado, curso_terminado, documento_firmado, resena_nueva, llamada_completada, referido_nuevo, reserva_nueva, chat_mensaje. Cada envío incluye X-Nexora-Event y X-Nexora-Signature: sha256=… (HMAC-SHA256 del cuerpo con tu secreto). Para webhooks de entrada puedes añadir X-Nexora-Timestamp (segundos Unix) y firmar timestamp.cuerpo; se rechaza si tiene más de 5 minutos. Se reintenta hasta 3 veces y queda en el registro de envíos.

// Verificar firma (Node.js)
import crypto from "crypto";
const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
const ok = req.headers["x-nexora-signature"] === "sha256=" + expected;

Webhooks de Entrada

Cada subcuenta tiene su dirección /api/public/hooks/SUBCUENTA_ID y su secreto. Firma el cuerpo igual que arriba. El campo opcional tipo decide qué se crea: contacto (por defecto: name, email, phone, tags, source), resena (author, rating 1-5, body, platform) o llamada (contact_name, phone, outcome, transcript, summary, duration_sec).

BODY='{"name":"Luis","email":"luis@correo.com","source":"Formulario"}'
SIG=$(printf %s "$BODY" | openssl dgst -sha256 -hmac "$SECRETO" | cut -d' ' -f2)
curl -X POST https://TU-DOMINIO/api/public/hooks/SUBCUENTA_ID \
  -H "X-Nexora-Signature: sha256=$SIG" -H "Content-Type: application/json" -d "$BODY"

# Registrar una reseña
BODY='{"tipo":"resena","author":"Marta","rating":5,"body":"¡Excelente!","platform":"google"}'

Reservas, Chat Embebible y Formularios

Cada subcuenta tiene un calendario público en /reservar/SUBCUENTA_ID (días, horario, duración y zona horaria se configuran en Panel → Reservas y chat web). Cada reserva crea el contacto, la cita y dispara reserva_nueva. Las citas también se leen y crean con el recurso citas.

El chat en vivo se instala con una línea; los mensajes llegan al buzón (recurso mensajes, platform: "web"), disparan chat_mensaje y el asistente IA responde solo con la base de conocimientos.

<script src="https://TU-DOMINIO/api/public/widget/SUBCUENTA_ID" async></script>

# Responder a un visitante del chat desde tu sistema
curl -X POST https://TU-DOMINIO/api/public/v1/mensajes -H "Authorization: Bearer nx_live_..." -H "Content-Type: application/json" \
  -d '{"subaccount_id":"UUID","platform":"web","contact_name":"Ana (#1a2b3c4d)","body":"¡Hola Ana!","direction":"saliente"}'

Los formularios (/f/FORM_ID) admiten lógica condicional: cada pregunta puede tener showIf: { field, equals } y solo se valida si está visible. Tipos: text, textarea, email, phone, select (options), checkbox, rating.

Servidor MCP

Cada agencia tiene su URL MCP (JSON-RPC sobre HTTP). Herramientas: buscar_contactos, crear_oportunidad, mover_oportunidad, responder_ticket, consultar_reporte, listar_resenas, responder_resena, registrar_llamada, consultar_afiliados, consultar_disponibilidad, listar_chats. Cada clave solo ve las herramientas que le permitas y todo uso queda registrado.

curl -X POST https://TU-DOMINIO/api/public/mcp/AGENCIA_ID \
  -H "Authorization: Bearer nxmcp_..." -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"buscar_contactos","arguments":{"q":"ana"}}}'

Errores y Límites

• 401: clave ausente o inválida
• 403: la clave no tiene el permiso
• 404: recurso no encontrado
• 429: límite por hora superado (cabecera Retry-After)