API REST

ERP DLM expone una API REST completa bajo el prefijo /api. La referencia interactiva está disponible en Swagger: https://erp.ovlicuo.com/api/docs.

Autenticación

JWT de usuario

La mayoría de endpoints requieren un token JWT obtenido tras login:

curl -X POST https://erp.ovlicuo.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@erpdlm.com","password":"admin"}'

Respuesta:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 1800
}

Usa el token en cada petición:

curl https://erp.ovlicuo.com/api/agents \
  -H "Authorization: Bearer eyJ..."

Tokens de API (api_tokens)

Para integraciones externas o el servidor MCP se pueden crear tokens de API con ámbitos:

• api_tokens.key_hash almacena el hash SHA-256 del token.
• api_tokens.company_id restringe el token a una empresa en entornos multi-tenant.
• api_access.resource_name define el ámbito (api_access, mcp, mcp:invoices, etc.).

El token se envía igualmente como Authorization: Bearer <token>.

Convenciones de rutas

• Todos los endpoints empiezan por /api.
• Los módulos auto-descubiertos se montan en /api/{nombre-con-guiones}.
• Nunca incluyas /api dos veces; las rutas internas del APIRouter usan prefix="".

Módulo	Prefijo real
sales	/api/sales
purchases	/api/purchases
accounting	/api/accounting
treasury	/api/treasury
clients	/api/clients
products	/api/products
bank_reconciliation	/api/bank-reconciliation (registro manual)

Ejemplos de endpoints

Ventas (/api/sales)

Método	Ruta	Descripción
GET	/api/sales/estimates	Listar presupuestos
POST	/api/sales/estimates	Crear presupuesto
PATCH	/api/sales/estimates/{id}	Actualizar presupuesto
POST	/api/sales/estimates/{id}/convert-to-order	Convertir a pedido
GET	/api/sales/orders	Listar pedidos
GET	/api/sales/delivery-notes	Listar albaranes
GET	/api/sales/invoices	Listar facturas de venta
POST	/api/sales/invoices	Crear factura de venta
POST	/api/sales/invoices/{id}/generate-accounting-entry	Generar asiento contable
GET	/api/sales/invoices/{id}/pdf	Descargar PDF
GET	/api/sales/reports/modelo-347	Modelo 347 (ventas)

Compras (/api/purchases)

Método	Ruta	Descripción
GET	/api/purchases/estimates	Listar presupuestos de compra
POST	/api/purchases/orders	Crear pedido de compra
GET	/api/purchases/delivery-notes	Listar albaranes de compra
GET	/api/purchases/invoices	Listar facturas de compra
POST	/api/purchases/invoices/{id}/approve	Aprobar factura de compra
POST	/api/purchases/invoices/{id}/reject	Rechazar factura de compra

Contabilidad (/api/accounting)

Método	Ruta	Descripción
GET	/api/accounting/fiscal-years	Ejercicios fiscales
GET	/api/accounting/journals	Diarios contables
GET	/api/accounting/accounts	Plan contable
GET	/api/accounting/subaccounts	Subcuentas
GET	/api/accounting/entries	Asientos contables
POST	/api/accounting/entries	Crear asiento
GET	/api/accounting/entries/{id}	Detalle de asiento

Tesorería (/api/treasury)

Método	Ruta	Descripción
GET	/api/treasury/customer-receipts	Recibos de clientes
POST	/api/treasury/customer-receipts	Crear recibo
GET	/api/treasury/supplier-payments	Pagos a proveedores
GET	/api/treasury/budgets	Presupuestos de tesorería

Paginación y filtros

La mayoría de listados devuelven un objeto con la forma:

{
  "data": [...],
  "total": 142,
  "skip": 0,
  "limit": 50
}

Parámetros comunes:

Parámetro	Tipo	Descripción
skip	integer	Offset (por defecto 0)
limit	integer	Tamaño de página (por defecto 50, máximo 10000)
search	string	Búsqueda textual
include_inactive	boolean	Incluir registros inactivos

Ejemplo:

curl "https://erp.ovlicuo.com/api/agents?search=pedro&limit=10&skip=0" \
  -H "Authorization: Bearer eyJ..."

CORS y entornos

El backend permite orígenes configurados en backend/app/core/config.py:

CORS_ORIGINS = [
    "http://localhost:5173",
    "http://localhost:42210",
    "https://erp.ovlicuo.com",
]

Para producción añade tu dominio en el .env correspondiente.

Multi-tenant

En entornos SaaS, envía siempre el Host correcto (p. ej. acme-sl.erp.ovlicuo.com). El backend enruta la petición a la base de datos del tenant; un token con company_id restringe además los resultados a una empresa dentro de esa BD.