Resumen. El backend de KopTup es una API REST en Express (Node.js) que guarda los datos en MongoDB, usa Redis para sesiones, cupos y topes de gasto, y llama a OpenAI en las demos con IA. Todas las rutas viven bajo /api/… (salvo las de salud) y cada una aplica su política de autorización en el servidor: pública, con sesión, dueño del recurso, equipo, administrador o "acceso a la demo". Esta página es la referencia completa, módulo por módulo, con los errores, los límites de uso y los flujos clave dibujados.

Para quién: un desarrollador que va a usar o cambiar la API, y el dueño que quiere entender qué pasa "por dentro" cuando alguien pide una demo, la aprueba el equipo y la abre el prospecto. Todos los ejemplos son respuestas reales del backend local con datos de ejemplo; los tokens se muestran como <oculto>.

En esta página:

1. La API en una imagen
2. Convenciones
3. Quién puede llamar cada ruta
4. Referencia por módulo
5. Códigos de error comunes
6. Límites de uso y topes de gasto
7. Flujos clave paso a paso
8. Ejemplos con curl
9. Salud del servicio y documentación interactiva
10. Para desarrolladores
11. Limitaciones conocidas
12. Páginas relacionadas

Cada petición pasa por las mismas capas antes de llegar al código que hace el trabajo. Si una capa la rechaza, la petición no sigue.

flowchart TD
    classDef cliente fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef capa fill:#e0e7ff,stroke:#4f46e5,color:#312e81
    classDef dato fill:#f1f5f9,stroke:#64748b,color:#334155
    classDef no fill:#fee2e2,stroke:#dc2626,color:#7f1d1d

    C["Web koptup.com, curl o servidor de la web"]:::cliente
    H["Cabeceras de seguridad (helmet)"]:::capa
    CO{"Origen permitido (CORS)?"}
    J["Lee el cuerpo JSON (máx. 2 MB)"]:::capa
    RL{"Dentro del cupo?"}
    R["Enrutador por prefijo /api/..."]:::capa
    P{"Política de la ruta"}
    K["Controlador o servicio"]:::capa
    M[("MongoDB")]:::dato
    RE[("Redis")]:::dato
    AI["OpenAI y correo"]:::dato
    E403["403 cors_forbidden"]:::no
    E429["429 demasiadas peticiones"]:::no
    E4xx["401, 403 o 503"]:::no

    C --> H --> CO
    CO -- no --> E403
    CO -- "sí" --> J --> RL
    RL -- no --> E429
    RL -- "sí" --> R --> P
    P -- rechaza --> E4xx
    P -- permite --> K
    K --> M
    K --> RE
    K --> AI

De arriba abajo: seguridad, CORS, tamaño del cuerpo, cupo de peticiones, política de la ruta y, al final, el controlador que lee o escribe en MongoDB, Redis u OpenAI.

El recorrido más importante de la API es el de una demo: alguien la pide, el equipo la aprueba, la persona activa su cuenta y la abre. El GIF muestra las peticiones reales de ese recorrido, una por cuadro:

GIF: ocho peticiones reales (solicitud, panel, aprobación, doble clic, revisión del enlace, activación, acceso a la demo y Mis demos) con las respuestas del backend local.

Cada ruta declara una de estas políticas. El inventario completo vive en el código, en apps/backend/src/routes/POLICIES.md; aquí está resumido y en la sección 4 aparece ruta por ruta. El detalle de los roles está en Roles y permisos.

La política Acceso a demo es la que conecta la API con el sistema de demos. Así decide el servidor:

