Saltar a contenido

API Platform

Estado: VERDE DOCUMENTAL
Scope: global
tenant_id: global
Owner: OpenClaw Platform Governance
Fuente de verdad: docs/architecture/API-PLATFORM.md

Objetivo

Definir la API Platform multi-tenant oficial de la future platform para exponer datos y capacidades de forma controlada, auditable y aislada por tenant, sin implementar todavia endpoints reales, gateways productivos ni publicacion de datos.

Esta etapa crea contrato, arquitectura, reglas, seguridad, roadmap y casos de uso. Al 2026-06-02 ya existe un PostgREST sandbox interno y privado para validar RLS, REST y OpenAPI sobre datos ficticios, pero no existe publicacion productiva, Kong ni endpoints productivos.

Que problema resuelve

La plataforma ya tiene una Multi-Tenant Foundation y una Data Foundation documentadas, pero todavia faltaba la capa que define como esos datos futuros podran exponerse sin mezclar empresas ni abrir superficies inseguras.

La API Platform resuelve:

  • contrato oficial para APIs global, tenant, internas y externas
  • reglas de aislamiento para no devolver datos de otro tenant
  • arquitectura inicial recomendada para publicar APIs sin exponer la base
  • modelo futuro de autenticacion, permisos, auditoria y OpenAPI
  • catalogo inicial de APIs futuras para negocio, agentes y terceros

Que no resuelve todavia

Esta etapa no resuelve todavia:

  • publicacion real de PostgREST
  • provision de PostgreSQL
  • publicacion de endpoints productivos
  • instalacion de Kong u otro API Gateway
  • instalacion productiva de Scalar sobre APIs reales
  • entrega de tokens, API keys o credenciales reales
  • integraciones runtime con terceros

Relacion con la arquitectura vigente

  • la infraestructura actual sigue cerrada y operativa
  • Nginx Proxy Manager sigue siendo la unica puerta aprobada de publicacion
  • la API Platform queda congelada como capa documental futura
  • ninguna API real puede exponerse antes de abrir una etapa runtime posterior

Relacion con otras foundations

Relacion con Multi-Tenant Foundation

La Multi-Tenant Foundation define el contrato base de alcance, ownership y aislamiento. La API Platform hereda esas reglas y las vuelve obligatorias en todo endpoint, token, permiso y respuesta.

Reglas heredadas clave:

  • toda API debe declarar scope
  • toda API scope=tenant debe declarar tenant_id
  • ningun tenant puede acceder a datos de otro tenant
  • todo activo debe tener owner y fuente de verdad

Documento rector relacionado:

Relacion con Data Foundation

La Data Foundation define la forma oficial de estructurar datos futuros con tenant_id, source_system, trazabilidad y preparacion para RLS.

La API Platform no inventa modelos paralelos. Debe consumir y exponer la Data Foundation respetando:

  • tenant_id obligatorio
  • separacion de datos globales y por tenant
  • auditoria de lectura y escritura
  • preparacion para PostgREST y OpenAPI

Documento rector relacionado:

Relacion con consumidores

Grafana

Grafana podra consumir APIs solo cuando exista una necesidad real y justificada. La via preferida para dashboards de negocio sigue siendo la Data Foundation o vistas aprobadas, no APIs improvisadas para reemplazar consultas analiticas.

Casos validos futuros:

  • dashboards de negocio con endpoints especializados
  • consumo controlado de estado operativo de APIs
  • vistas globales autorizadas con filtros y auditoria

OpenClaw

OpenClaw podra actuar como consumidor y productor interno de APIs futuras.

Casos validos futuros:

  • consultar pedidos, stock, ventas o alertas del tenant correcto
  • disparar workflows internos auditables
  • consumir APIs globales autorizadas para catalogos o estado de plataforma

Regla:

  • ningun workflow o agente de un tenant puede consumir datos de otro tenant

Agentes

Los agentes futuros podran usar APIs internas o externas gobernadas, pero siempre con permisos minimos, tenant_id explicito cuando aplique y trazabilidad de requests.

Terceros

Terceros autorizados podran consumir APIs externas futuras solo bajo contrato, autenticacion, permisos, rate limiting futuro y documentacion OpenAPI.

Tipos oficiales de API

