# Referencia de API de Neotask

Referencia completa de la API para la plataforma Neotask. Este documento cubre cada endpoint disponible, metodos de autenticacion, manejo de errores y limites de tasa.

---

## Autenticacion

Todas las solicitudes API requieren autenticacion mediante uno de los siguientes metodos:

- **Bearer JWT**: Pase el encabezado `Authorization: Bearer <token>`. Los tokens se obtienen de los endpoints de inicio de sesion descritos a continuacion.
- **HMAC de Licencia**: Firma HMAC-SHA256 vinculada al dispositivo utilizada por la aplicacion de escritorio Neotask. El cliente firma solicitudes con un secreto derivado de la clave de licencia y la huella digital del dispositivo.
- **Encabezado de Inquilino**: Incluya `x-tenant-id: <tenantId>` para cualquier endpoint con alcance de inquilino. Este encabezado identifica a que inquilino (espacio de trabajo) aplica la solicitud.

Muchos endpoints combinan multiples requisitos de autenticacion. Por ejemplo, "Tenant + Admin" significa que la solicitud debe incluir tanto un JWT valido (perteneciente a un usuario con el rol de Admin) como el encabezado `x-tenant-id`.

---

## Endpoints de Auth

Endpoints para autenticacion de usuarios en plataformas web, iOS y escritorio.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/auth/login` | Autenticar con correo y contrasena. Devuelve un JWT en caso de exito. | Ninguna |
| POST | `/api/auth/google` | Autenticar via Google OAuth en la web. Espera un codigo de autorizacion de Google. | Ninguna |
| POST | `/api/auth/google-ios` | Autenticar via Google OAuth en iOS. Espera un payload de autorizacion especifico de iOS. | Ninguna |
| POST | `/api/auth/google-token` | Verificar un token de acceso de Google y devolver un JWT de Neotask. | Ninguna |
| POST | `/api/auth/apple` | Autenticar via Apple Sign-In. Espera un token de identidad de Apple. | Ninguna |
| GET | `/api/auth/me` | Devolver el perfil del usuario autenticado (nombre, correo, avatar, roles). | JWT |
| DELETE | `/api/auth/account` | Eliminar permanentemente la cuenta del usuario autenticado y todos los datos asociados. | JWT |

---

## Endpoints de Auth del Panel

Endpoints de autenticacion especificos del panel de Neotask, incluyendo inicio de sesion con clave de licencia y autenticacion de dos factores (TOTP).

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/dashboard/auth/login` | Autenticar con una clave de licencia. Devuelve un JWT en caso de exito, o senala que se requiere TOTP. | Ninguna |
| POST | `/api/dashboard/auth/totp-login` | Completar inicio de sesion proporcionando un codigo TOTP o codigo de respaldo cuando la autenticacion de dos factores esta habilitada. | Ninguna |
| GET | `/api/dashboard/auth/me` | Devolver la informacion de licencia actual y los derechos de funciones para el usuario autenticado del panel. | JWT |
| POST | `/api/dashboard/totp/setup` | Generar un secreto TOTP y codigo QR para configurar la autenticacion de dos factores. | JWT |
| POST | `/api/dashboard/totp/verify` | Verificar un codigo TOTP para confirmar y habilitar la autenticacion de dos factores en la cuenta. | JWT |

---

## Endpoints de Facturacion

