Niveles de modelos

ClickBalance ERP tiene 1,278 modelos en total. La construcción del API es incremental — habilitar todos a la vez es imposible (cada modelo tiene callbacks, validaciones y reglas que necesitan ser auditadas). Por eso los modelos se agrupan en niveles según complejidad técnica.

Resumen

Total expuesto hoy: 1,078 (84%).

Nivel 1 — Catálogos globales

Modelos sin campo empresa, sin callbacks, CRUD plano. Son la base del sistema: monedas, países, tipos de cliente, regímenes fiscales, unidades de medida, etc.

• Lectura: lista completa, paginada, sin filtros multi-tenant.
• Escritura: típicamente requiere permisos de superadmin — modificar un catálogo global afecta a TODAS las empresas.
• Ejemplos: Moneda, Pais, Estado, RegimenFiscal, UnidadMedida, FormaPagoSat, MetodoPagoSat, UsoCfdiSat.

curl http://localhost/api/v1/Moneda \
  -H "Authorization: Bearer $TOKEN"

Nivel 2 — Catálogos con relaciones

Igual que Nivel 1 pero con foreign keys. Cada FK aparece dos veces en la respuesta:

• <fk> — el ID numérico (lo que mandás al crear/actualizar).
• <fk>_str — la representación humana (lo que mostrás en la UI).

Por defecto el API resuelve y devuelve _str. Para alta concurrencia o listados grandes, usa ?lean=true para evitar el costo del JOIN.

curl "http://localhost/api/v1/RegimenFiscal?lean=true" \
  -H "Authorization: Bearer $TOKEN"

Nivel 3 — Multi-tenant

El grueso del ERP. Todo lo que tiene una columna empresa: facturas, compras, ventas, asientos contables, productos, etc.

• Filtro automático por la empresa del token.
• Creación: el campo empresa se asigna del token; el cliente NO lo manda.
• Eliminación: verifica dependencias antes de borrar; si hay registros que referencian este, retorna 409 con el detalle.
• Ejemplos: Compra, Venta, Cliente, Proveedor, Producto, Poliza, MovimientoBancario.

curl http://localhost/api/v1/Compra \
  -H "Authorization: Bearer $TOKEN"

Nivel 4 — Con callbacks

Modelos cuya lógica de negocio vive en callbacks (PHP) o que requieren side effects más allá del CRUD: timbrado de CFDI, generación de pólizas, recálculo de saldos, etc.

Hoy SOLO están habilitados:

• Asociado — empleados internos.
• FormaPago — formas de pago por empresa.

El resto está en el roadmap. La habilitación requiere auditar cada callback para confirmar que no rompe consistencia y que la API expone los efectos secundarios de manera explícita.

Cómo saber qué hay disponible

GET /api/v1/metadata (sin token) lista todos los modelos habilitados:

curl http://localhost/api/v1/metadata

Y para inspeccionar uno en particular (columnas, tipos, relaciones):

curl http://localhost/api/v1/metadata/moneda