Skip to main content
Los agentes se integran una vez y luego corren sin supervisión, así que el contrato tiene que decir de antemano qué puede cambiar y con cuánto aviso.

​
Versionado

Cada ruta lleva su versión mayor: /co/rues/entity-by-nit/v1, /pe/sunat/ruc/v1, /global/web-search/v1. La versión es parte de la ruta, no un encabezado, de modo que una solicitud es inequívoca por sí sola y la descripción OpenAPI en https://api.croma.run/openapi (también en https://usecroma.com/openapi.json) lista todas las versiones en servicio. Dentro de una versión mayor el contrato solo crece. Estos cambios salen sin nueva versión y sin aviso:
  • Endpoints nuevos, campos opcionales nuevos en la solicitud, campos nuevos en la respuesta.
  • Valores nuevos en campos documentados como conjuntos abiertos (estados, nombres y términos legales en el idioma de la fuente).
  • Fuentes nuevas detrás de un endpoint existente, si la forma de la respuesta no cambia.
Estos cambios rompen el contrato y exigen una nueva ruta mayor (/v2):
  • Eliminar o renombrar un campo de solicitud o de respuesta.
  • Cambiar el tipo o el significado de un campo.
  • Volver obligatorio un campo de solicitud opcional.
  • Cambiar un code de error o el sobre de error.
Los nombres de campo son snake_case en inglés en todos los endpoints, y todo endpoint acepta un encabezado opcional Idempotency-Key; esas convenciones también son parte del contrato.

​
Deprecación

Cuando una versión de un endpoint se programa para retiro:
  1. Se anuncia en el changelog (y en su feed Atom) con al menos 90 días de anticipación a la fecha de retiro, nombrando el sucesor.
  2. Desde el anuncio, cada respuesta del endpoint en retiro lleva un encabezado Deprecation (RFC 9745) con la fecha en que la deprecación entró en vigor, un encabezado Sunset (RFC 8594) con la fecha de retiro y un encabezado Link con rel="successor-version" apuntando al reemplazo.
  3. La descripción OpenAPI marca la operación con deprecated: true y su descripción nombra el sucesor.
  4. Pasada la fecha de retiro, la ruta responde 410 Gone con el sobre de error estándar (code: "endpoint_retired") y el mismo encabezado Link, durante al menos 90 días más.
Hoy ningún endpoint está deprecado, así que ninguna respuesta lleva estos encabezados todavía; un cliente que revise Deprecation y Sunset en cada respuesta se enterará de un retiro el mismo día en que se anuncie.

​
Lo que esto no cubre

  • El contenido de los datos. Croma devuelve los registros oficiales tal como se publican; que una fuente cambie lo que publica no es un cambio de la API. Cada guía anota los límites propios de la fuente.
  • Los límites de tasa y cupos, que son por organización y pueden cambiar con tu plan. Se reportan en cada respuesta; consulta Límites de tasa.
  • El servidor MCP negocia su versión de protocolo según el Model Context Protocol; los nombres de las herramientas siguen los ids de los endpoints (rues_entity_by_nit) y comparten el calendario de deprecación de los endpoints que tienen detrás.