Documentación de API

1 Autenticación

Todo endpoint privado usa tokens de Firebase Auth. El token se envía en el header Authorization.

Authorization: Bearer <FIREBASE_ID_TOKEN>

El cliente obtiene el token con currentUser.getIdToken() (Firebase Auth v8).
El backend lo verifica con verifyIdToken en api/_auth-middleware.js y extrae el uid → aislamiento por tenant.
Sin token o token inválido → 401 { "error": "..." }.
Las acciones de administrador requieren además un custom claim de admin más un lease de sesión (_admin-access-session.js).

Nota: los tokens del panel interno (Mission Control) son independientes de este flujo. Se emiten por perfil y viajan como Bearer <MC_TOKEN> + header X-Profile. No aplican a la API pública aquí documentada.

Ejemplo de llamada autenticada

const token = await firebase.auth().currentUser.getIdToken();

const res = await fetch('/api/crm-contacts', {
  headers: { Authorization: `Bearer ${token}` }
});
const data = await res.json();

2 Convenciones

Aspecto	Regla
Formato	JSON en request y response (`Content-Type: application/json`)
Base URL	`https://app.zentixchatbot.cloud` (todas las rutas bajo `/api/`)
Errores	HTTP status real + `{ "error": "mensaje" }`
Códigos	`400` input inválido · `401` sin token · `403` prohibido · `404` · `409` conflicto · `429` rate limit · `500`
Métodos	La mayoría acepta `GET` (lectura) y `POST` (acción); el body puede llevar `{ "action": "..." }`
CORS	Solo los endpoints públicos de captura permiten origen del widget embebido
Idempotencia	Webhooks y crons son re-entrantes; deduplican por ID externo
Módulos internos	Los `_*.js` (132 archivos) no son invocables por HTTP

3 Endpoints públicos

No requieren autenticación. Usados por widgets, landings y proveedores externos.

Endpoint	Método	Descripción
/api/submit-lead	POST	Captura de lead pública (widgets, formularios, landings)
/api/submit-platform-inquiry	POST	Consulta comercial con honeypot anti-spam
/api/landing-agent	POST	Chat del agente público en landings
/api/chatbot-api	GETPOST	Runtime del chatbot (intents, prompts, scoring)
/api/chatbot-landing	GET	Página pública compartible de un agente
/api/scoring-service	POST	Scoring 5-pillar de leads
/api/paypal-client-id	GET	Client ID público para cargar el SDK de PayPal
/api/whatsapp-webhook	GETPOST	Verificación (GET) y eventos (POST) de WhatsApp Cloud
/api/favicon	GET	Favicon SVG
/api/not-found	GET	Fallback 404 de la API

4 Auth y perfil de usuario

Endpoint	Método	Descripción
/api/ensure-user-profile	POST	Crea/sincroniza el perfil del usuario recién autenticado (usa el token)
/api/send-welcome-email	POST	Email de bienvenida en el primer login (Resend)
/api/google-auth	POST	Inicia el OAuth de Google Calendar
/api/google-callback	GET	Callback OAuth de Google
/api/google-disconnect	POST	Revoca la conexión de Google Calendar

5 Pagos y facturación

Endpoint	Método	Descripción
/api/paypal-create-order	POST	Crea la orden de PayPal del checkout
/api/paypal-capture-order	POST	Captura el pago aprobado
/api/paypal-webhook	WEBHOOK	Eventos de PayPal con firma verificada
/api/billing-quote	GETPOST	Cotización de plan o upgrade
/api/billing-status	GET	Estado de suscripción y límites del tenant
/api/billing-reconcile	POST	Conciliación de pagos vs. suscripciones

6 CRM

Endpoint	Métodos	Descripción
/api/crm-contacts	GETPATCHDELETE	CRUD de contactos (DELETE cubre erasure de privacidad)
/api/crm-conversations	GETPOSTDELETE	Conversaciones por contacto o canal
/api/crm-deals	GETPOSTPATCHDELETE	Pipeline de deals
/api/crm-escalations	GETPOST	Escalations y handoff a humano
/api/crm-followups	GETDELETE	Seguimientos pendientes
/api/crm-exports	POST	Export CSV de datos CRM
/api/crm-action-center	GET	Cola de acciones sugeridas
/api/order-actions	GETPOST	Acciones de órdenes (crear, estado, cotizar)
/api/generate-quote-draft	GETPOST	Borrador de cotización
/api/score-lead	POST	Re-score manual de un lead
/api/followup-alerts	GET	Alertas de follow-ups vencidos
/api/import-apollo-contacts	POST	Import desde Apollo (auth + autorización previa)
/api/apollo-import	GET	Estado/lectura de import de Apollo

7 Agentes IA