flowchart TD
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef no fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef dec fill:#fef3c7,stroke:#d97706,color:#78350f

    A["Petición a una API de demo"] --> B{"Token válido y rol de equipo?"}:::dec
    B -- "sí" --> OK1["Pasa (motivo staff)"]:::ok
    B -- no --> C{"La demo existe y está activa?"}:::dec
    C -- no --> N1["403 demo_disabled"]:::no
    C -- "sí" --> D{"Modo de la demo"}:::dec
    D -- publico --> OK2["Pasa (motivo publico)"]:::ok
    D -- "solicitud o privado" --> E{"Hay sesión?"}:::dec
    E -- no --> N2["401 login_required, motivo sin_sesion"]:::no
    E -- "sí" --> F{"DemoGrant activo con expiresAt futuro?"}:::dec
    F -- "sí" --> OK3["Pasa (motivo grant) y registra el uso"]:::ok
    F -- no --> N3["403 demo_access_required, motivo expirado, revocado o sin_acceso"]:::no

La vigencia se compara con la hora actual en cada petición: un acceso vencido o revocado se niega al instante, sin esperar el proceso que corre cada hora.

La ruta pública GET /api/demo-access/:slug usa exactamente la misma regla, pero siempre responde 200 y pone la decisión en data. Así la ve la web al abrir /demo/<slug>:

Demo pública sin sesión (publico), demo con solicitud sin sesión (sin_sesion), con un acceso vigente (grant, con días restantes) y demo privada sin acceso (sin_acceso).

Lo que la web muestra en cada caso está en Flujos del prospecto y cliente.

Convenciones de las tablas: Auth es la política de la sección 3; :id es el _id de MongoDB salvo que se diga otra cosa; "→" separa lo que se envía de lo que se recibe.

Las rutas de prueba POST /api/contact/test-whatsapp y /api/contact/test-email se retiraron (solo existían fuera de producción y responden 404): la prueba de los avisos es POST /api/admin/notifications/test (4.15).

Los valores de reason son: staff, publico, grant, sin_sesion, sin_acceso, expirado, revocado, desactivada, no_existe y no_disponible.

Estas rutas se montan antes de /api/admin para que el rol sales pueda gestionar solicitudes y accesos sin entrar al resto del panel.

Las pantallas que usan estas rutas están en el Manual del administrador; por ejemplo, el enlace de activación que devuelve approve es el que el panel muestra para copiar o enviar por WhatsApp.

Todo este router exige admin o manager, salvo el cambio de rol (solo admin).

En estas rutas :orderId es el código del pedido (ORD-0001), no el _id.

Todas exigen sesión. Cada controlador filtra por la cuenta que llama (o permite al equipo, donde se indica).

Toda la ruta tiene su propio cupo: 180 peticiones por minuto por IP (GET /models no cuenta) y las preguntas al chat, otro de 60 por minuto por IP. Los bots, sus documentos y el historial se guardan en MongoDB (ver Modelos de datos); sin base de datos, las rutas /bots… responden 503 storage_unavailable.

La API anterior "por sesión" (/session, /upload, /message, /info, /config, /messages, /documents) se retiró: responde 404 y, al arrancar, el backend borra lo que dejó (colección chatbots y uploads/chatbot).

Códigos propios: demo_disabled, budget_exhausted, capacity (503); invalid_format (415); file_too_large (413); too_many_pages (más de 30 páginas), too_much_text (más de 400.000 caracteres aunque tenga 30 páginas o menos), empty_document, unreadable_document (422); daily_limit, question_limit, rate_limited (429); document_not_found (404); llm_error (502, la pregunta no se descuenta); lead_unavailable (503: no se pudo registrar la prueba, el documento no se procesó y el cupo del día se devuelve).

Todas exigen acceso a la demo gestor-contenido (abierta por defecto), texto de máximo 10.000 caracteres, presupuesto disponible y cupo de 20 cada 10 minutos y 100 al día por IP (el equipo no tiene cupo).

Todas exigen sesión y cada consulta se filtra por la cuenta que llama. Las que usan IA (subir, búsqueda semántica y explicaciones) tienen tope mensual DOCUMENTS_MONTHLY_BUDGET_USD y cupo diario por cuenta DOCUMENTS_AI_DAILY_LIMIT_PER_USER (ver 6.3); sin cupo, una subida guarda el documento sin análisis y lo dice (ai: { analyzed: false, code }).

