Saltar a contenido

Scalar Sandbox Developer Portal

Fecha: 2026-06-03

Objetivo

Publicar un portal Scalar en https://developers.alpuntodeventa.com.ar para documentar las APIs sandbox de forma profesional, navegable y segura, sin exponer PostgREST publicamente, sin publicar datos reales y sin convertir todavia la capa en una API productiva.

Estado al 2026-06-03:

  • portal publicado y validado por HTTPS
  • HTTP redirige a HTTPS
  • Scalar carga correctamente
  • OpenAPI publico sigue sanitizado
  • PostgREST continua interno
  • probe publico agregado a observabilidad
  • stash remoto pre-scalar-sandbox-2026-06-02 revisado y preservado

Diagnostico previo

Safe point inicial

  • git status -sb -> ## main...origin/main
  • git rev-parse HEAD -> 58c5557cd2ae4a39bf4eaff0981319879d97152f

Hallazgos reales del 2026-06-02

  • developers.alpuntodeventa.com.ar resuelve a 46.202.151.32
  • openclaw-postgrest-sandbox sigue Up
  • openclaw-postgres-sandbox sigue Up (healthy)
  • proxy-network existe en el VPS
  • pg-sandbox-internal existe en el VPS
  • openclaw-postgrest-sandbox mantiene PortBindings {}
  • openclaw-postgrest-sandbox sigue solo en pg-sandbox-internal
  • http://developers.alpuntodeventa.com.ar respondia el fallback HTTP de NPM
  • https://developers.alpuntodeventa.com.ar todavia no tenia publicacion valida
  • el contrato runtime de PostgREST sigue siendo swagger: "2.0"
  • el contrato runtime seguia declarando host: openclaw-postgrest-sandbox:3000

Revalidacion operativa del 2026-06-03

  • http://developers.alpuntodeventa.com.ar/ -> 301 a https://developers.alpuntodeventa.com.ar/
  • https://developers.alpuntodeventa.com.ar/ -> 200
  • https://developers.alpuntodeventa.com.ar/clientes -> 404
  • Scalar sigue cargando con hideTestRequestButton: true
  • el certificado HTTPS sigue valido y responde sin warning de cliente
  • openclaw-postgrest-sandbox mantiene PortBindings {}
  • openclaw-postgrest-sandbox sigue solo en pg-sandbox-internal
  • el probe publico de developers.alpuntodeventa.com.ar queda agregado a blackbox-http

Revision del stash remoto

Comandos ejecutados en /opt/openclawai:

  • git stash list
  • git stash show --stat stash@{0}
  • git diff --stat HEAD stash@{0}

Resultado:

  • stash@{0} sigue siendo pre-scalar-sandbox-2026-06-02
  • el stash contiene cambios previos sobre postgrest-sandbox y su documentacion
  • no representa un pendiente simple del portal actual
  • comparado contra HEAD, aplicarlo hoy removeria artefactos ya publicados de 15.5/15.6 y mezclaria regresiones documentales y runtime

Decision:

  • conservar el stash
  • no aplicarlo
  • no eliminarlo

Motivo:

  • sirve como resguardo previo a Scalar
  • no hay evidencia suficiente para considerarlo descartable
  • eliminarlo agregaria riesgo operativo innecesario

Compatibilidad Scalar

La documentacion oficial de Scalar valida dos puntos utiles para esta etapa:

  • la imagen scalarapi/api-reference permite montar documentos en /docs
  • Scalar renderiza documentos OpenAPI/Swagger, por lo que Swagger 2.0 sigue siendo aceptable para este sandbox

Decision:

  • mantener Swagger 2.0 en 15.6
  • no convertir a OpenAPI 3 solo por estetica
  • sanitizar host, schemes y mensaje de uso en los JSON exportados

Que muestra el portal

  • tres contratos sanitizados:
  • Sandbox Global
  • Sandbox Al Punto de Venta
  • Sandbox La Directa
  • recursos visibles:
  • clientes
  • productos
  • ventas
  • tenants
  • metadata humana agregada en 15.5
  • respuestas esperadas y modelos del sandbox

Que NO permite todavia

  • no ejecuta requests reales contra PostgREST
  • no publica tokens
  • no publica secretos
  • no conecta datos reales
  • no expone PostgREST fuera de pg-sandbox-internal
  • no reemplaza la futura API productiva

Acceso y uso en lenguaje simple

Que es:

  • un portal publico de documentacion del sandbox
  • una forma segura de mostrar contratos y recursos sin abrir el backend real

Que se puede ver:

  • endpoints sandbox
  • parametros
  • respuestas
  • esquemas
  • diferencias por perfil de contrato

Que no se puede hacer todavia:

  • llamar la API real
  • pedir tokens desde la UI
  • escribir datos
  • acceder a datos productivos

Por que las requests reales no estan habilitadas:

  • porque PostgREST vive solo en red privada Docker
  • porque el objetivo de esta etapa es documentar sin exponer backend
  • porque todavia no existe una capa aprobada de auth, rate limiting y auditoria para uso publico controlado

Que falta para pasar de sandbox documental a APIs controladas:

  • politica formal de pruebas interactivas
  • auth publica controlada
  • auditoria de requests
  • decision de mocks o proxy seguro
  • gobierno de versionado entre sandbox y productivo

Por que no conecta directo al runtime interno

PostgREST sandbox hoy exige JWT, vive solo en red privada Docker y declara un host interno. Exponerlo publicamente para que Scalar haga requests reales rompería tres reglas del proyecto:

  • mantencion de PostgREST como servicio interno
  • no publicacion de datos reales ni caminos productivos
  • separacion estricta entre documentacion sandbox y runtime real