Endpoint	Método	Descripción
/api/agents	GETPOST	Listar y crear chatbots del usuario
/api/generate-chatbot	POST	Genera un agente (config, prompt, use-cases)
/api/agent-train	GETPOST	Entrenamiento agéntico (fuentes, snippets, estado)
/api/auto-learn	POST	Auto-aprendizaje desde scraping
/api/scrape-website	POST	Scraping de sitio para entrenamiento
/api/support-agent	POST	Agente de soporte con tools
/api/support-agent-actions	POST	Acciones del agente de soporte
/api/agent-health-dashboard	GET	Métricas de salud de agentes
/api/agent-maintenance	POST	Mantenimiento autónomo (dedup, integridad)
/api/workspace-agent-runs	GET	Corridas del agente de workspace
/api/workspace-agent-schedules	GETPOST	Schedules del agente de workspace
/api/workspace-agent-artifacts	GET	Artefactos generados por corridas

8 Calendario y reuniones

Endpoint	Método	Descripción
/api/agenda-meetings	GETPOST	CRUD de reuniones agendadas
/api/booking-audit	GET	Auditoría de reservas (Twilio + Cloud)
/api/google-calendar-sync	POST	Sincroniza reuniones con Google Calendar

9 Canales de mensajería

Endpoint	Método	Descripción
/api/whatsapp-cloud	GETPOST	Integración WhatsApp Cloud API (envío, estado)
/api/whatsapp-cloud-setup	GETPOST	Canales históricos de WhatsApp Cloud: listado y desconexión; alta directa próximamente. Para nuevas conexiones usa Twilio WhatsApp.
/api/whatsapp-integration	GETPOST	Integración legada, ligada al tenant verificado
/api/twilio-whatsapp-setup	GETPOST	Credenciales de Twilio WhatsApp
/api/twilio-whatsapp-status	GET	Estado de la conexión de Twilio
/api/telegram-setup	GETPOST	Config del bot de Telegram (nunca devuelve el token)
/api/channel-health	GET	Salud de rutas por canal

10 Integraciones

Endpoint	Método	Descripción
/api/slack-integration	GETPOST	Conexión Slack (OAuth + configuración)
/api/n8n-integration	GETPOST	Conexión n8n (credenciales cifradas)
/api/firecrawl-import	GET	Import de Firecrawl por oleadas

11 SEO

Endpoint	Método	Descripción
/api/seo-workspace	GET	Datos SEO del workspace
/api/seo-portal	GETPOST	Portal SEO para clientes
/api/seo-portal-sync	GET	Sincronización del portal
/api/seo-audit	POST	Auditoría SEO
/api/seo-onpage	POST	Análisis on-page
/api/seo-local	POST	SEO local
/api/seo-roadmap-generator	POST	Generador de roadmap SEO
/api/seo-monthly-report	GETPOST	Reporte mensual
/api/seo-performance-sync	POST	Sincronización de performance
/api/seo-billing	GETPOST	Facturación del servicio SEO
/api/seo-capture-order	POST	Captura de orden de venta SEO

12 Workspace y notificaciones

Endpoint	Método	Descripción
/api/metrics-aggregator	GET	Métricas por tenant para Overview, Analytics y Sales
/api/dashboard-settings	GETPOST	Preferencias y settings del dashboard
/api/workspace-notifications	GETPOST	Notificaciones del workspace
/api/workspace-readiness	GET	Checklist de preparación del workspace
/api/resend-tracking	WEBHOOK	Eventos de tracking de Resend (aperturas, clicks)
/api/send-order-status-email	RETIRADO	Compatibilidad; las transiciones usan la ruta durable

13 MCP (Model Context Protocol)

Expone la API como tools MCP para asistentes de IA (Claude, ChatGPT, Cursor, Hermes). Transporte Streamable HTTP sin sesión; misma autenticación Bearer.

Endpoint	Método	Descripción
/api/mcp	POST	MCP Streamable HTTP (stateless): initialize, tools/list y tools/call con las 7 tools de Zentix. 401 sin token.

Guía completa de conexión (Claude Desktop, Cursor, stdio local, escrituras con recibo) en la página Servidor MCP. Escrituras acotadas a agenda_meeting_create con idempotencia; solo lectura por defecto.

14 Admin

Requieren custom claim de admin más lease de sesión. Sirven al Admin Control Center.

Endpoint	Método	Descripción
/api/admin-auth	POST	Verificación de sesión admin (claims + lease)
/api/admin-overview	GET	Resumen global de la plataforma
/api/admin-users	GET	Gestión de usuarios
/api/admin-leads	GET	Todos los leads (cross-tenant)
/api/admin-agents	GET	Todos los agentes
/api/admin-analytics	GET	Analytics global
/api/admin-payments	GET	Pagos globales
/api/admin-health	GET	Salud de la plataforma
/api/admin-actions	GETPOST	Acciones administrativas (revoca leases, etc.)
/api/admin-reset-crm-system	POST	Reset del sistema CRM — peligroso
/api/admin-reset-test-data	POST	Bulk-delete de datos de prueba