Estas rutas sirven a dos demos privadas (solo por invitación: Cuentas médicas y Sistema experto) y a la herramienta interna /liquidacion del equipo. Las que procesan con IA (/procesar-facturas-pdf, /procesar-modular, /aprendizaje/feedback, /api/expert/procesar* y /generar-excel, /api/cups/buscar-*, vectorizar, revectorizar, /cuentas/procesar-hibrido y /process) tienen tope mensual HEALTH_MONTHLY_BUDGET_USD y cupo diario por cuenta HEALTH_AI_DAILY_LIMIT_PER_USER (el equipo solo tiene el tope mensual). La interpretación de reglas de /api/reglas-facturacion (solo el equipo) también cuenta contra ese tope mensual.

En producción responde 404 Endpoint not found, igual que una ruta que no existe. El diagnóstico de WhatsApp que vivía en /api/test (/whatsapp, /whatsapp/status) se retiró: lo reemplazan GET /api/admin/notifications/status y POST /api/admin/notifications/test (4.15), que también funcionan en producción.

Cada contacto nuevo (POST /api/contact, POST /api/demo-requests y la subida de «Prueba con tu documento») avisa al dueño por correo (Resend por API HTTPS; SMTP solo como respaldo) y por WhatsApp (WhatsApp Cloud API de Meta con la plantilla koptup_aviso). El envío no frena la respuesta del formulario. Estas rutas no dependen de COMMERCE_ENABLED; las de /api/admin/notifications se montan antes de /api/admin. El recorrido completo está en el diagrama 7.7 y la configuración en Operación y despliegue › 4.5.

Las dos rutas del webhook responden 404 not_found mientras falte WHATSAPP_WEBHOOK_VERIFY_TOKEN o WHATSAPP_APP_SECRET. Se montan antes del parser JSON global porque la firma se calcula sobre el cuerpo crudo, y no pasan por el límite general de /api.

Estados de Contact.notificaciones.<canal>.estado:

Forma de la respuesta de GET /api/admin/notifications/status (valores de ejemplo, no de producción):

{
  "success": true,
  "data": {
    "email": {
      "proveedor": "resend", "configurado": true, "destino": "du***@ejemplo.co",
      "remitente": "KopTup <[email protected]>",
      "ultimoExito": "2026-10-14T15:02:11.000Z", "ultimoFallo": null, "ultimoError": null, "faltan": []
    },
    "whatsapp": {
      "proveedor": "meta", "configurado": true, "destino": "+57 *** *** 1234",
      "plantilla": "koptup_aviso", "webhook": false,
      "ultimoExito": "2026-10-14T15:02:12.000Z", "ultimoFallo": null, "ultimoError": null, "faltan": []
    },
    "latido": { "activo": true, "cadaDias": 30, "ultimo": "2026-10-14T15:00:03.000Z", "proximo": "2026-11-13T15:00:03.000Z" }
  }
}

Con un canal sin configurar, configurado es false y faltan lista las variables (por ejemplo ["RESEND_API_KEY"] o ["WHATSAPP_API_TOKEN", "ADMIN_WHATSAPP_NUMBER"]). Si WHATSAPP_PROVIDER pide un proveedor retirado (twilio, ultramsg), proveedor es null y faltan es ["WHATSAPP_PROVIDER"].

Validación con mensajes por campo, API de demo sin sesión, sin acceso, sin el rol, acción repetida y enlace ya usado: respuestas reales del backend local.

Los códigos de cada módulo (chatbot, demo RAG, LinkedIn) están en su sección. Una respuesta antigua sin código propio recibe el del estado HTTP (bad_request, unauthorized, forbidden, not_found, conflict, internal_error…); en producción, un 5xx nunca devuelve detalles internos.

Los cupos marcados "memoria" se cuentan en el proceso del backend; los marcados "Redis" se comparten entre instancias.

