Ir al contenido

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.

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.

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.

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.

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.