# API Reference - Horux360 **Base URL:** `https://horuxfin.com/api` --- ## Autenticación Todos los endpoints (excepto auth) requieren header: ``` Authorization: Bearer ``` ### Rate Limits (por IP) | Endpoint | Límite | Ventana | |----------|--------|---------| | `POST /auth/login` | 10 requests | 15 minutos | | `POST /auth/register` | 3 requests | 1 hora | | `POST /auth/refresh` | 20 requests | 15 minutos | | General `/api/*` | 30 requests/s | burst 50 | --- ## Auth (`/api/auth`) ### `POST /auth/register` Registra nueva empresa y usuario admin. Provisiona base de datos dedicada. **Body:** ```json { "empresa": { "nombre": "Mi Empresa", "rfc": "ABC123456789" }, "usuario": { "nombre": "Juan", "email": "juan@empresa.com", "password": "min8chars" } } ``` **Response:** `{ accessToken, refreshToken, user: UserInfo }` ### `POST /auth/login` ```json { "email": "usuario@empresa.com", "password": "..." } ``` **Response:** `{ accessToken, refreshToken, user: UserInfo }` ### `POST /auth/refresh` ```json { "refreshToken": "..." } ``` **Response:** `{ accessToken, refreshToken }` ### `POST /auth/logout` *(requiere auth)* ```json { "refreshToken": "..." } ``` ### `GET /auth/me` *(requiere auth)* **Response:** `UserInfo` --- ## Dashboard (`/api/dashboard`) ### `GET /dashboard/kpis?año=2026&mes=3` KPIs principales: ingresos, egresos, utilidad, margen, IVA balance, conteo de CFDIs. ### `GET /dashboard/ingresos-egresos?año=2026` Datos mensuales de ingresos/egresos para gráfica anual. ### `GET /dashboard/resumen-fiscal?año=2026&mes=3` IVA por pagar, IVA a favor, ISR, declaraciones pendientes, próxima obligación. ### `GET /dashboard/alertas?limit=5` Alertas activas no resueltas, ordenadas por prioridad. --- ## CFDI (`/api/cfdi`) ### `GET /cfdi?page=1&limit=20&tipo=ingreso&search=...` Lista paginada de CFDIs con filtros. ### `GET /cfdi/resumen` Resumen de conteo por tipo y estado. ### `GET /cfdi/emisores` Lista de emisores únicos. ### `GET /cfdi/receptores` Lista de receptores únicos. ### `GET /cfdi/:id` Detalle de un CFDI. ### `GET /cfdi/:id/xml` XML original del CFDI. ### `POST /cfdi` Crear un CFDI individual. Sujeto a límite de plan. ### `POST /cfdi/bulk` Carga masiva de CFDIs. Body limit: 50MB. Sujeto a límite de plan. ### `DELETE /cfdi/:id` Eliminar un CFDI. --- ## Impuestos (`/api/impuestos`) ### `GET /impuestos/iva?año=2026` Datos mensuales de IVA (trasladado, acreditable, resultado, acumulado). --- ## Alertas (`/api/alertas`) ### `GET /alertas` ### `POST /alertas` ### `PUT /alertas/:id` ### `DELETE /alertas/:id` ### `PATCH /alertas/:id/read` ### `PATCH /alertas/:id/resolve` --- ## Calendario (`/api/calendario`) ### `GET /calendario?año=2026&mes=3` ### `POST /calendario` ### `PUT /calendario/:id` ### `DELETE /calendario/:id` --- ## Reportes (`/api/reportes`) ### `GET /reportes/flujo-efectivo?año=2026` ### `GET /reportes/impuestos?año=2026` ### `GET /reportes/forecasting?año=2026` ### `GET /reportes/concentrado?año=2026` --- ## Export (`/api/export`) ### `GET /export/cfdis?format=excel&tipo=ingreso` Exporta CFDIs a Excel o CSV. --- ## FIEL (`/api/fiel`) ### `POST /fiel/upload` ```json { "cerFile": "", "keyFile": "", "password": "..." } ``` - Archivos max 50KB cada uno - Password max 256 caracteres ### `GET /fiel/status` Estado actual de la FIEL configurada. ### `DELETE /fiel` Eliminar credenciales FIEL. --- ## SAT Sync (`/api/sat`) ### `POST /sat/sync` Iniciar sincronización manual. ```json { "type": "daily", "dateFrom": "2026-01-01", "dateTo": "2026-01-31" } ``` ### `GET /sat/sync/status` Estado actual de sincronización. ### `GET /sat/sync/history?page=1&limit=10` Historial de sincronizaciones. ### `GET /sat/sync/:id` Detalle de un job de sincronización. ### `POST /sat/sync/:id/retry` Reintentar un job fallido. ### `GET /sat/cron` *(admin global)* Info del job programado. ### `POST /sat/cron/run` *(admin global)* Ejecutar sincronización global manualmente. --- ## Usuarios (`/api/usuarios`) ### `GET /usuarios` Usuarios del tenant actual. ### `GET /usuarios/all` *(admin global)* Todos los usuarios de todas las empresas. ### `POST /usuarios` Invitar usuario (genera password temporal con `crypto.randomBytes`). ```json { "email": "nuevo@empresa.com", "nombre": "María", "role": "contador" } ``` ### `PUT /usuarios/:id` Actualizar usuario (nombre, role, active). ### `DELETE /usuarios/:id` ### `PUT /usuarios/:id/global` *(admin global)* Actualizar usuario de cualquier empresa. ### `DELETE /usuarios/:id/global` *(admin global)* --- ## Tenants / Clientes (`/api/tenants`) *(admin global)* ### `GET /tenants` Lista de todos los tenants/clientes. ### `POST /tenants` Crear nuevo tenant. Provisiona base de datos. Envía email al admin. ```json { "nombre": "Empresa Nueva", "rfc": "ENE123456789", "plan": "business", "adminNombre": "Pedro", "adminEmail": "pedro@nueva.com" } ``` ### `PUT /tenants/:id` Actualizar tenant (plan, limits, active). ### `DELETE /tenants/:id` Soft delete — renombra la base de datos a `*_deleted_*`. --- ## Suscripciones (`/api/subscriptions`) *(admin global)* ### `GET /subscriptions/:tenantId` Suscripción activa del tenant. ### `POST /subscriptions/:tenantId/generate-link` Generar link de pago MercadoPago. ### `POST /subscriptions/:tenantId/mark-paid` Marcar como pagado manualmente. ```json { "amount": 999 } ``` ### `GET /subscriptions/:tenantId/payments` Historial de pagos. --- ## Webhooks (`/api/webhooks`) ### `POST /webhooks/mercadopago` Webhook de MercadoPago. Requiere headers: - `x-signature`: Firma HMAC-SHA256 - `x-request-id`: ID del request --- ## Roles y Permisos | Rol | Descripción | Acceso | |-----|-------------|--------| | `admin` | Administrador del tenant | Todo dentro de su tenant + invitar usuarios | | `contador` | Contador | CFDI, impuestos, reportes, dashboard | | `visor` | Solo lectura | Dashboard, CFDI (solo ver), reportes | ### Admin Global El admin del tenant con RFC `CAS2408138W2` tiene acceso adicional: - Gestión de todos los tenants - Suscripciones - SAT cron - Impersonación via `X-View-Tenant` header - Bypass de plan limits al impersonar --- ## Tipos Compartidos (`@horux/shared`) ### UserInfo ```typescript interface UserInfo { id: string; email: string; nombre: string; role: 'admin' | 'contador' | 'visor'; tenantId: string; tenantName: string; tenantRfc: string; plan: string; } ``` ### JWTPayload ```typescript interface JWTPayload { userId: string; email: string; role: Role; tenantId: string; iat?: number; exp?: number; } ```