Cada ruta de cuenta tiene su propio contador: agotar el del login no bloquea el registro, la recuperación ni la activación. Los cupos por correo cuentan el correo normalizado (mayúsculas, puntos y +etiqueta de Gmail no abren un contador nuevo). Todas las respuestas 429 traen code: "rate_limited", un mensaje en español y la cabecera Retry-After.

Detrás del proxy de Railway el servidor confía en un salto (TRUST_PROXY_HOPS, por defecto 1) para leer la IP real del visitante. Los cupos estándar se ven en las cabeceras RateLimit-* de cada respuesta:

La captura es anterior a la verificación final del 14 de octubre de 2026: hoy el chatbot informa 180 por minuto en sus rutas y 60 por minuto en las preguntas. La verificación de sesión informa 120 por minuto y la demo RAG publica sus límites en /status.

Seis funciones con IA tienen un tope mensual en dólares. El gasto se calcula con los tokens que informa el proveedor, se suma en Redis por mes (UTC) y la API nunca devuelve montos.

flowchart LR
    classDef ok fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef no fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
    classDef dec fill:#fef3c7,stroke:#d97706,color:#78350f

    A["Petición que usaría IA"] --> B{"Hay clave de OpenAI?"}:::dec
    B -- no --> X1["503 o modo sin IA"]:::no
    B -- "sí" --> C{"Redis responde?"}:::dec
    C -- no --> X2["Falla cerrada: 503 o modo sin IA"]:::no
    C -- "sí" --> D{"Gasto del mes menor al tope?"}:::dec
    D -- no --> X3["budget_exhausted"]:::no
    D -- "sí" --> E{"Dentro del cupo?"}:::dec
    E -- no --> X4["429 rate_limited"]:::no
    E -- "sí" --> F["Llama al modelo y suma el costo al mes"]:::ok

Si no se puede medir el gasto, no se gasta: sin Redis, las funciones con IA públicas se apagan o pasan a su modo sin IA.

Un tope con valor inválido o negativo deja la función sin presupuesto (cero). En documentos y salud, el cliente de OpenAI de cada función suma el costo real de cada respuesta y no llama al modelo con el tope agotado o sin Redis, aunque el servicio que lo use no pase por la ruta con cupo.

Los cuatro diagramas siguientes cubren el recorrido completo solicitud → aprobación → activación → acceso. El mismo recorrido, visto por el usuario, está en Flujos del prospecto y cliente. El 7.7 muestra el aviso al dueño de un contacto nuevo, con sus reintentos y el webhook de WhatsApp.

sequenceDiagram
    autonumber
    actor V as Visitante
    participant W as Web
    participant A as API
    participant R as Redis
    participant M as MongoDB
    actor D as Dueño
    V->>W: Llena Solicitar demo y autoriza sus datos
    W->>A: POST /api/demo-requests
    alt Campo trampa lleno (bot)
        A-->>W: 201 con un código, sin guardar nada
    else Sin autorización de datos
        A-->>W: 400 consent_required
    else Datos inválidos
        A-->>W: 400 invalid_request con errores por campo
    else Datos válidos
        A->>R: Suma 1 al cupo de la IP y al del email
        alt Cupo agotado
            A-->>W: 429 rate_limited con Retry-After
        else Hay cupo
            A->>M: Busca una solicitud abierta del mismo email (30 días)
            alt Ya existe
                A->>M: Le suma las demos y anota el reenvío
                A-->>W: 201 fusionada true
            else Es nueva
                A->>M: Crea DemoRequest pendiente con la prueba del consentimiento
                A-->>W: 201 codigo y estado pendiente
                A->>M: Registra el lead en Contact (demo-request)
                A-->>V: Acuse por correo (si hay correo configurado)
                A--)D: Aviso al dueño por correo y WhatsApp, sin esperar
            end
        end
    end