API global

Una API global pertenece a la plataforma compartida.

Ejemplos futuros:

  • estado general de la plataforma
  • catalogo de tenants autorizados
  • health o status de componentes expuestos oficialmente

Reglas:

  • no puede devolver datos funcionales de tenants sin filtro y permiso formal
  • puede operar sobre metadata global
  • todo acceso cross-tenant debe quedar justificado y auditado

API por tenant

Una API por tenant expone datos o acciones propias de una sola empresa.

Ejemplos futuros:

  • clientes de ladirecta
  • ventas de alpuntodeventa
  • pedidos, stock o productos de un tenant especifico

Reglas:

  • siempre debe operar con tenant_id
  • no puede devolver datos de otro tenant
  • el path visible no reemplaza el control real de permisos

API interna

Una API interna esta pensada para servicios de plataforma, OpenClaw, automatizaciones o componentes internos aprobados.

Puede no estar publicada a Internet aun cuando exista.

API externa

Una API externa esta pensada para apps de clientes, terceros o integraciones fuera del runtime interno.

Reglas adicionales futuras:

  • autenticacion fuerte
  • auditoria reforzada
  • OpenAPI completo
  • rate limit cuando aplique

Arquitectura recomendada inicial

Arquitectura inicial recomendada:

flowchart LR
    pg[PostgreSQL] --> postgrest[PostgREST]
    postgrest --> npm[Nginx Proxy Manager]
    npm --> api[API]

Lectura:

  • PostgreSQL es la base objetivo futura
  • PostgREST puede exponer REST sobre la base
  • Nginx Proxy Manager puede servir inicialmente como SSL y proxy de publicacion
  • la base de datos nunca debe exponerse directamente

Evolucion futura recomendada

flowchart LR
    pg[PostgreSQL] --> runtime[PostgREST / APIs propias]
    runtime --> gateway[API Gateway futuro]
    gateway --> clients[Clientes internos y externos]

Lectura:

  • Kong u otro API Gateway queda como opcion futura, no obligatoria hoy
  • el gateway solo debe incorporarse si existe necesidad real de policy, versionado, rate limiting, developer portal o centralizacion de auth
  • Scalar queda recomendado como capa futura de documentacion interactiva

Reglas de exposicion

  • no exponer base de datos directamente
  • no exponer endpoints sin autenticacion ni permisos
  • no usar la ruta visible como unico control de seguridad
  • no mezclar datos de tenants por conveniencia
  • no publicar secretos reales en ejemplos, docs o logs

Contrato multi-tenant obligatorio

Toda API futura debe declarar como minimo:

  • scope: global o tenant
  • tenant_id
  • owner
  • consumidor esperado
  • tipo: interna o externa
  • permisos
  • scopes
  • fuente de datos
  • clasificacion de datos
  • auditoria requerida
  • rate limit futuro si aplica
  • documentacion OpenAPI requerida

Regla madre

Ninguna API puede devolver datos de otro tenant.

Esta regla aplica a:

  • consultas
  • respuestas paginadas
  • joins
  • exports
  • endpoints de lectura
  • endpoints de escritura
  • APIs internas
  • APIs externas

Convencion de endpoints

Convencion recomendada, sin implementacion todavia:

text GET /api/v1/global/status GET /api/v1/tenants/ladirecta/clientes GET /api/v1/tenants/alpuntodeventa/ventas GET /api/v1/tenants/{tenant_id}/productos POST /api/v1/tenants/{tenant_id}/pedidos

Reglas:

  • usar versionado explicito como /api/v1/
  • usar global para APIs compartidas de plataforma
  • usar /tenants/{tenant_id}/ para alcance por tenant
  • la ruta visible debe coincidir con el contrato, pero no reemplaza permisos, tokens, roles ni validacion real de tenant_id

Seguridad y permisos futuros

La seguridad futura recomendada debe combinar:

  • PostgreSQL Row Level Security
  • roles de base
  • JWT o API keys
  • claims con tenant_id
  • scopes
  • permisos de lectura vs escritura
  • auditoria de requests
  • logs sin secretos
  • rotacion de credenciales
  • principio de minimo permiso

Modelo de seguridad recomendado