Gestionar suscripciones, sesiones de checkout y compras in-app a traves de Stripe y RevenueCat.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/billing/checkout` | Crear una sesion de Stripe Checkout para el plan Pro. Devuelve una URL de checkout. | Tenant + Admin |
| POST | `/api/billing/checkout/enterprise` | Crear una sesion de Stripe Checkout para el plan Enterprise. Devuelve una URL de checkout. | Tenant + Admin |
| GET | `/api/billing/status` | Devolver el plan actual, conteo de mensajes y limites de uso para el inquilino. | Tenant + Viewer |
| POST | `/api/billing/portal` | Crear una sesion del Portal de Cliente de Stripe para gestionar metodos de pago y facturas. | Tenant + Admin |
| POST | `/api/billing/agent-addon` | Comprar un complemento de espacio de agente adicional para el inquilino. | Tenant + Admin |
| POST | `/api/billing/webhook` | Manejador de webhook de Stripe. Valida la firma de Stripe y procesa eventos del ciclo de vida de suscripciones. | Stripe Signature |
| POST | `/api/billing/revenuecat-sync` | Verificar una compra in-app de iOS via RevenueCat y sincronizar derechos al inquilino. | Tenant + Admin |
| POST | `/api/billing/revenuecat-webhook` | Manejador de webhook de RevenueCat. Procesa eventos de suscripcion originados desde el App Store. | Bearer |

---

## Endpoints de Chat

Enviar y recibir mensajes, gestionar sesiones y consultar resultados de trabajos asincronos.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/chat/init` | Auto-provisionar un inquilino, agente y sesion para el usuario autenticado. Use esto para inicializar el entorno de chat de un nuevo usuario en una sola llamada. | JWT |
| POST | `/api/chat/send` | Enviar un mensaje al agente. El mensaje se procesa asincronamente; se devuelve un ID de trabajo inmediatamente. | Tenant + Admin |
| GET | `/api/chat/jobs/:jobId` | Consultar el estado y resultado de un trabajo de chat asincrono por su ID. | Tenant + Viewer |
| GET | `/api/chat/messages` | Obtener todos los mensajes para una sesion dada. Pase el ID de sesion como parametro de consulta. | Tenant + Viewer |
| GET | `/api/chat/sessions` | Listar todas las sesiones de chat del inquilino. | Tenant + Viewer |
| POST | `/api/chat/sessions` | Crear una nueva sesion de chat. | Tenant + Admin |

---

## Endpoints de Agentes y Actividad

Explorar agentes, sesiones, herramientas, archivos, skills, canales, trabajos programados y equipos asociados al inquilino.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | `/api/activity/agents` | Listar todos los agentes pertenecientes al inquilino. | Tenant |
| GET | `/api/activity/sessions` | Listar sesiones. Soporta filtrado por `agentId`, `status` y parametros de rango de fechas. | Tenant |
| GET | `/api/activity/sessions/:id/entries` | Obtener todas las entradas (mensajes y eventos) para una sesion especifica. | Tenant |
| GET | `/api/activity/tools` | Listar todas las herramientas disponibles para los agentes del inquilino. | Tenant |
| GET | `/api/activity/files` | Listar todos los archivos asociados con los agentes del inquilino. | Tenant |
| GET | `/api/activity/skills` | Listar todos los skills asociados con los agentes del inquilino. | Tenant |
| GET | `/api/activity/channels` | Listar todos los canales asociados con los agentes del inquilino. | Tenant |
| GET | `/api/activity/cron-jobs` | Listar todos los trabajos programados (cron) del inquilino. | Tenant |
| GET | `/api/activity/teams` | Listar todos los equipos dentro del inquilino. | Tenant |

---

## Endpoints de Skills

