Referencia de la API

URL base y formato de respuesta

Cada ruta se sirve bajo el prefijo /api. En local la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que leen el sitio web y el panel de NEXT_PUBLIC_API_BASE_URL (Variables de entorno). Los archivos se sirven fuera del prefijo: los archivos de marca del kit en /media/… y los archivos subidos en /media/uploads/….

Los cuerpos de las peticiones son JSON, salvo las subidas de archivos. Cada respuesta llega en el mismo envoltorio:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es un código corto que rellenan algunas escrituras, como project_created o invitation_sent, y está vacío en los demás casos. Los espacios de trabajo, proyectos y tareas se nombran por sus ids públicos (org_forma, prj_01); los miembros, invitaciones, claves y archivos por su número. Los textos de proyectos y tareas llevan ambos idiomas como { "en": { … }, "ar": { … } }.

La comprobación de estado no necesita token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Hasta que la base de datos responde y tiene sus tablas, responde 503 con "status":"unavailable" y "database":"down". La comprobación de estado de la imagen de Docker lee ese estado, y Docker Compose inicia el sitio web y el panel solo cuando pasa.

Los navegadores solo pueden llamar a la API desde las direcciones de CORS_ORIGIN. Sin definir, permite http://localhost:3030 y http://localhost:3031, y en producción la API se niega a iniciar sin él (Problemas de CORS).

Errores

Un fallo conserva el envoltorio, con success: false, data: null y el estado HTTP:

{
  "success": false,
  "data": null,
  "message": "seat_limit_reached",
  "errors": { "email": ["…"] }
}

• errors aparece en un fallo de validación (400), con los problemas por campo.
• Un campo desconocido en un cuerpo se rechaza con 400: cada cuerpo acepta solo los campos listados abajo.
• Cuando la API tiene una frase para el error, message es esa frase en el idioma de la petición (Accept-Language: ar para árabe): un inicio de sesión rechazado, todo 429, los registros cerrados, una cuenta protegida frente a un cambio de contraseña o correo, un secreto de webhook ausente, una suscripción que Stripe no pudo cancelar, un rol o permiso de plataforma que quien llama no tiene, y el modo de mantenimiento, entre otros.
• En los demás casos, en 401, 403 y 404 el message es una frase general del estado, y en 400, 402, 409, 410 y 503 es el motivo como código corto (seat_limit_reached, slug_taken, over_plan_limit, payment_declined, preview_expired, invitation_expired, payment_unavailable), que un cliente convierte en su propia frase. Un cambio a un plan inferior rechazado por el uso lleva además blockers.
• 402 significa un cambio a un plan superior que el proveedor de pago no quiso cobrar: payment_declined, payment_needs_action (el banco quiere que se confirme el pago) o payment_method_missing. El plan se queda como estaba.
• Mientras el personal de la plataforma tiene activado el modo de mantenimiento, toda ruta fuera de la lista corta de Modo de mantenimiento responde 503 a cualquiera que no sea personal de la plataforma, con la frase en message y code: "maintenance_mode".
• 401 significa sin token, un token caducado, o credenciales incorrectas. 403 significa sesión iniciada sin el permiso, o una escritura en un espacio de trabajo suspendido. 404 también responde por un espacio de trabajo del que quien llama no es miembro, para que un extraño no pueda saber qué espacios existen.
• Una petición por encima de un límite responde 429 (Límites por dirección).

Inicio de sesión

1. 01

   Inicio de sesión

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@northstack.example","password":"YOUR_PASSWORD"}'

   Pon la contraseña de ejemplo de Instalación en lugar de YOUR_PASSWORD, o usa una cuenta propia. data.access_token es el token, con token_type Bearer, expires_in y admin, la cuenta con sus roles de plataforma, permisos y espacios de trabajo.
