La API para clientes forma parte del plan Enterprise. Su descripción incluye los endpoints de escritura y las operaciones y feeds del módulo de campo, y la capa MCP para clientes de IA usa esas mismas operaciones. Mientras el módulo de campo está cerrado para una cuenta, sus operaciones y feeds responden 403 con INSUFFICIENT_SCOPE, porque sus permisos solo se pueden dar a una clave mientras el módulo está abierto; mientras los clientes de IA están desactivados, la dirección de la capa MCP responde 404. Este artículo explica cómo indica la API su versión, qué puede cambiar y con cuánto aviso.
Dónde está la versión
- La ruta lleva la versión principal: todas las operaciones están bajo
/api/portal/v1. - El documento OpenAPI de
/api/portal/v1/openapi.json(OpenAPI 3.1, público y sin datos) da la versión completa eninfo.version, hoy 1.18.0. Se genera a partir de las mismas definiciones que sirve la API, así que no puede apartarse de ellas; cada operación indica su permiso enx-scopey, cuando los clientes de IA pueden llamarla, el nombre de su herramienta enx-mcp-tool. Con?format=swagger2llega en Swagger 2.0, para las herramientas que solo importan esa versión, como Power Automate (suscripciones por la API). - La capa MCP declara la misma versión, y sus herramientas son las operaciones de la API con los mismos nombres, así que las dos cambian a la vez.
La referencia de la API de este centro de ayuda se construye a partir del mismo documento, y las referencias de MCP y de webhooks, a partir del mismo registro.
Lo que puede añadir una versión
Una versión que añade operaciones, permisos, feeds o eventos de webhook deja lo que existía como estaba. Cuando llegaron los permisos y las operaciones del módulo de campo, no cambió nada de la primera versión: las claves creadas antes de que existieran los permisos siguen leyendo los datos del lineal y las semanas publicadas, y /releases sigue sin tener en cuenta su consulta. Cualquier otra petición GET responde 400 a un parámetro de consulta que no admite, un feed a una opción que su archivo no admite, y una petición POST lee solo su cuerpo, nunca su dirección. La versión que añadió la búsqueda por nombre cambió el orden de la lista de incidencias y el de /data/{kind} cuando aún ninguna cuenta tenía clave: las incidencias paginan por su apertura, de la más reciente a la más antigua, para que ninguna página pierda una, y los datos llegan con las semanas más recientes primero.
Para que una novedad nunca rompa tu cliente, haz que no tenga en cuenta los campos de una respuesta que no conozca y que trate un valor que no reconozca como algo de lo que avisar, no como un fallo. Sigue la versión del documento y vuelve a leer la referencia cuando cambie.
Cambios incompatibles y retiradas
Un cambio incompatible, o la retirada de la API o de un formato de exportación, llega con aviso, y lo anterior se mantiene al menos 90 días después de ese aviso (cláusula 12.3 de las condiciones del portal para marcas). Lo mismo vale para lo que reciben las integraciones de la cuenta: los archivos y mensajes que se entregan a sus sistemas, a sus direcciones de webhook, a las aplicaciones que tienen sus claves de API y a los asistentes de IA que autorizan sus miembros (cláusula 12.4). Nuestros avisos llegan por correo a la dirección del administrador que consta en la cuenta (cláusula 17.1), así que mantenla al día.
Los 90 días cubren la API, los formatos de exportación y esas entregas; para las funciones del portal, los nombres de las métricas y las pantallas, consulta la cláusula 12.3.
Qué hacer ante un aviso
- Lee el aviso y la referencia para saber qué cambia y desde cuándo.
- Prueba el nuevo comportamiento dentro de esos 90 días, con una clave que tenga solo los permisos que necesita la prueba.
- Revisa tus receptores de webhooks y tus importaciones CSV, además de tus llamadas a la API.
- Escribe a marcas@mercamap.com si algo del aviso no está claro.