Por eso Scalar consume solo artefactos sanitizados versionados en Git.

Contratos OpenAPI usados

Ubicacion versionada:

  • infra/data-foundation/postgrest-sandbox/openapi/openapi-sandbox-global.json
  • infra/data-foundation/postgrest-sandbox/openapi/openapi-sandbox-alpuntodeventa.json
  • infra/data-foundation/postgrest-sandbox/openapi/openapi-sandbox-ladirecta.json

Origen:

  • runtime interno http://openclaw-postgrest-sandbox:3000/
  • tokens generados en memoria sobre el VPS
  • sanitizacion inmediata antes de persistir en Git

Como se sanitizan

Script oficial:

  • infra/data-foundation/postgrest-sandbox/tools/export-sanitized-openapi.sh

Reglas aplicadas:

  • reemplazar host por developers.alpuntodeventa.com.ar
  • reemplazar schemes por https
  • fijar basePath en /mock
  • remover securityDefinitions nulas
  • mantener descripciones humanas del sandbox
  • agregar disclaimer explicito de no-productivo
  • no guardar tokens ni secretos en ningun archivo

Regeneracion segura paso a paso

  1. Entrar al directorio del sandbox:

bash cd /opt/openclawai/infra/data-foundation/postgrest-sandbox

  1. Ejecutar la regeneracion oficial:

bash bash tools/export-sanitized-openapi.sh

  1. Confirmar que el script cierre en: OpenAPI sanitizado exportado y validado

  2. Revalidar manualmente:

bash grep -R -n -E "openclaw-postgrest-sandbox|pg-sandbox-internal|rpc/|Authorization|Bearer |token|secret" openapi

Resultado esperado:

  • sin coincidencias

  • Revalidar el host y la base publica:

bash grep -R -n -E "\"host\": \"developers.alpuntodeventa.com.ar\"|\"basePath\": \"/mock\"" openapi

  1. Reaplicar el contenedor Scalar:

bash cd /opt/openclawai docker compose -f infra/api-docs/scalar-sandbox/docker-compose.yml up -d

  1. Verificar el portal publicado:

bash curl -I http://developers.alpuntodeventa.com.ar/ curl -I https://developers.alpuntodeventa.com.ar/ curl -I https://developers.alpuntodeventa.com.ar/clientes

Datos que muestra

  • nombres de recursos y columnas del sandbox
  • ejemplos y esquemas derivados del runtime real
  • metadata humana agregada con COMMENT ON
  • solo datos ficticios del sandbox multi-tenant

Implementacion elegida

Stack repo:

  • infra/api-docs/scalar-sandbox/docker-compose.yml
  • infra/api-docs/scalar-sandbox/scalar.config.json
  • infra/api-docs/scalar-sandbox/README.md

Decisiones:

  • usar la imagen oficial scalarapi/api-reference
  • montar contratos sanitizados en /docs
  • unir el contenedor a proxy-network
  • no publicar puertos al host
  • ocultar el boton de prueba real para impedir requests contra backend real

Publicacion por NPM

Publicacion aprobada:

  • dominio: developers.alpuntodeventa.com.ar
  • upstream: scalar-sandbox:8080
  • SSL: Let's Encrypt
  • Force SSL: activo
  • HTTP/2: activo

Observabilidad

Estado aplicado al 2026-06-03:

  • developers.alpuntodeventa.com.ar agregado a infra/observability/prometheus/targets/blackbox-http-targets.json
  • Executive Infrastructure Board actualizado para mostrar Developer Portal
  • la alerta generica BlackboxProbeFailed cubre este probe sin exponer servicios internos

Validacion esperada en VPS:

  • target https://developers.alpuntodeventa.com.ar/ en Prometheus -> up
  • panel Developer Portal en Grafana -> UP

Relacion con API Documentation Platform

Esta etapa ejecuta por primera vez la arquitectura definida en docs/architecture/API-DOCUMENTATION-PLATFORM.md:

OpenAPI sanitizado -> Scalar -> Developer Portal sandbox

No reemplaza la etapa productiva futura. Solo cierra la capa documental sandbox sobre contratos seguros.

Que queda para produccion futura

  • tokens sandbox controlados desde la UI si se aprueban
  • proxies de prueba o mocks dedicados
  • versionado formal de APIs
  • politica de auditoria de pruebas interactivas
  • separacion sandbox vs productivo por tenant
  • publicacion futura de APIs reales con auth y rate limiting

Experiencia de uso

Como entrar

  • abrir https://developers.alpuntodeventa.com.ar

Que se ve

  • selector de tres contratos sandbox
  • recursos clientes, productos, ventas, tenants
  • esquemas, parametros, ejemplos y respuestas

Que se puede probar

  • navegacion de endpoints
  • lectura del contrato
  • inspeccion de modelos y respuestas

Que todavia no se puede probar

  • ejecucion real de requests contra PostgREST
  • autenticacion real con tokens desde la UI
  • acceso a datos productivos o privados

Checklist de cierre

  • SAFE POINT inicial registrado
  • diagnostico real documentado
  • documento SCALAR-SANDBOX-DEVELOPER-PORTAL.md creado
  • contratos sanitizados generados
  • sin host interno Docker en JSON versionados
  • sin secretos ni tokens persistidos
  • stack Scalar sandbox preparado
  • publicacion por NPM prevista sobre developers.alpuntodeventa.com.ar
  • PostgREST preservado como interno
  • stash remoto revisado y conservado por seguridad
  • probe publico agregado sin exponer servicios internos