iDempiere OpenAPI Contract

Objetivo

Producir una especificacion OpenAPI versionada y util como contrato entre:

• backend OSGi/Java,
• UI (ZK o frontend externo),
• clientes externos (POS, mobile, integraciones, middleware).

Estructura sugerida (si el repo no tiene una)

• openapi/ (specs versionadas)
• postman/ (colecciones exportadas)
• java/ (stubs/SDKs generados si aplica)
• osgi/ (esqueleto de bundle/servicios)
• db/migrations/ (migraciones necesarias)
• tests/contract/ (contract tests)
• docs/ (guia funcional/tecnica)

Dominios comunes (baseline)

• /auth/token
• /health
• /customers (C_BPartner)
• /products (M_Product)
• /inventory
• /sales/orders
• /shipments
• /invoices
• /payments
• /reports
• /webhooks
• /sync (offline/batch)

Workflow recomendado

1. Versionar el contrato
   • Usar semver estricto y un archivo por version.
2. Disenar schemas y mapping a iDempiere
   • Modelar IDs y referencias (AD_Client/AD_Org, C_BPartner, M_Product, etc).
   • Definir formato consistente de errores (4xx/5xx) y validaciones (422).
3. Disenar endpoints por dominio
   • Separar por bounded contexts (ventas, stock, finanzas, integraciones).
4. Seguridad
   • Documentar scopes/roles y aplicar security por operation.
   • No exponer datos sensibles (PCI/PII).
5. Validar y generar artefactos
   • Lint/validate de OpenAPI.
   • Generar stubs (Java) y coleccion Postman si el repo lo requiere.
   • Agregar contract tests contra mock o staging.
6. Integracion en OSGi
   • Definir servicios, transacciones y manejo de idempotencia.

Checklist de salida

• Spec valida y versionada (semver).
• Ejemplos coherentes y errores documentados.
• Seguridad definida y aplicada.
• Artefactos derivados reproducibles (si aplican).