bmc-api-contract-validator
Validates API responses against the canonical contract from planilla-inventory and DASHBOARD-INTERFACE-MAP. Catches drift before the UI breaks. Use when validating API contracts, pre-deploy checks, or
SKILL.md.cursor/skills/bmc-api-contract-validator/SKILL.md
GitHubBMC API Contract Validator
Before working: Read docs/team/knowledge/Contract.md if it exists.
Valida que las respuestas de la API cumplan el contrato canónico definido por Mapa (planilla-inventory, DASHBOARD-INTERFACE-MAP). Detecta drift antes de que la UI falle.
When to Use
- Después de cambios en
bmcDashboard.jsosheets-api-server.js - Pre-deploy: validar que los endpoints devuelven la forma esperada
- Cuando Vista reporta "datos no disponibles" o errores de consumo
- Sync: como parte del pre-deploy checklist
Canonical Contracts (from Mapa)
GET /api/kpi-financiero
{
"ok": true,
"pendingPayments": [{ "CLIENTE_NOMBRE", "COTIZACION_ID", "MONTO", "MONEDA", "FECHA_VENCIMIENTO", "ESTADO_PAGO" }],
"calendar": [{ "date", "total", "byCurrency": {} }],
"byPeriod": { "estaSemana", "proximaSemana", "esteMes", "total" },
"byCurrency": { "$": { "total", "estaSemana", "proximaSemana", "esteMes" }, ... },
"currencies": ["$", "UES", ...],
"metas": [{ "PERIODO", "TIPO", "META_MONTO", "MONEDA", "NOTAS" }]
}
GET /api/proximas-entregas
{ "ok": true, "data": [{ "COTIZACION_ID", "CLIENTE_NOMBRE", "TELEFONO", "DIRECCION", "FECHA_ENTREGA", ... }] }
GET /api/audit
{ "ok": true, "headers": [], "data": [{ "TIMESTAMP", "ACTION", "ROW", "OLD_VALUE", "NEW_VALUE", "REASON", "USER", "SHEET" }] }
Workflow
- Read planilla-inventory.md and DASHBOARD-INTERFACE-MAP.md for contract.
- Run
node scripts/validate-api-contracts.js(or equivalent) against running server. - Report pass/fail per endpoint; list missing or unexpected fields.
- Update PROJECT-STATE if drift detected; notify Mapa and Vista via Log.
Script
Run with server at http://localhost:3001 (or BMC_API_BASE env):
BMC_API_BASE=http://localhost:3001 node scripts/validate-api-contracts.js
Reference
- planilla-inventory:
docs/google-sheets-module/planilla-inventory.md - DASHBOARD-INTERFACE-MAP:
docs/bmc-dashboard-modernization/DASHBOARD-INTERFACE-MAP.md - bmcDashboard.js:
server/routes/bmcDashboard.js