sequenceDiagram
    autonumber
    actor E as Equipo
    participant A as API
    participant M as MongoDB
    participant S as Correo
    E->>A: POST /api/admin/demo-requests/:id/approve
    A->>M: Lee el rol vigente del que aprueba
    alt Demo privada y no es admin
        A-->>E: 403 requires_admin
    else Puede aprobar
        A->>M: Cambia pendiente o en_revision a aprobada (condicionado)
        alt Otro ya la procesó
            A-->>E: 409 already_processed
        else La reclamó
            A->>M: Vincula la cuenta del email o crea una prospect invitada
            A->>M: Crea un DemoGrant por demo (o extiende el vigente)
            A->>M: Emite el enlace de activación (72 h, solo se guarda su hash)
            A->>S: Correo con el enlace si hay correo configurado (espera hasta 15 s)
            A->>M: Registra demo_request.approve en la bitácora
            A-->>E: 200 con activationUrl, accesos y si el correo salió
        end
    end

Si algo falla a mitad de camino, la API deshace lo que creó y devuelve la solicitud a su estado anterior.

sequenceDiagram
    autonumber
    actor P as Prospecto
    participant W as Web
    participant A as API
    participant M as MongoDB
    participant R as Redis
    P->>W: Abre /activar/TOKEN
    W->>A: POST /api/auth/activate/check
    A->>M: Busca el hash del token sin gastarlo
    A-->>W: Nombre y correo enmascarado, o token_invalid, token_used, token_replaced, token_expired
    P->>W: Escribe su contraseña
    W->>A: POST /api/auth/activate
    A->>M: Marca el enlace como usado (atómico, un solo uso)
    A->>M: Guarda la contraseña cifrada y pasa la cuenta a activo
    A->>M: Invalida otros enlaces pendientes y registra user.activate
    A->>R: Guarda el refresh token (7 días)
    A-->>W: accessToken, refreshToken y usuario
    W-->>P: Mis demos con aviso de bienvenida

sequenceDiagram
    autonumber
    actor P as Prospecto
    participant W as Servidor de la web
    participant A as API
    participant M as MongoDB
    P->>W: Abre /demo/erp
    W->>A: GET /api/demo-access/erp con su token
    A->>M: Catálogo (modo y activa) y DemoGrant de la cuenta
    alt Acceso vigente
        A->>M: Suma una visita si pasaron 30 min desde la última
        A-->>W: allowed true, reason grant, días restantes
        W-->>P: Muestra la demo
        P->>A: Llamadas a la API de la demo, por ejemplo /api/linkedin-ads/generate
        A->>M: Repite la revisión del acceso en cada llamada
        A-->>P: Respuesta de la demo
    else Sin acceso, vencido o revocado
        A-->>W: allowed false con el motivo
        W-->>P: Pantalla /demo-acceso/erp con la salida adecuada
    end

sequenceDiagram
    autonumber
    participant W as Web
    participant A as API
    participant R as Redis
    W->>A: POST /api/auth/login
    A->>R: Guarda refresh_token de la cuenta (7 días, reemplaza el anterior)
    A-->>W: accessToken de 15 min y refreshToken
    W->>A: Peticiones con Authorization Bearer
    A-->>W: 401 TOKEN_EXPIRED cuando vence
    W->>A: POST /api/auth/refresh
    A->>R: Compara con el guardado
    A-->>W: accessToken nuevo
    W->>A: POST /api/auth/logout
    A->>R: Borra el refresh token

sequenceDiagram
    autonumber
    participant J as Proceso horario
    participant R as Redis
    participant M as MongoDB
    participant S as Correo
    J->>R: Toma el candado jobs:demo-grants:lock
    alt Otra instancia lo tiene
        J-->>J: Salta esta corrida
    else Lo toma (o Redis no responde)
        J->>M: Marca expirado los accesos activos con expiresAt pasado
        opt Hay correo configurado
            J->>M: Reclama los que vencen en 3 días sin recordatorio
            J->>S: Un recordatorio por persona
        end
        J->>R: Suelta el candado
    end

Corre cada hora (DEMO_GRANTS_JOB_INTERVAL_MS), la primera vez unos 30 segundos después de arrancar; DEMO_GRANTS_JOB_ENABLED=false lo apaga. La vigencia real no depende de él: la API compara la fecha en cada petición.

