Revisar el changelog del API de Crol antes de liberar

Revisar el changelog del API antes de liberar tu integración

CÓMO SE HACE ⏱ 4 min 📦 Centro de ayuda. Para desarrolladores

Revisa el changelog del API de Crol para saber qué cambió antes de mover tu integración a producción. Úsalo en cada liberación y cada vez que un endpoint deje de responder como esperabas. Al terminar sabrás qué cambios te afectan y qué ajuste pide cada uno.

Pre-requisitos

  • Tienes una integración activa contra el API de Crol y sabes qué endpoints consume.
  • Conoces la fecha de tu última revisión del changelog. Si es tu primera vez, toma la fecha en que liberaste la integración.
  • No necesitas token ni credenciales: el changelog es público.

Pasos

  1. Entra al changelog desde la pantalla de Crol REST API, en apidocs.crol.mx. Si prefieres el enlace directo, es api.crol.mx/changelog.html.

La pantalla de Crol REST API tiene tres accesos al changelog, y los tres llevan al mismo lugar: el aviso Conoce los cambios realizados en el API de la barra superior, el enlace Changelog de la esquina superior derecha y el enlace changelog de la API dentro de la introducción.

Pantalla de Crol REST API con los tres accesos al changelog resaltados
  1. Pulsa Breaking en la barra de filtros. Es lo único que obliga a un cambio de tu lado, así que se revisa primero.

La barra superior del changelog filtra el historial por tipo de cambio y trae un buscador para localizar un endpoint por su nombre.

Changelog del API de Crol mostrando la barra de filtros con las opciones Todos, Nuevo, Mejorado, Corregido, Breaking e Info junto al buscador del historial
  1. Recorre las entradas hasta la fecha de tu última revisión. El historial va de la más reciente a la más antigua y se agrupa por fecha, así que todo lo que está por encima de esa fecha es tu pendiente.
  2. Lee la Acción requerida de cada entrada Breaking. Ahí está el ajuste concreto, no el diagnóstico.

Cada entrada trae su etiqueta de tipo, la descripción del cambio y —cuando aplica— el endpoint afectado y el bloque de acción requerida. El símbolo # de la izquierda es el enlace permanente de esa entrada.

Entrada de tipo Breaking en el changelog del API de Crol con su enlace ancla, la descripción del cambio y el bloque de acción requerida
  1. Copia el enlace # de cada entrada que te afecta y regístralo en tu control de versiones. El identificador es estable y sirve para citar el cambio exacto en un ticket.
  2. Aplica los ajustes en tu código y pruébalos con cuidado: el API de Crol no tiene ambiente de pruebas, así que cada petición trabaja sobre los datos reales de tu empresa.
  3. Anota la fecha de esta revisión. Es el punto de partida de la siguiente.
Advertencia: no hay ambiente de pruebas del API. Como integrador trabajas siempre contra la empresa productiva, así que valida primero con las peticiones de consulta y deja para el final las que crean o modifican documentos, sobre registros que puedas cancelar.
Nota: las etiquetas Nuevo, Mejorado, Corregido e Info no rompen tu integración: las adoptas cuando te convenga. Solo Breaking cambia el contrato del endpoint.

Resultado esperado

  • Tienes la lista de cambios posteriores a tu última revisión, separados entre los que te afectan y los que no.
  • Cada cambio Breaking que te afecta tiene su ajuste aplicado y probado.
  • Tu bitácora de versiones cita el identificador de cada entrada que motivó un cambio de código.

Variaciones / Notas

Automatizar la revisión con el changelog en JSON

El mismo historial se publica como un arreglo de objetos en api.crol.mx/changelog.json, sin token. El enlace vive en el pie de la página.

Pie del changelog del API de Crol con la nota de actualización manual y el enlace Ver como JSON

Cada objeto trae id, fecha, tipo y descripcion; los cambios que lo ameritan agregan endpoint y accionRequerida. Con eso agregas un paso a tu proceso de liberación que falle si aparece un cambio Breaking posterior a tu última revisión.

Buscar un endpoint concreto

Si lo que quieres saber es qué pasó con un endpoint específico, escribe su nombre en el buscador del historial en lugar de recorrer las fechas. El filtro de tipo y el buscador se combinan.

Qué no encontrarás en el changelog

El historial se actualiza manualmente y resume los cambios relevantes para quien integra. No incluye cambios internos de infraestructura ni de mantenimiento. Para el detalle de cómo quedó un endpoint, consulta el Swagger en api.crol.mx: el changelog dice qué cambió, el Swagger dice cómo quedó.

Errores frecuentes

«Mi integración dejó de recibir el arreglo de un catálogo»

Causa: un cambio Breaking movió ese catálogo al formato estándar del API y la lista dejó de venir en la raíz del cuerpo de la respuesta.

Solución: filtra por Breaking, busca el endpoint y aplica la acción requerida. En estos casos el listado se lee desde el campo data de la respuesta.

«El changelog no menciona el cambio que me reportó soporte»

Causa: el historial excluye los cambios internos de infraestructura y mantenimiento, que no alteran el contrato de ningún endpoint.

Solución: contrasta el endpoint contra el Swagger. Si el comportamiento no coincide con lo documentado, abre un ticket describiendo la petición y la respuesta que recibes.

«Me citaron una entrada y no la encuentro»

Causa: el filtro activo esconde las entradas de otros tipos, o la entrada es más antigua que lo que alcanzas a ver.

Solución: vuelve a Todos y pega el identificador en el buscador. Si te pasaron el enlace completo con #, ábrelo directo: te lleva a la entrada exacta.

Hazlo simple.