flowchart TD
    client[Cliente o sistema] --> token[Token o API key]
    token --> auth[Auth y validacion de claims]
    auth --> check[Chequeo de tenant y scopes]
    check --> api[API / PostgREST]
    api --> rls[PostgreSQL RLS]
    rls --> data[Datos filtrados]

Reglas de permisos

  • una credencial de ladirecta solo puede ver tenant_id=ladirecta
  • una credencial de alpuntodeventa solo puede ver tenant_id=alpuntodeventa
  • un rol root o admin solo puede ver alcance global o cross-tenant si eso queda autorizado formalmente
  • escribir siempre debe requerir permisos mas estrictos que leer

Catalogo inicial de APIs futuras

Estado general del catalogo:

  • todas quedan en estado futuro
  • ninguna esta implementada en esta etapa

APIs globales

health

  • proposito: exponer salud oficial de la API Platform
  • fuente esperada: runtime API / metadata de plataforma
  • tipo de acceso: interna y externa segun publicacion futura
  • alcance: global
  • sensibilidad: baja
  • estado: futuro

tenants

  • proposito: listar tenants aprobados y metadata publica autorizada
  • fuente esperada: catalogo global de tenants
  • tipo de acceso: interna o externa controlada
  • alcance: global
  • sensibilidad: media
  • estado: futuro

platform status

  • proposito: entregar estado funcional resumido de servicios o capacidades aprobadas
  • fuente esperada: metadata de plataforma y servicios autorizados
  • tipo de acceso: interna y externa controlada
  • alcance: global
  • sensibilidad: media
  • estado: futuro

APIs por tenant

clientes

  • proposito: consultar y eventualmente mutar clientes del tenant
  • fuente esperada: WooCommerce, SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

productos

  • proposito: exponer catalogo de productos del tenant
  • fuente esperada: WooCommerce, SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: media
  • estado: futuro

marcas

  • proposito: exponer marcas y clasificaciones comerciales del tenant
  • fuente esperada: SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: media
  • estado: futuro

pedidos

  • proposito: consultar y registrar pedidos del tenant
  • fuente esperada: WooCommerce, SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

ventas

  • proposito: exponer ventas y hechos comerciales cerrados
  • fuente esperada: WooCommerce, SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

stock

  • proposito: exponer disponibilidad y movimientos de stock
  • fuente esperada: SGC / ERP, PostgreSQL
  • tipo de acceso: interna y externa controlada
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

alertas

  • proposito: consultar alertas de negocio o acknowledge futuro
  • fuente esperada: PostgreSQL, OpenClaw
  • tipo de acceso: interna
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

workflows

  • proposito: listar o operar workflows auditables del tenant
  • fuente esperada: OpenClaw, PostgreSQL
  • tipo de acceso: interna
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

agentes

  • proposito: consultar estado o capacidades auditables de agentes del tenant
  • fuente esperada: OpenClaw, PostgreSQL
  • tipo de acceso: interna
  • alcance: tenant
  • sensibilidad: alta
  • estado: futuro

API Documentation Future

Toda API futura debe tener contrato OpenAPI.

Herramienta recomendada futura

  • Scalar

Alternativa

  • Swagger UI

Que debe cubrir OpenAPI

  • endpoints
  • parametros
  • respuestas
  • errores
  • scopes
  • ejemplos
  • autenticacion esperada

Reglas para documentacion interactiva

  • las pruebas deben usar tokens de prueba o entornos controlados
  • no deben exponerse secretos reales
  • la interfaz interactiva no reemplaza permisos ni controles reales
  • los ejemplos deben usar datos ficticios o anonimizados

Diagramas de referencia

Data Foundation -> API Platform -> Consumers

flowchart LR
    data[Data Foundation] --> api[API Platform]
    api --> grafana[Grafana]
    api --> openclaw[OpenClaw]
    api --> agents[Agentes]
    api --> third[Terceros autorizados]

Tenant API request flow

flowchart TD
    user[Usuario o app del tenant] --> route[Endpoint /tenants/{tenant_id}]
    route --> auth[Auth]
    auth --> claims[Claims y scopes]
    claims --> tenant[Tenant check]
    tenant --> api[API / PostgREST]
    api --> rls[PostgreSQL RLS]
    rls --> response[Respuesta filtrada]

