Esta es la versión 1 de la API pública. No hay un segmento explícito de versión en la URL (no usamos /v1/) porque nos comprometemos a no romper el contrato público actual. Cuando exista una versión incompatible, será publicada bajo un nuevo prefijo y la versión actual seguirá disponible durante el periodo de transición.
Política de compatibilidad
Nos comprometemos a no romper, sin aviso previo, los siguientes elementos:
- Las rutas, métodos HTTP y códigos de estado documentados.
- Los nombres de los campos existentes en los payloads de respuesta.
- La semántica de los campos (su significado y unidad).
- Los códigos de error documentados.
Qué consideramos cambios no disruptivos
Pueden ocurrir en cualquier momento, sin comunicación previa:
- Agregar nuevos endpoints.
- Agregar campos opcionales a un request.
- Agregar campos nuevos a una respuesta.
- Agregar valores nuevos a un catálogo (siempre que tu integración no los enumere de forma cerrada).
Qué consideramos cambios disruptivos
Si tuvieran que ocurrir, los anunciaremos por correo a todos los integradores con al menos 90 días de antelación:
- Renombrar o eliminar campos.
- Cambiar tipos (de
stringaint, por ejemplo). - Cambiar la semántica de un campo o de un endpoint.
- Cambiar códigos de estado HTTP usados en escenarios estables.
Deprecación
Cuando un endpoint o un campo se marque como deprecado, recibirás:
- Una nota en esta documentación.
- Un header
Sunseten las respuestas indicando la fecha de retiro. - Un correo con al menos 90 días de aviso antes del retiro definitivo.