2. 02

   Llama a una ruta protegida

   TerminalCopiar

   curl http://localhost:8000/api/workspaces \
     -H "Authorization: Bearer YOUR_TOKEN"

   Eso lista los espacios de trabajo de la cuenta con su rol en cada uno. Cada ruta de espacio de trabajo recibe entonces el id público del espacio en su ruta:

   TerminalCopiar

   curl "http://localhost:8000/api/workspaces/org_forma/projects?limit=20" \
     -H "Authorization: Bearer YOUR_TOKEN"

• remember: true firma un token de 30 días y remember: false uno de 12 horas; si se omite, el token dura JWT_EXPIRATION, 7d por defecto.
• Un correo desconocido y una contraseña incorrecta responden ambos 401 con el mismo mensaje, tras el mismo trabajo de hash de contraseña, de modo que ni la respuesta ni su tiempo indican qué correos tienen cuenta.
• Diez inicios de sesión fallidos desde una misma dirección en 15 minutos responden 429 hasta que el fallo más antiguo cumple 15 minutos (RATE_LIMIT_LOGIN). Los inicios de sesión correctos no cuentan.
• Los tokens no guardan estado: POST /api/auth/logout responde al instante, y cerrar sesión es que el cliente olvide su token.

Espacios de trabajo y permisos

• Las rutas de espacio de trabajo empiezan por /api/workspaces/:workspaceId, el id público del espacio. En cada petición la API comprueba que quien llama tiene una membresía activa allí (si no, 404) y tiene el permiso que nombra la ruta (si no, 403). El rol es el de la membresía: una persona puede ser propietaria de un espacio y administradora de otro.
• Un espacio de trabajo tiene cuatro roles (owner, admin, member, billing) y su propia matriz de 14 permisos: workspace.read, workspace.update, workspace.delete, projects.read, projects.write, members.invite, members.remove, roles.manage, billing.read, billing.manage, keys.manage, audit.read, ai.read y ai.apply. El propietario los tiene todos, y workspace.delete y roles.manage quedan con el propietario diga lo que diga la matriz. Un cambio en la matriz se aplica a la siguiente petición.
• Un espacio de trabajo suspendido conserva todo GET y rechaza cualquier otro método con 403.
• Un espacio de trabajo con pago vencido lo conserva todo hasta que pasan BILLING_GRACE_DAYS (7 por defecto); entonces no puede crear proyectos, invitaciones ni claves de API (403), mientras toda lectura y toda otra escritura siguen funcionando.
• Las rutas de plataforma (/api/platform, /api/users, /api/admins, /api/roles, /api/settings) comprueban en su lugar los permisos de plataforma de la cuenta, concedidos mediante roles de plataforma. Los datos de ejemplo crean Platform admin, con los 21, y Support, que lee todas las páginas de la plataforma y exporta informes. Una ruta que lista varios permisos acepta cualquiera de ellos.

• Equipo, roles y permisos
• Administración de la plataforma

Listas y paginación

{ "data": [ ], "total": 12, "page": 1, "limit": 7, "totalPages": 2 }

• Proyectos, proyectos archivados, actividad, conversaciones del chat y sus mensajes, y la página de organizaciones y usuarios de la plataforma con page y limit, como máximo 100 por página. Los valores por defecto son 7 proyectos, 12 eventos, 20 conversaciones y 10 organizaciones o usuarios.
• La página de personal, de ajustes de la plataforma y de roles de plataforma usa en su lugar page y page_count (10 por defecto, como máximo 100). La página de roles de plataforma solo cuando se dan ambos; si no, se devuelven todos los roles.
• Las listas vienen de la más reciente a la más antigua (proyectos, usuarios y organizaciones por su último cambio), con el id como desempate, salvo que se dé un sort; los roles de plataforma vienen por nombre. La lista de proyectos devuelve también counts por pestaña.
• Lo que pertenece a un solo espacio de trabajo y se muestra completo responde sin paginar: las tareas de un tablero, los miembros, las invitaciones, las claves de API, los archivos de un proyecto, las últimas 36 facturas y las últimas 8 notificaciones.

Espacios de trabajo, miembros y la matriz de roles

Invitaciones

Los correos de invitación pasan por los ajustes SMTP de la API, o van a su registro, con el enlace, mientras SMTP_HOST está vacío.

