Contrato API — OpenAPI 3.0

El contrato de la API del ERP vive en web/contracts/openapi.yaml: OpenAPI 3.0.3, versión 2.0.0, ~880 paths (~24.000 líneas). Es la fuente de verdad de los endpoints: se actualiza antes de implementar el consumo en frontend, y el CI lo hace cumplir con un gate bloqueante.

Dónde verlo

Superficie	URL / ruta	Acceso
Swagger UI	`api.zentto.net/docs`	Requiere sesión de admin del ERP (cookie httpOnly — iniciar sesión en `app.zentto.net` primero). No es público.
Spec JSON	`api.zentto.net/openapi.json`	Mismo requisito (JWT + admin). Sin sesión responde 401.
Repositorio	`zentto-web/web/contracts/openapi.yaml`	Fuente canónica versionada; también `openapi-additions.yaml` y colecciones Insomnia/Postman generadas
Catálogo para reportes	`GET /v1/report-contract`	Subconjunto solo-GET del contrato, filtrable por `?scope=<tags>` (lo usa el asistente de reportes)

Por qué no está embebido aquí

El spec dejó de servirse público: /docs y /openapi.json van tras requireJwt + requireAdmin (y el kill-switch DOCS_ENABLED=false los apaga por completo). Un Swagger UI embebido en esta página no puede cargar el spec sin esa sesión, así que esta página documenta el sistema y enlaza a la UI oficial.

Vista local del contrato

# Con el repo clonado — vista interactiva local:
npx @redocly/cli preview-docs web/contracts/openapi.yaml

# O levantar la API local y abrir http://localhost:4000/docs
cd web/api && npm run dev

Cómo se sirve en la API

swagger-ui-express monta /docs (explorer, persistAuthorization) y /openapi.json en app.ts.
src/lib/openapi-doc.ts memoiza el YAML y elimina 8 prefijos legacy del contrato publicado (/v1/facturas, /v1/compras, /v1/pedidos, /v1/cotizaciones*, /v1/ordenes, /v1/presupuestos, /v1/notas) — rutas viejas que no deben usarse.
La imagen Docker de la API copia el contrato a /app/contracts/openapi.yaml.

Gates de CI (bloqueantes)

Gate	Qué verifica	Dónde corre
Audit OpenAPI coverage	`npm run audit:openapi` — todo endpoint montado tiene su entrada en el contrato	job `type-check` de `deploy-api.yml` y `test.yml`
SP Contract Tests	`tests/schema/sp-contracts.test.ts` — las firmas y shapes de las funciones PL/pgSQL coinciden con lo que la API espera (contra un PostgreSQL de servicio)	job `schema-tests` (prod y dev)
Audit API shapes	Consistencia de shapes de respuesta (modo warning, no bloquea — publica resumen en el PR)	`audit-api-shapes.yml`

Reglas de trabajo con el contrato

Contrato primero: endpoint nuevo o cambio de shape → actualizar openapi.yaml en el mismo PR (el gate lo exige).
Autenticación: los endpoints protegidos declaran cookie/bearer; el esquema real es cookie httpOnly zentto_token (o Bearer para server-to-server).
Shapes de listas: { items, total }; escrituras: { ok, id?, message }. Un grid vacío con API 200 casi siempre es un shape mismatch — el contrato es el árbitro.
Los microservicios tienen contrato propio (zentto-auth, payments, notify, geo…): este documento cubre solo la API del ERP.