horux-strategy-platform/docs/04-api-reference.md

4. API Reference

Base URL

http://localhost:8000/api

Autenticación

Todos los endpoints (excepto login) requieren token Bearer:

Authorization: Bearer {token}

---

Endpoints de Autenticación

POST /login

Iniciar sesión

Request:

{
  "email": "admin@horux360.com",
  "password": "password"
}

Response 200:

{
  "user": {
    "id": 1,
    "nombre": "Administrador",
    "email": "admin@horux360.com",
    "role": "admin",
    "cliente_id": null
  },
  "token": "1|abc123..."
}

POST /logout

Cerrar sesión (requiere autenticación)

Response 200:

{
  "message": "Sesión cerrada exitosamente"
}

GET /user

Obtener usuario actual

Response 200:

{
  "id": 1,
  "nombre": "Administrador",
  "email": "admin@horux360.com",
  "role": "admin",
  "cliente_id": null,
  "cliente": null
}

---

Endpoints de Giros

GET /giros

Listar giros activos

Response 200:

[
  { "id": 1, "nombre": "Hotelería", "activo": true },
  { "id": 2, "nombre": "Comercio", "activo": true }
]

---

Endpoints de Clientes

GET /clientes

Listar clientes (filtrado por rol)

Response 200:

[
  {
    "id": 1,
    "nombre_empresa": "Hotel Boutique HSA",
    "logo": "logos/abc123.png",
    "giro_id": 1,
    "moneda": "MXN",
    "giro": { "id": 1, "nombre": "Hotelería" }
  }
]

POST /clientes

Crear cliente (multipart/form-data)

Request:

nombre_empresa: Hotel Ejemplo
giro_id: 1
moneda: MXN
logo: [archivo imagen]

Response 201:

{
  "id": 2,
  "nombre_empresa": "Hotel Ejemplo",
  "giro_id": 1,
  "moneda": "MXN",
  "logo": "logos/xyz789.png"
}

GET /clientes/{id}

Obtener cliente con balanzas y reportes

PUT /clientes/{id}

Actualizar cliente

DELETE /clientes/{id}

Eliminar cliente (solo admin)

---

Endpoints de Balanzas

GET /clientes/{id}/balanzas

Listar balanzas de un cliente

Response 200:

[
  {
    "id": 1,
    "cliente_id": 1,
    "periodo_inicio": "2024-01-01",
    "periodo_fin": "2024-12-31",
    "sistema_origen": "contpaqi",
    "status": "completado"
  }
]

POST /clientes/{id}/balanzas

Subir balanza (multipart/form-data)

Request:

archivo: [archivo PDF/Excel/CSV]
periodo_inicio: 2024-01-01
periodo_fin: 2024-12-31

Response 201:

{
  "id": 2,
  "sistema_origen": "contpaqi",
  "status": "procesando"
}

GET /balanzas/{id}/cuentas

Listar cuentas de una balanza

Response 200:

[
  {
    "id": 1,
    "codigo": "001-100-000",
    "nombre": "ACTIVO CIRCULANTE",
    "nivel": 1,
    "saldo_final_deudor": 1500000.00,
    "saldo_final_acreedor": 0,
    "excluida": false,
    "es_cuenta_padre": true,
    "requiere_revision": false,
    "categoria_contable": {
      "id": 1,
      "nombre": "Activos Circulantes"
    }
  }
]

PUT /balanzas/{id}/exclusiones

Actualizar cuentas excluidas

Request:

{
  "exclusiones": [5, 12, 23]
}

---

Endpoints de Cuentas

PUT /cuentas/{id}/clasificacion

Corregir clasificación de cuenta

Request:

{
  "reporte_contable_id": 1,
  "categoria_contable_id": 3,
  "requiere_revision": false
}

POST /cuentas/{id}/toggle-exclusion

Alternar exclusión de cuenta

GET /anomalias

Listar cuentas que requieren revisión

---

Endpoints de Reportes

GET /clientes/{id}/reportes

Listar reportes de un cliente

POST /clientes/{id}/reportes

Generar nuevo reporte

Request:

{
  "nombre": "Reporte Anual 2024",
  "balanza_ids": [1, 2, 3]
}

Response 201:

{
  "id": 1,
  "nombre": "Reporte Anual 2024",
  "periodo_tipo": "anual",
  "status": "completado",
  "data_calculada": { ... }
}

GET /reportes/{id}

Obtener reporte con datos calculados

GET /reportes/{id}/pdf

Descargar PDF del reporte

Response: Archivo PDF

DELETE /reportes/{id}

Eliminar reporte

---

Endpoints de Administración

Requieren rol admin.

Usuarios

• GET /admin/usuarios - Listar usuarios
• POST /admin/usuarios - Crear usuario
• PUT /admin/usuarios/{id} - Actualizar usuario
• DELETE /admin/usuarios/{id} - Eliminar usuario

Giros

• GET /admin/giros - Listar todos los giros
• POST /admin/giros - Crear giro
• PUT /admin/giros/{id} - Actualizar giro
• DELETE /admin/giros/{id} - Eliminar giro

Umbrales

• GET /admin/umbrales - Listar umbrales
• POST /admin/umbrales - Crear umbral
• PUT /admin/umbrales/{id} - Actualizar umbral
• DELETE /admin/umbrales/{id} - Eliminar umbral

Reglas de Mapeo

• GET /admin/reglas-mapeo - Listar reglas
• POST /admin/reglas-mapeo - Crear regla
• PUT /admin/reglas-mapeo/{id} - Actualizar regla
• DELETE /admin/reglas-mapeo/{id} - Eliminar regla

---

Códigos de Error

Código	Descripción
401	No autenticado
403	No autorizado
404	Recurso no encontrado
422	Error de validación
500	Error del servidor

Ejemplo error 422:

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}