OpenAPI spec

Where to get it

Source	When to use
api.fiscaliacore.com/v3/api-docs	Always-current JSON, served by the production backend. Regenerated on every deploy.
api.fiscaliacore.com/v3/api-docs.yaml	Same content, YAML form — handy for diff-friendly review.
docs/api/openapi.json on GitHub	Versioned snapshot committed with each release. Pin your client generator to this for reproducible builds.

Key bits of the spec

• OpenAPI version: 3.1.0
• Title: fiscaliacore API
• Version: v1 (semver tracking starts when we exit Phase 7)
• Servers:
  • https://api.fiscaliacore.com — Production
  • http://localhost:8081 — Local development
• Security scheme: bearerSession (HTTP Bearer, opaque format) — the session token from POST /api/v1/sessions
• Tags: Sessions, ACECF — Aprobación Comercial (more arrive as Phases 3–5 ship)

Versioning policy

• v1 path prefix freezes when we exit Phase 7 (full stateless bridge + Pasos 4–15 green). Breaking changes thereafter ship under v2.
• Non-breaking additions (new endpoints, new optional fields, new enum values) ship in place without prefix changes.
• Breaking changes in v1 are limited to the refactor's phase transitions and are announced via Deprecation: header + sunset date at least 60 days in advance.

Client generation

Pick any OpenAPI-compatible generator. Examples:

# Typed TypeScript with fetch
npx openapi-typescript-codegen \
  --input https://api.fiscaliacore.com/v3/api-docs \
  --output ./src/fiscaliacore-client \
  --client fetch

# Java
npx @openapitools/openapi-generator-cli generate \
  -i https://api.fiscaliacore.com/v3/api-docs \
  -g java \
  -o ./fiscaliacore-client-java

# Python (httpx)
npx @openapitools/openapi-generator-cli generate \
  -i https://api.fiscaliacore.com/v3/api-docs \
  -g python \
  -o ./fiscaliacore-client-python

Generated clients don't know about the session-token retry pattern — wrap the generated methods in a thin adapter that handles 401 SESSION_EVICTED per the session-auth guide.