Proyectos y archivos

Crear un proyecto en un espacio de trabajo con pago vencido cuyo periodo de gracia ha terminado responde 403.

Tareas y el tablero

Una tarea se lista y se crea bajo su proyecto, y se cambia por su propio id bajo el espacio de trabajo.

Una persona asignada que no es miembro responde 400 con assignee_not_member. Cada cambio escribe un evento en el rastro de actividad, como task.moved con las columnas de origen y destino.

Resumen, actividad, notificaciones y búsqueda

Los últimos eventos del resumen y la campana muestran todo el rastro a quien llama con projects.read o audit.read, solo los eventos billing. a quien tiene billing.read y ninguno de esos dos, y nada a nadie más.

Facturación, su webhook y el pago de prueba

• El pago usa Stripe Checkout cuando STRIPE_SECRET_KEY está definido, y el pago de prueba integrado en caso contrario, o siempre que BILLING_PROVIDER=simulator. El pago de prueba no cobra a nadie.
• La dirección de retorno por sí sola nunca cambia un plan: solo lo hace el webhook firmado, o la sesión leída de vuelta en sync.
• El precio de Stripe de cada plan se crea en el primer uso, con la clave de búsqueda northstack_<plan>_usd_<cents>_month, así que no hay que configurar nada antes en Stripe.
• Un pago de Stripe completado para un espacio de trabajo que ya tiene una suscripción de Stripe cancela la antigua, con su tiempo sin usar abonado. invoice.paid guarda la factura de Stripe una vez (las facturas son únicas por id de factura del proveedor), con su importe y periodo, lleva el periodo del espacio de trabajo al que inicia una factura, y en una renovación aplica un cambio a un plan inferior programado para ella.
• En el pago de prueba la API renueva cada periodo al terminar (una factura pagada, los siguientes 30 días, un cambio a un plan inferior programado aplicado) y termina uno configurado para cancelarse. Una prueba que llega a su fin pasa a pago vencido, con el periodo de gracia. Los contadores de uso vuelven a cero en cada periodo. Esto se ejecuta en cada lectura de facturación y una vez por hora.
• Apunta tu webhook de Stripe a https://<your API>/api/billing/webhooks/stripe con los eventos de arriba más checkout.session.expired.

• Facturación
• Ajustes de pago

Claves de API y la API pública

curl http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer nst_live_…"

• El secreto de una clave de producción empieza por nst_live_, el de una clave de demostración por nst_demo_. Una clave de demostración funciona solo mientras la API funciona en modo demostración.
• Sin clave, una desconocida o revocada responde 401; una clave sin el alcance de la ruta responde 403; un espacio de trabajo suspendido rechaza la escritura.
• Toda ruta salvo la lista de proyectos se ejecuta como el creador de la clave: lo que crea queda registrado como hecho por él, con la validación del panel, los eventos de actividad y los límites del plan. Responde 404 cuando el creador ha dejado el espacio de trabajo, y las tres escrituras responden 403 cuando el rol del creador ya no tiene projects.write.
• Cada llamada cuenta para las solicitudes de API del plan, que leen la página de facturación y los límites del plan.

• Claves de API

Resumen de la plataforma y organizaciones

Usuarios, personal, roles de plataforma y ajustes

La protección de contraseñas y correos: quien llama y no es la propia cuenta puede definir su contraseña o cambiar su correo solo cuando es Platform admin o tiene todos los permisos de plataforma que tiene la cuenta; en caso contrario la API responde 403. El correo también está protegido, porque un restablecimiento de contraseña se envía a él.

La protección de roles: nadie puede conceder, quitar ni elevar un rol de plataforma más allá de sus propios permisos, así que admins.assign_roles o roles.assign_permissions por sí solos nunca llevan al rol Platform admin.

Los 21 permisos de plataforma son platform.view, reports.export, organizations.view, organizations.manage, users.view, users.create, users.update, users.delete, users.restore, admins.view, admins.create, admins.edit, admins.delete, admins.assign_roles, roles.view, roles.create, roles.edit, roles.delete, roles.assign_permissions, settings.view y settings.edit.

