API-first, integraciones con token y lecturas separadas desde el inicio

1. Separar reportes desde el INICIO (ya implementado a nivel de código)

Lo pediste desde el día 1 — hecho, sin pagar una réplica todavía:

• Las lecturas (inventario, ventas, reportes, Flai) pasan por dbRead(); las escrituras por db().
• Hoy dbRead() usa la misma BD. Cuando agregues la réplica, defines DATABASE_URL_READ y toda la lectura se va a la réplica — sin tocar el código.
• Así, desde el inicio, un reporte pesado no compite con la transacción; y nunca habrá refactor para escalar.

2. API-first: todo el ERP es API

Cada capacidad vive detrás de /api/v1 (la UI consume la misma API que un tercero). Hoy: health, inventario, ventas (con paginación). Plan: productos, clientes, guias, reparto, cobranzas, reportes.

3. Integración por token — SOLO suscriptores cerrados

• Token por tenant (Authorization: Bearer <api_key>) — el que ya usamos.
• Solo suscriptores activos tienen key: se genera/activa al contratar y se revoca al suspender (estado del tenant en el panel admin).
• Scopes por key: read / write / por módulo (ej. un ERP externo solo lee inventario).
• Rate-limit por tenant (con Redis) → protege la plataforma y permite cobrar por volumen.
• Auditoría: cada llamada por API queda registrada (quién/qué/cuándo).
• HTTPS obligatorio.

4. Integraciones en ambos sentidos

• Entrante (REST): terceros crean/leen datos con su token (ventas, stock, clientes).
• Saliente (Webhooks): ConTodo notifica eventos (venta.creada, pago.conciliado, entrega.realizada) a la URL del cliente → se integran a su ERP/CRM/e-commerce.
• Marketplace de integraciones (a futuro): Shopify, WooCommerce, bancos, WhatsApp, HubSpot — conectores sobre la misma API. (ver propuesta técnica.)

5. Gestión de tokens (panel)

• El admin del tenant ve/crea/revoca sus tokens (con nombre y scope).
• El super-admin ve el uso por tenant (llamadas, rate-limit, estado) — junto al consumo de IA. Ver [[26-despliegue-costos-admin]] y [[25-flai-consumo-whatsapp]].

6. Seguridad de la API

• Keys largas, revocables, con scope mínimo.
• Rate-limit + cuotas por plan (Redis).
• Aislamiento por tenant_id en cada consulta (un token nunca ve datos de otra empresa).
• Todo por HTTPS; auditoría de cada request.

Estado: token por tenant ✅ (Bearer). Pendiente: scopes, rate-limit (Redis), webhooks salientes, panel de tokens. Relacionado: [[31-infra-ops-roadmap]] · [[20-roadmap-backend]] · [[27-arquitectura-datos-dashboards]].