sequenceDiagram
    autonumber
    actor V as Visitante
    participant A as API
    participant M as MongoDB
    participant RS as Resend
    participant ME as Meta WhatsApp
    actor D as Dueño
    V->>A: POST /api/contact (o Solicitar demo, o Prueba con tu documento)
    A->>M: Crea el Contact con cada canal pendiente o no_configurado
    A-->>V: 200 sin esperar los avisos
    par Correo
        A->>RS: POST /emails con Idempotency-Key contact-id-email-hash del cuerpo y reply_to
        alt 2xx con id
            RS-->>A: id del correo
            A->>M: email enviado con idProveedor
            RS--)D: Correo a NOTIFY_EMAIL
        else Error o sin respuesta en 15 s
            A->>M: email fallido con error y proximoIntento
        end
    and WhatsApp
        A->>ME: POST /v25.0/id-del-número/messages con la plantilla koptup_aviso
        alt 2xx con wamid
            ME-->>A: wamid
            A->>M: whatsapp enviado con idProveedor
            ME--)D: WhatsApp al número del dueño
        else Error de plantilla 132xxx
            A->>ME: Plantilla de respaldo hello_world
            A->>M: whatsapp enviado con respaldo hello_world y el error
        else Otro error
            A->>M: whatsapp fallido con el código de Meta
        end
    end
    loop Cada 5 min, contactos de los últimos 3 días
        A->>M: Reclama los canales fallidos con proximoIntento vencido
        A->>RS: Reintento (misma Idempotency-Key si el cuerpo no cambió)
        A->>ME: Reintento de la plantilla
    end
    opt Webhook configurado
        ME->>A: POST /api/webhooks/whatsapp firmado
        A->>M: Busca por wamid y pasa a entregado, leido o fallido
        A--)D: Si falló, correo de alerta con el código de Meta
    end

El formulario responde sin esperar a los proveedores. Cada canal se envía y se guarda por separado; un reintento nunca toca un canal que ya salió. Antes de cada intento, el backend «reclama» el canal con una actualización condicionada, así que dos procesos nunca envían el mismo aviso a la vez. Una vez al mes, el job del latido manda un aviso de prueba por los dos canales.

Usa tu backend local y guarda la URL en una variable. Las respuestas son reales (recortadas donde dice …).

export API=http://localhost:3001

curl -s "$API/api/demo-catalog"

{
  "success": true,
  "fuente": "bd",
  "data": [
    { "slug": "chatbot", "nombre": "Chatbot RAG con tus documentos", "nombreEn": "RAG chatbot over your documents", "accessMode": "publico", "activo": true },
    { "slug": "code-review-ia", "nombre": "Revisión de código con IA", "nombreEn": "AI code review", "accessMode": "publico", "activo": true },
    …
  ]
}

curl -s -X POST "$API/api/demo-requests" \
  -H 'Content-Type: application/json' \
  -d '{
    "nombre": "Laura Martínez",
    "empresa": "Agroinsumos del Llano SAS",
    "cargo": "Gerente administrativa",
    "email": "[email protected]",
    "telefono": "+57 310 555 0101",
    "pais": "Colombia",
    "tamanoEmpresa": "11-50",
    "demos": ["erp", "linkedin-ads"],
    "casoDeUso": "Queremos controlar inventario y facturación de nuestras tres bodegas en un solo sistema.",
    "consentimiento": true,
    "origen": { "pagina": "/solicitar-demo", "utm": { "source": "linkedin", "campaign": "erp-pymes" } }
  }'

{
  "success": true,
  "message": "Recibimos tu solicitud. Te escribiremos al correo que indicaste.",
  "data": { "codigo": "DR-2026-6T8CKS", "estado": "pendiente", "fusionada": false }
}

Si falta la autorización de datos la respuesta es 400:

{
  "fields": ["consentimiento"],
  "success": false,
  "code": "consent_required",
  "message": "Debes autorizar el tratamiento de tus datos personales (Ley 1581 de 2012) para enviar la solicitud."
}