Ajustes públicos y modo de mantenimiento

Mientras el ajuste de plataforma maintenance_mode es true, toda petición de quien no es personal de la plataforma (una cuenta con platform.view) responde 503, con code: "maintenance_mode" y el mensaje "The platform is closed for maintenance. Please try again shortly." Un token ausente o incorrecto recibe el mismo 503. Estas siguen abiertas para todos:

• GET /api/health y GET /api/public-settings;
• POST /api/auth/login y POST /api/auth/logout, donde el inicio de sesión sigue rechazando con el 503 a quien no es personal una vez que las credenciales son correctas;
• POST /api/billing/webhooks/stripe y la descarga firmada de facturas;
• el endpoint MCP, que conserva su propia clave, y GET /api/demo/status;
• el POST /api/contact del sitio web y todas las rutas /api/licenses, para que el formulario de contacto y el pago de licencias sigan funcionando.

Todo lo demás está cerrado para quien no es personal, incluidos el registro, la recuperación de contraseña, las invitaciones, el alta inicial, la API pública bajo /api/v1, los archivos subidos y el asistente. La lista es back-end/src/common/constants/maintenance.constants.ts.

El formulario de contacto

• Un clientToken repetido devuelve el id del primer mensaje en lugar de guardar un segundo, así que reintentar es seguro.
• Un campo website relleno se trata como un bot: la respuesta es igual, y no se guarda nada.
• Cada dirección puede enviar cinco por hora; el siguiente responde 429.
• Los mensajes se guardan en la tabla contact_messages y se reenvían a CONTACT_INBOX cuando está definido.

El pago de licencias

• El precio es el propio del servidor, de back-end/src/modules/licenses/constants/license-offers.ts; el navegador nunca envía uno.
• Una tarjeta va a Stripe Checkout cuando STRIPE_SECRET_KEY está definido, PayPal a PayPal cuando PAYPAL_CLIENT_ID y PAYPAL_CLIENT_SECRET están definidos, y cualquiera de los dos al pago de prueba en caso contrario. En el modo demostración nunca se ofrece un proveedor con claves en vivo.
• Un pedido se paga una sola vez, por lo que llegue primero entre el checkout.session.completed de Stripe en POST /api/billing/webhooks/stripe, el confirm del retorno o el Pay del pago de prueba. Solo ese emite la clave de licencia y envía el recibo por correo. checkout.session.expired marca el pedido como fallido.
• El id del pedido es una cadena larga y aleatoria que solo llevan los enlaces de retorno del comprador. Un clientToken repetido responde con el primer pedido. Cada dirección puede iniciar diez pedidos por hora.

• El pago de licencias

Archivos subidos y multimedia

Las imágenes y los archivos de proyecto van al bucket de Cloudflare R2 cuando están definidas sus cinco variables R2_*, y en caso contrario a MEDIA_UPLOAD_DIR, y se sirven en PUBLIC_MEDIA_URL seguido de /uploads/….

Todo lo que la API sirve bajo /media lleva X-Content-Type-Options: nosniff, y un archivo que no es una imagen rasterizada, un PDF, texto plano, audio o vídeo (un archivo HTML o SVG, por ejemplo) se envía con Content-Disposition: attachment, de modo que se descarga en lugar de abrirse como una página en la dirección de la API. Los archivos de un bucket R2 los sirve el bucket, con el tipo con el que se subieron.

Límites por dirección

Una petición por encima de un límite responde 429, con una frase que nombra lo que se limitó y cuánto esperar, como "Too many sign-ups from this address. Wait an hour, then try again." Los recuentos viven en la memoria de la API, así que un reinicio los borra. Detrás de un proxy inverso, define TRUST_PROXY con el número de proxies delante de la API, o cada visitante se cuenta como la única dirección del proxy.

El asistente de IA, sus conversaciones y propuestas

Servidor MCP

Actualizaciones de permisos en vivo mediante socket.io

Rutas del modo demostración