Gestionar el catalogo de skills, instalar y configurar skills, y publicar skills personalizados.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | `/api/skills/catalog` | Explorar el catalogo completo de skills. Devuelve todos los skills publicados disponibles para instalacion. | Tenant |
| GET | `/api/skills/list` | Listar los skills actualmente instalados por el usuario. | Tenant + Viewer |
| POST | `/api/skills/sync` | Sincronizar skills desde el sistema de archivos. Use esto despues de desplegar nuevos archivos de skills para actualizar el registro. | Tenant + Admin |
| POST | `/api/skills/register` | Registrar (instalar) un skill del catalogo. | Tenant + Viewer |
| DELETE | `/api/skills/register/:skillId` | Desregistrar (desinstalar) un skill por su ID. | Tenant + Viewer |
| POST | `/api/skills/:skillId/publish` | Publicar un skill para hacerlo disponible en el catalogo. | Tenant + Admin |
| POST | `/api/skills/:skillId/unpublish` | Despublicar un skill, eliminandolo del catalogo. | Tenant + Admin |
| GET | `/api/skills/all` | Listar todos los skills incluyendo los no publicados. Endpoint solo para admin para gestion de skills. | Tenant + Admin |
| PUT | `/api/skills/:skillId/env-schema` | Definir o actualizar el esquema de variables de entorno para un skill. Esto controla que campos de configuracion se presentan a los usuarios. | Tenant + Admin |
| POST | `/api/skills/:skillId/configure` | Guardar valores de configuracion para un skill instalado. | Tenant + Viewer |
| DELETE | `/api/skills/:skillId/configure` | Eliminar toda la configuracion de un skill, restableciendolo a valores predeterminados. | Tenant + Viewer |

---

## Endpoints de Canales

Vincular, configurar, habilitar y desconectar canales de mensajeria (por ejemplo, Slack, Discord, WhatsApp).

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | `/api/channels/` | Listar todos los canales y sus estados actuales. | Tenant + Viewer |
| GET | `/api/channels/:channel/status` | Obtener el estado detallado de un canal especifico. | Tenant + Viewer |
| POST | `/api/channels/:channel/link` | Iniciar el proceso de vinculacion para un canal. Devuelve una URL de vinculacion o token de sesion dependiendo del tipo de canal. | Tenant + Admin |
| GET | `/api/channels/:channel/link/wait` | Long-poll para la finalizacion de un flujo de vinculacion de canal. Devuelve una vez que el canal se vincula exitosamente o la operacion expira. | Tenant + Admin |
| GET | `/api/channels/:channel/jobs/:jobId` | Obtener el resultado de un trabajo asincrono especifico del canal. | Tenant + Admin |
| POST | `/api/channels/:channel/enable` | Habilitar un canal vinculado para que el agente comience a recibir mensajes de el. | Tenant + Admin |
| POST | `/api/channels/:channel/disable` | Deshabilitar un canal sin desvincularlo. El agente deja de recibir mensajes pero la conexion del canal se preserva. | Tenant + Admin |
| POST | `/api/channels/:channel/disconnect` | Desconectar y desvincular completamente un canal. | Tenant + Admin |
| GET | `/api/channels/:channel/config` | Obtener la configuracion actual de un canal. | Tenant + Admin |
| POST | `/api/channels/:channel/config` | Actualizar la configuracion de un canal. | Tenant + Admin |

---

## Endpoints de Google OAuth

Iniciar y gestionar flujos de Google OAuth para conectar servicios de Google a Neotask.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET/POST | `/oauth/google/start` | Iniciar un flujo de Google OAuth. Acepta parametros opcionales para especificar a que servicios de Google solicitar acceso. | Opcional |
| GET | `/oauth/google/services` | Listar todas las definiciones de servicios de Google soportados por Neotask, agrupados por categoria. | Ninguna |
| GET | `/oauth/google/callback` | Manejador de callback OAuth. Google redirige aqui despues de que el usuario otorga o deniega acceso. | Ninguna |
| GET | `/oauth/google/status` | Consultar el estado de un flujo OAuth en progreso. Devuelve si el flujo esta pendiente, completado o fallido. | Ninguna |

### Servicios de Google Disponibles

Neotask soporta la conexion a 25 servicios de Google, organizados por categoria:

| Categoria | Servicios |
|----------|----------|
| **Core** | Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks |
| **Comunicacion** | People/Contacts, Chat, Meet, YouTube, Photos |
| **Ubicacion** | Places API, Routes/Directions, Business Profile |
| **Especializados** | Classroom, Play Developer, AdSense, Google Ads |

---

## Endpoints de Claves de Proveedor

