docs: align API specifications and correct SDK examples

[javorosas]

Summary

Align the Spanish and English OpenAPI 3.1 specifications with the public API contract.

• Add missing operation IDs and validate required path parameters.
• Describe all seven public webhook events with correlated event and resource types using the standard OpenAPI webhooks field.
• Correct webhook subscription fields, supported events, URL formats, creation status, and signature-validation request and response schemas.
• Define invoice creation responses as an invoice or draft instead of an untyped object.
• Correct nullable response fields and date formats, including SAT stamp dates, and document cancellation timestamps and missing public response fields.
• Define invoice creation variants explicitly by invoice type and draft status, and keep defaulted input fields optional.
• Align pagination, retention status filters, catalog errors, and both language versions.
• Add automated specification checks and representative TypeScript contract examples.
• Correct CommonJS installation examples in Spanish and English to use const Facturapi = require('facturapi'), and normalize the TypeScript label.

Scope

These changes update documentation and contract checks. They do not change API behavior. The checks cover schema structure and representative examples; they do not establish exhaustive coverage of every accepted request and response.

This PR consolidates and supersedes #301 and #302, keeping the response-schema and installation-example corrections together.

Release coordination

The direct CommonJS constructor example corresponds to the support introduced in FacturAPI/facturapi-node#121. Merge these documentation changes once that SDK release is available on npm.

Validation

• pnpm install --frozen-lockfile
• pnpm test:openapi: local references, unique operation IDs, required path parameters, OpenAPI 3.1 nullability, structural parity between languages, and representative TypeScript examples.
• pnpm build
• pnpm typecheck
• git diff --check

[Copilot]

Copilot review overview

🟡 Changes recommended

Certificate nullability remains incomplete, draft stamp types reject null, and webhook operation IDs are not validated.

Review effort: Balanced
Findings: 5

Open (5)

• Draft invoice stamp schema must allow null · New
• certificate.updated_at remains non-nullable · New
• El esquema stamp de borradores debe admitir null · New
• certificate.updated_at must allow null · New
• Webhook operation IDs are excluded from global validation · New

What changed in this PR

Aligns bilingual OpenAPI contracts with the public API and adds automated contract validation.

Changes:

• Corrects schemas, webhooks, pagination, nullability, and invoice variants.
• Adds OpenAPI structural and TypeScript contract checks.
• Adds CI and repository guidance for API documentation changes.

File	Description
AGENTS.md	Adds documentation and contract guidelines.
.github/​workflows/​openapi.yml	Runs OpenAPI checks in CI.
website/​openapi_v2.yaml	Updates the Spanish API contract.
website/​openapi_v2.en.yaml	Updates the English API contract.
website/​scripts/​check-openapi.mjs	Validates both specifications.
website/​test/​openapi-types.fixture.txt	Adds representative generated-type checks.
website/​package.json	Adds the OpenAPI test command and dependencies.
website/​pnpm-lock.yaml	Locks new dependencies.
website/​tsconfig.json	Excludes generated directories from type checking.

Files not reviewed (1)

• website/pnpm-lock.yaml: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical OpenAPI schema and lockfile issues remain unresolved.

Review effort: Lite
Findings: 3 · 2

Open (5)

• Restore missing enum key for SAT values · New
• Restablecer la clave enum para los valores SAT · New
• Regenerate lockfile with the missing webpack snapshot · New
• Allow nullable uuid in invoice drafts · New
• Permitir uuid nullable en borradores de factura · New

Resolved since last review (5)

• Webhook operation IDs are excluded from global validation
• certificate.updated_at must allow null
• El esquema stamp de borradores debe admitir null
• certificate.updated_at remains non-nullable
• Draft invoice stamp schema must allow null

Files not reviewed (1)

• website/pnpm-lock.yaml: Generated file

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate OpenAPI contract inconsistencies and an incomplete nullable-schema validator remain unresolved.

Review effort: Lite
Findings: 4

Open (4)

• Add wildcard to webhook request event enums · New
• Allow null customer in invoice draft responses · New
• Add wildcard to webhook request event enums · New
• Permitir customer nulo en respuestas de borradores · New

Resolved since last review (5)

• Regenerate lockfile with the missing webpack snapshot
• Restablecer la clave enum para los valores SAT
• Restore missing enum key for SAT values
• Permitir uuid nullable en borradores de factura
• Allow nullable uuid in invoice drafts

Files not reviewed (1)

• website/pnpm-lock.yaml: Generated file

[Copilot]

Copilot review overview

🔵 Needs a closer look

One or more issues must be addressed before approval.

Review effort: Lite
Findings: None

Resolved since last review (4)

• Permitir customer nulo en respuestas de borradores
• Add wildcard to webhook request event enums
• Allow null customer in invoice draft responses
• Add wildcard to webhook request event enums