15 Cron jobs

Invocados por Vercel Cron con CRON_SECRET. Sin sesión de usuario. Frecuencias exactas de vercel.json.

Endpoint	Schedule	Descripción
/api/cron-workspace-agent	cada 2 min	Corridas agénticas programadas
/api/cron-crm-action-center	cada 2 min	Refresca la cola de acciones sugeridas
/api/cron-crm-ingestion-repair	cada 2 min	Repara la ingesta de CRM
/api/cron-workflow-outbox	cada 2 min	Outbox de workflows (integraciones Google)
/api/cron-channel-route-health	cada 5 min	Salud de rutas por canal
/api/cron-auto-analyze	cada 10 min	Selección de tareas ejecutables (leases, defers)
/api/cron-crm-followups	cada 10 min	Follow-ups de CRM
/api/send-meeting-reminders	cada 10 min	Recordatorios de reunión
/api/retry-failed-notifications	cada 30 min	Retry acotado de emails fallidos
/api/cron-crm-retention	horario (:15)	Retención y limpieza
/api/cron-firecrawl-import	diario 02:00	Consumidor de la cola de Firecrawl
/api/cron-maintenance	diario 06:00	Integridad de datos para todos los usuarios
/api/cron-revenue-attribution	lunes 06:00	Atribución lead→deal→order→payment
/api/send-onboarding-drip	diario 09:30	Drip de onboarding Day 1/3/7
/api/send-followup-reminders	diario 10:00	Recordatorios de follow-up
/api/send-weekly-digest	lunes 09:00	Digest semanal de actividad
/api/send-agent-health-alerts	domingo 08:00	Alertas de agentes inactivos

Interno: estos endpoints no son públicos. No publiques sus schedules ni el CRON_SECRET. Registrados en código pero sin schedule activo: cron-canonical-crm-migration, cron-recalculate-scores.

16 Webhooks entrantes

Llamados por terceros hacia Zentix. Todos verifican firma o secret antes de procesar.

Endpoint	Fuente	Descripción
/api/whatsapp-webhook	Meta	Verificación GET + eventos POST de WhatsApp Cloud
/api/twilio-whatsapp-webhook	Twilio	Mensajes entrantes de WhatsApp vía Twilio
/api/telegram-webhook	Telegram	Updates del bot
/api/slack-webhook	Slack	Events API
/api/paypal-webhook	PayPal	Pagos, disputas, suscripciones
/api/resend-inbound	Resend	Email entrante (parse)
/api/resend-inbound-routes	Resend	Config de rutas inbound
/api/webhook-intent-handler	interno	Enrutador de intents multi-canal

Ejemplo: verificación GET de WhatsApp Cloud

GET /api/whatsapp-webhook
  ?hub.mode=subscribe
  &hub.verify_token=<VERIFY_TOKEN>
  &hub.challenge=<CHALLENGE>

// Respuesta esperada: 200 con el valor de hub.challenge

17 Firestore directo

El frontend autenticado lee y escribe directo en estas colecciones (reglas en firebase-security-rules.txt).

userschatbotsleads dealsordersmeetings conversationsconversation_eventsescalations followup_alertspayment_linkstelegram_leads whatsapp_leadschatbot_config_audit

Conviven el acceso directo (legacy) y el acceso vía endpoints serverless. La dirección del proyecto es centralizar las escrituras en la API; las reglas de Firestore restringen por request.auth.uid.

18 Mapa: qué página llama a qué

Página / área	Llamadas API
Landing, features, pricing, contacto, soluciones, blog (ES+EN)	`landing-agent` (widget), `submit-lead` (formularios). El resto es estático.
/login	Firebase Auth (Google, Facebook, email) → luego `ensure-user-profile` y `send-welcome-email`
/checkout	SDK de PayPal + `paypal-create-order`, `paypal-capture-order`, `billing-quote`, `billing-status`
/dashboard (legacy)	CRM completo, canales, calendario, agentes, pagos y settings (~40 endpoints)
/workspace (Zentix 2.0)	39 endpoints del workspace agéntico
/admin-dashboard	`admin-auth` más lecturas y acciones de admin
Widget embebido (cliente)	`chatbot-api`, `submit-lead`
Página pública de agente	`chatbot-landing`, `chatbot-api`
Clientes MCP (Claude, ChatGPT, Cursor, Hermes)	`mcp` (tools sobre CRM, agenda, agentes y métricas)

Documentación relacionada

Servidor MCP — conecta tu asistente de IA a esta API
Base de conocimiento — guías de producto para usuarios
Planes y límites
Contacto — dudas de integración