Gestionar claves API de terceros (por ejemplo, para proveedores de LLM). Las claves se cifran en reposo y pueden resolverse (descifrarse) bajo demanda.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| PUT | `/api/provider-keys/:provider` | Guardar o actualizar una clave API para el proveedor especificado. La clave se cifra antes del almacenamiento. | HMAC + Auth |
| GET | `/api/provider-keys/` | Listar todas las claves de proveedor guardadas. Los valores de las claves estan enmascarados (solo se muestran los ultimos cuatro caracteres). | Auth |
| DELETE | `/api/provider-keys/:provider` | Eliminar una clave API guardada para el proveedor especificado. | HMAC + Auth |
| GET | `/api/provider-keys/:provider/resolve` | Descifrar y devolver la clave API completa para el proveedor especificado. | Auth |
| GET | `/api/provider-keys/mode` | Obtener el modo de clave actual (proporcionada por el usuario vs. creditos de plataforma) y el saldo de creditos restante. | Auth |

### Proveedores Permitidos

El parametro de ruta `:provider` debe ser uno de los siguientes valores:

- `anthropic`
- `openai`
- `openai-codex`
- `openrouter`
- `google-ai`

---

## Endpoints de Uso

Rastrear uso, consultar analiticas, monitorear gastos y gestionar presupuestos.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/usage/ingest` | Ingerir un registro de datos de uso (por ejemplo, conteos de tokens, modelo utilizado). | Auth |
| GET | `/api/usage/query` | Consultar analiticas de uso con filtros flexibles (rango de fechas, modelo, agente). | Auth |
| GET | `/api/usage/summary` | Obtener un resumen de uso para un periodo dado. Pase `period` como parametro de consulta (por ejemplo, `day`, `week`, `month`). | Auth |
| GET | `/api/usage/analytics` | Recuperar analiticas de uso detalladas incluyendo desgloses por modelo y agente. | Auth |
| GET | `/api/usage/spending` | Obtener datos de gasto para un periodo dado. Pase `period` como parametro de consulta. | Auth |
| GET | `/api/usage/budget` | Obtener informacion de presupuesto incluyendo el limite total, monto utilizado y monto restante. | Auth |
| POST | `/api/usage/cron-runs` | Registrar la ejecucion de un trabajo programado (cron) para seguimiento de uso. | Auth |
| POST | `/api/usage/budget-snapshot` | Capturar una instantanea puntual del estado actual del presupuesto. | Auth |

---

## Endpoints de Onboarding

Guiar a nuevos usuarios a traves de la configuracion inicial, incluyendo la seleccion de un proveedor de modelos y la configuracion de una clave API.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/onboarding/init` | Inicializar la configuracion de onboarding para el usuario autenticado. Crea ajustes predeterminados y devuelve el estado de onboarding. | JWT |
| GET | `/api/onboarding/models` | Listar proveedores de modelos disponibles y sus modelos soportados. Este endpoint es publico y no requiere autenticacion. | Ninguna |
| POST | `/api/onboarding/setup` | Configurar una clave API de proveedor durante el onboarding. Valida la clave antes de guardar. | Tenant + Admin |
| POST | `/api/onboarding/complete` | Marcar el onboarding como completo para el usuario actual. | Dashboard Auth |

---

## Endpoints de Inquilinos