Security flow

flowchart TD
    req[Request] --> token[JWT o API key]
    token --> validate[Validacion]
    validate --> scopes[Chequeo de scopes]
    scopes --> perms[Chequeo lectura/escritura]
    perms --> audit[Auditoria]
    audit --> data[Acceso permitido]

Future API Docs flow

flowchart LR
    openapi[OpenAPI] --> docs[Scalar o Swagger UI]
    docs --> test[Pruebas controladas]
    test --> users[Equipos internos y terceros autorizados]

Casos de uso

Caso 1 - La Directa consulta sus ventas desde una app externa

La app usa una credencial de ladirecta, consulta GET /api/v1/tenants/ladirecta/ventas y solo recibe datos filtrados por tenant_id=ladirecta.

Caso 2 - Alpuntodeventa consulta productos para un dashboard

Un dashboard del tenant consulta GET /api/v1/tenants/alpuntodeventa/productos y solo ve el catalogo del tenant autorizado.

Caso 3 - OpenClaw consume API interna de pedidos

Un workflow interno consulta pedidos del tenant correcto usando permisos internos y deja trazabilidad de la request.

Caso 4 - Un tercero autorizado consulta stock de un tenant

Un partner autorizado consume un endpoint de stock con autenticacion, scopes restringidos y auditoria activa.

Caso 5 - Un token invalido o de otro tenant debe ser rechazado

Si un token de ladirecta intenta consultar /api/v1/tenants/alpuntodeventa/ventas, la request debe rechazarse antes de devolver datos.

Roadmap de implementacion futura

Las siguientes subfases quedan definidas solo como roadmap interno de la API Platform. No estan implementadas en esta etapa.

  • 15.1 API Platform Contract
  • 15.2 PostgreSQL base minima de prueba
  • estado actual: sandbox privado validado en VPS con RLS, datos ficticios y sin publicacion host, implementado en infra/data-foundation/postgres-sandbox/
  • 15.3 PostgREST sandbox interno
  • estado actual: implementado como sandbox interno inicial en infra/data-foundation/postgrest-sandbox/, primero con vistas fijas por rol para validar RLS y OpenAPI sin exposicion publica
  • 15.4 Seguridad sandbox con JWT
  • estado actual: consolidada sobre un runtime interno unico con claims tenant_id, role, scope, aud, iss y exp, secreto fuera de Git, scope enforcement por recurso en db-pre-request y RLS reforzada en base
  • 15.5 OpenAPI Refinement Sandbox
  • estado actual: documentado en docs/governance/operations/OPENAPI-REFINEMENT-SANDBOX.md, con contrato objetivo, metadata SQL humana para PostgREST, evaluacion de superficie y carpeta de exportes preparada sin instalar todavia Scalar
  • 15.6 API Docs con Scalar
  • estado actual: implementado como portal sandbox sobre contratos sanitizados en https://developers.alpuntodeventa.com.ar
  • 15.7 Publicacion segura por NPM
  • estado actual: implementada para el portal sandbox sin reach al backend
  • 15.8 Pruebas con tenants alpuntodeventa y ladirecta
  • 15.9 Auditoria y logs

Decisiones ya tomadas

  • la API Platform queda aprobada como capa documental oficial
  • la arquitectura inicial recomendada es PostgreSQL -> PostgREST -> Nginx Proxy Manager -> API
  • la evolucion futura puede incorporar PostgREST / APIs propias y un gateway posterior si existe necesidad real
  • PostgreSQL Row Level Security es la base futura recomendada para evitar acceso cruzado entre tenants
  • toda API futura debe tener OpenAPI
  • Scalar queda como recomendacion futura para documentacion interactiva

Decisiones pendientes

  • cuando abrir la implementacion runtime real de la API Platform
  • si el primer runtime sera solo PostgREST o mezcla con APIs propias
  • formato final de JWT, API keys y claims
  • politica final de rate limiting por tipo de consumidor
  • momento de aprobacion real de Scalar o Swagger UI
  • politica final de auditoria de lectura para endpoints sensibles

Regla final

No se considera aprobada ninguna API futura si no respeta al mismo tiempo:

Y por encima de todo:

  • ninguna API puede mezclar datos entre tenants