# 1. Inicia sesión (la contraseña es la que la persona creó al activar su cuenta)
curl -s -X POST "$API/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "[email protected]", "password": "<tu contraseña>" }'

{
  "success": true,
  "message": "Login successful",
  "data": {
    "accessToken": "<oculto>",
    "refreshToken": "<oculto>",
    "user": { "id": "6ac89e19d28776d0718d6513", "email": "[email protected]", "name": "Laura Martínez", "role": "prospect" }
  }
}

# 2. Copia el accessToken en una variable y pide tus demos
export TOKEN='<accessToken>'
curl -s "$API/api/me/demos" -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": [
    {
      "id": "6ac89e19d28776d0718d6516",
      "demoSlug": "erp",
      "demoNombre": "ERP modular",
      "accessMode": "solicitud",
      "demoActiva": true,
      "estado": "activo",
      "vigente": true,
      "expiresAt": "2026-10-23T07:56:09.487Z",
      "diasRestantes": 14,
      "ultimoAcceso": "2026-10-09T07:56:10.018Z",
      "accesos": 1,
      "url": "/demo/erp"
    },
    …
  ]
}

Con el mismo token, una API de una demo a la que la cuenta no tiene acceso responde 403:

curl -s "$API/api/auditoria/estadisticas" -H "Authorization: Bearer $TOKEN"

{
  "success": false,
  "code": "demo_access_required",
  "demo": "cuentas-medicas",
  "motivo": "sin_acceso",
  "message": "Tu cuenta no tiene acceso a esta demo. Solicítalo desde la página de la demo."
}

/health/live dice si el proceso está vivo; /health dice si puede atender (MongoDB conectado).

• /health/live responde 200 siempre que el proceso esté vivo, aunque MongoDB esté caído: sirve para diagnosticar si el proceso arranca.
• /health responde 503 mientras MongoDB no esté conectado. Es el healthcheck del despliegue en Railway (un despliegue sin base no entra en servicio y la versión anterior sigue atendiendo) y lo revisa el monitoreo de GitHub Actions cada 15 minutos. Si el backend arranca sin base de datos, sigue vivo y las rutas que necesitan leer roles o accesos responden 503 service_unavailable (falla cerrada).
• Swagger (/api-docs) existe solo fuera de producción o con API_DOCS_ENABLED=true. Se genera con los comentarios @swagger de src/routes/*.ts y config/swagger.ts le agrega el esquema de sesión (bearerAuth), qué rutas son públicas, las de solo desarrollo (marcadas como obsoletas) y el formato de error. Los comentarios no cubren todas las rutas: esta página es la referencia completa.

Qué hacer cuando el backend no responde está en Operación y despliegue.

Checklist para agregar una ruta:

1. Elige la política (sección 3) y aplícala en el archivo de rutas con los middleware de middleware/access.ts. Si la ruta es del equipo, usa requireRole (lee el rol en la base) y no solo el rol del token.
2. Valida la entrada (en el código nuevo se usa zod y zodToAppError para devolver fields y errores).
3. Lanza AppError(mensaje, status, code) o usa sendError(res, status, code, mensaje) en vez de armar el JSON a mano: así la respuesta tiene siempre success, code y un message en español.
4. Envuelve los controladores asíncronos con asyncHandler.
5. Si llama a OpenAI desde una ruta pública, pasa por getBudgetStatus y recordSpend y agrega un cupo en Redis.
6. Si la acción la hace el equipo, regístrala con recordAudit.
7. Agrega la ruta a routes/POLICIES.md y una prueba de integración.

• Modelos de datos: las colecciones que esta API lee y escribe, con sus estados.
• Roles y permisos: qué puede hacer cada rol.
• Arquitectura: dónde corre el backend y con qué servicios habla.
• Flujos del prospecto y cliente y Manual del administrador: las pantallas que usan estas rutas.
• Operación y despliegue: variables de entorno y procedimientos ante fallas.
• Backend y API (plan): el plan original de esta parte.