Compatibilidad
Qué puede cambiar sin aviso mientras el API siga en v1, y qué no.
La versión del API va en la ruta (/integrations/v1). Mientras esa versión no
cambie, nos comprometemos a no romper una integración existente. Eso significa
que sí podemos hacer, en cualquier momento y sin avisar:
- Agregar campos a cualquier respuesta.
- Agregar valores a una lista existente: un estado de orden nuevo, un código de error nuevo, un evento de webhook nuevo.
- Agregar endpoints, filtros opcionales y campos opcionales en los cuerpos.
- Cambiar la redacción de
messagey destatusLabel, que son texto de presentación. - Ajustar el límite de peticiones, que siempre viaja en las cabeceras
X-RateLimit-*.
Por eso tu cliente tiene que ignorar lo que no conoce en vez de fallar: campos nuevos, estados nuevos y códigos nuevos van a aparecer.
Lo que no vamos a hacer sin publicar una versión nueva del API:
- Quitar o renombrar un campo de una respuesta.
- Cambiar el tipo o el significado de un campo existente.
- Quitar un endpoint, o volver obligatorio un campo que era opcional.
- Endurecer una validación de forma que un cuerpo que hoy se acepta pase a rechazarse.
- Cambiar el algoritmo de firma o la cadena canónica.
Si alguna vez hiciera falta, /integrations/v2 convivirá con /v1 durante un
periodo de transición que acordaremos con vos. No vamos a apagar una versión sin
aviso previo.
Los cambios de esta documentación se registran en Historial de cambios.