Crear y gestionar inquilinos (espacios de trabajo), almacenar secretos cifrados y crear sesiones y trabajos directamente.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/tenants/` | Crear un nuevo inquilino (espacio de trabajo). Devuelve el ID del inquilino y ajustes predeterminados. | JWT |
| GET | `/api/tenants/:tenantId` | Obtener detalles para un inquilino especifico, incluyendo ajustes y conteo de miembros. | JWT |
| POST | `/api/tenants/secrets` | Almacenar un secreto cifrado asociado con el inquilino. Usado para integraciones de servicios. | Tenant + Admin |
| POST | `/api/tenants/sessions` | Crear una nueva sesion dentro del inquilino. | Tenant + Admin |
| POST | `/api/tenants/jobs` | Crear un nuevo trabajo asincrono dentro del inquilino. | Tenant + Admin |

---

## Endpoints de Memoria

Gestionar configuracion de memoria del agente, archivos y contenido. La memoria permite a los agentes persistir informacion entre sesiones.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | `/api/memory/config` | Obtener la configuracion actual de memoria (estado habilitado, politica de retencion, limites). | Auth |
| POST | `/api/memory/config` | Actualizar ajustes de memoria como periodo de retencion y limites de almacenamiento. | Auth |
| GET | `/api/memory/files` | Listar todos los archivos de memoria almacenados para el agente. | Auth |
| GET | `/api/memory/files/:filename` | Recuperar el contenido de un archivo de memoria especifico por nombre de archivo. | Auth |
| DELETE | `/api/memory/files/:filename` | Eliminar un archivo de memoria especifico por nombre de archivo. | Auth |
| GET | `/api/memory/content` | Recuperar contenido de memoria almacenado. | Auth |
| POST | `/api/memory/content` | Almacenar nuevo contenido de memoria para el agente. | Auth |

---

## Endpoints de Cuentas de Google

Gestionar cuentas de Google que han sido conectadas a Neotask via OAuth.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | `/api/google-accounts/` | Listar todas las cuentas de Google conectadas con sus alcances de servicio y estado. | Auth |
| POST | `/api/google-accounts/:accountId/activate` | Activar una cuenta de Google conectada, habilitando al agente para usar sus servicios autorizados. | Auth |
| DELETE | `/api/google-accounts/:accountId` | Eliminar una cuenta de Google conectada y revocar sus tokens almacenados. | Auth |

---

## Endpoints de Contacto y Soporte

Enviar y gestionar solicitudes de contacto de soporte.

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| POST | `/api/contact/` | Enviar un mensaje del formulario de contacto. Limitado a 5 solicitudes por 15 minutos por direccion IP. | Ninguna |
| GET | `/api/contacts/` | Listar todos los envios de contacto con soporte de paginacion. Solo admin. | Admin |
| PATCH | `/api/contacts/:id` | Actualizar el estado de un envio de contacto (por ejemplo, marcar como resuelto). | Admin |
| DELETE | `/api/contacts/:id` | Eliminar un envio de contacto. | Admin |

---

## Limites de Tasa

Neotask aplica limites de tasa en ciertos endpoints para proteger la estabilidad del servicio. Cuando se excede un limite de tasa, la API devuelve una respuesta `429 Too Many Requests`.

| Categoria de Endpoint | Limite |
|-------------------|-------|
| Formulario de contacto | 5 solicitudes por 15 minutos por IP |
| Intentos de inicio de sesion | 10 solicitudes por 15 minutos por IP |
| Seguimiento/analitica | 30 solicitudes por 60 segundos por IP |

---

## Respuestas de Error

Todas las respuestas de error siguen un formato JSON consistente:

```json
{
  "error": "Descripcion del mensaje de error",
  "status": 400
}
```

### Codigos de Estado

| Codigo | Significado |
|------|---------|
| 400 | **Solicitud Incorrecta** -- La solicitud estaba mal formada o contenia parametros invalidos. |
| 401 | **No Autorizado** -- Falta la autenticacion o el token proporcionado es invalido. |
| 402 | **Pago Requerido** -- Los creditos del inquilino se han agotado. Actualice su plan o agregue creditos para continuar. |
| 403 | **Prohibido** -- El usuario autenticado no tiene permisos suficientes para esta accion. |
| 404 | **No Encontrado** -- El recurso solicitado no existe. |
| 429 | **Limite de Tasa Excedido** -- Demasiadas solicitudes. Espere y reintente despues del periodo indicado en los encabezados de respuesta. |
| 500 | **Error Interno del Servidor** -- Ocurrio un error inesperado en el servidor. Si persiste, contacte al soporte de Neotask. |