Canales y compatibilidad
| Capacidad | REST v1 | CLI | MCP de esta entrega |
|---|---|---|---|
| Identidad, objetos y campos | Sí | Sí | Sí |
| Lectura, historial y transiciones disponibles | Sí | Sí | Sí |
| Crear, modificar o borrar registros | Sí | Sí | Sí, con confirmación |
| Ejecutar acciones/transiciones | Sí | Sí | Sí, con confirmación |
| Archivos, analítica, bulk y eventos | Sí | Sí | Sí; archivos hasta 1 MiB |
| Calendario y notificaciones propias | Sí | Sí | Sí |
| Retrieve y validate de metadata | Sí | Sí | Sí |
| Consultar despliegues de metadata | Sí | Sí | Sí |
| Deploy, cancel, quick deploy y rollback | Sí | Sí | Sí, con confirmación |
| Corridas y aprobaciones de agentes | Sí | Sí | Sí, con gobernanza |
La referencia OpenAPI es el inventario completo de operaciones REST, con scopes y riesgo. La presencia de un endpoint no implica que la conexión esté autorizada a usarlo. La IA interna puede incorporar capacidades adicionales que todavía no constituyen un contrato público.
Versiones y ambientes
Sección titulada «Versiones y ambientes»La ruta /api/v1 identifica la versión mayor del contrato REST. El manifiesto del portal publica un hash del snapshot de OpenAPI y del catálogo MCP; esos hashes identifican exactamente la documentación distribuida.
Consultá /api/v1/capabilities y /api/v1/openapi.json en el ambiente de destino. El catálogo MCP efectivo se obtiene con tools/list. No deduzcas la compatibilidad por el nombre de un tenant ni supongas que desarrollo, UAT y producción sirven la misma release.
Contrato estable de v1
Sección titulada «Contrato estable de v1»Dentro de /api/v1 se preservan rutas, métodos, significado de operaciones, parámetros obligatorios y tipos de campos documentados. Agregar campos opcionales de respuesta, operaciones, herramientas o códigos de error más específicos es compatible: los clientes deben ignorar campos de respuesta desconocidos y manejar códigos nuevos según su estado HTTP. No deben enviar propiedades de entrada desconocidas.
Eliminar o renombrar una operación, exigir un parámetro nuevo o cambiar el tipo o significado de un campo requiere una nueva versión mayor. Su publicación debe incluir una guía de migración y el calendario de convivencia antes de retirar la versión anterior. El número de release del ERP y la versión del contrato API son independientes.
Los permisos, scopes aprobados, publicación de objetos y reglas de negocio se evalúan en cada solicitud. Un cambio de permisos o una corrección de seguridad puede restringir acceso inmediatamente dentro de v1; no garantiza que un usuario conserve acceso a datos que antes podía consultar. Los objetos y campos personalizados se descubren en cada tenant y no forman un catálogo fijo entre ambientes.
La habilitación por tenant también es independiente de la release. Un ambiente todavía no habilitado responde 503 con public_api_disabled; reconectar o solicitar más permisos no lo habilita.
Verificación automática
Sección titulada «Verificación automática»pnpm check:api-contracts comprueba que OpenAPI, los esquemas de los controladores y el catálogo MCP distribuido no hayan quedado desactualizados. La suite de contratos del backend valida las operaciones y los ejemplos de examples/workflows.json. pnpm --filter=@erp/docs run test comprueba los recursos de documentación para clientes e IAs. Estas verificaciones forman parte de CI.
Qué no debe inferir un cliente
Sección titulada «Qué no debe inferir un cliente»Los esquemas de respuestas tipadas se generan desde los controladores. Las partes dinámicas, como campos de registros, entradas de acciones custom o definiciones extensibles, permanecen abiertas intencionalmente. Un esquema abierto no autoriza nombres arbitrarios: se completa con el descubrimiento del recurso, sus permisos y las validaciones del servidor.
OpenAPI sirve para construir solicitudes y clientes; no sustituye las reglas de negocio. El servidor sigue siendo la autoridad sobre permisos, límites, dependencias y estado vigente.