Initial commit: Horux Strategy Platform
- Laravel 11 backend with API REST - React 18 + TypeScript + Vite frontend - Multi-parser architecture for accounting systems (CONTPAQi, Aspel, SAP) - 27+ financial metrics calculation - PDF report generation with Browsershot - Complete documentation (10 documents) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
322
docs/04-api-reference.md
Normal file
322
docs/04-api-reference.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# 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:**
|
||||
```json
|
||||
{
|
||||
"email": "admin@horux360.com",
|
||||
"password": "password"
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"message": "Sesión cerrada exitosamente"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /user
|
||||
Obtener usuario actual
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
[
|
||||
{ "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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"sistema_origen": "contpaqi",
|
||||
"status": "procesando"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /balanzas/{id}/cuentas
|
||||
Listar cuentas de una balanza
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"exclusiones": [5, 12, 23]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpoints de Cuentas
|
||||
|
||||
### PUT /cuentas/{id}/clasificacion
|
||||
Corregir clasificación de cuenta
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"nombre": "Reporte Anual 2024",
|
||||
"balanza_ids": [1, 2, 3]
|
||||
}
|
||||
```
|
||||
|
||||
**Response 201:**
|
||||
```json
|
||||
{
|
||||
"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:**
|
||||
```json
|
||||
{
|
||||
"message": "The email field is required.",
|
||||
"errors": {
|
||||
"email": ["The email field is required."]
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user