Saltar al contenido principal

Cambios en la API

Cambios en la API

La API de Soyio evoluciona constantemente: agregamos endpoints, campos y eventos para sumar funcionalidades. Esta página explica qué cambios publicamos sin previo aviso, cuáles anunciamos con anticipación y cómo preparar tu integración para que siga funcionando a medida que la API crece.

Todas las rutas de la API viven bajo /api/v1. Publicamos los cambios compatibles sin previo aviso. Los cambios incompatibles los anunciamos antes de aplicarlos.

Cambios compatibles​

Son cambios que no requieren modificar tu integración, siempre que siga las recomendaciones de esta página. Los publicamos en cualquier momento y sin aviso previo:

  • Agregar endpoints o recursos nuevos
  • Agregar parámetros opcionales al request body o a la query
  • Agregar campos a las respuestas de la API o al payload de los eventos
  • Agregar valores nuevos a un enum, por ejemplo un estado o un tipo de acción
  • Agregar tipos de evento nuevos a los webhooks
  • Agregar filtros u opciones de ordenamiento a los endpoints de listado
  • Cambiar el orden de los campos en un objeto JSON
  • Cambiar el texto de title, detail o errors en las respuestas de error
  • Marcar un campo o endpoint como deprecado, sin eliminarlo
  • Cambiar el largo o el formato interno de los identificadores, manteniendo su prefijo (agr_, evt_, etc.)

Cambios incompatibles​

Son cambios que pueden romper una integración existente. Los anunciamos con anticipación y no los aplicamos en producción hasta que termine el periodo de aviso:

  • Eliminar o renombrar un endpoint, un campo o un tipo de evento
  • Eliminar o renombrar un valor de un enum
  • Cambiar el tipo de dato de un campo, por ejemplo de string a integer
  • Volver obligatorio un parámetro que era opcional
  • Agregar un parámetro obligatorio sin valor por defecto
  • Agregar validaciones que rechacen requests que antes eran válidos
  • Cambiar el código HTTP o el type de error que retorna un caso existente
  • Cambiar el comportamiento documentado de un endpoint o el momento en que se emite un evento
  • Cambiar el formato de autenticación o de la firma de los webhooks

Si encontramos una vulnerabilidad de seguridad, podemos aplicar el cambio necesario sin cumplir el periodo de aviso. En ese caso, te avisamos lo antes posible y te explicamos qué necesitas ajustar.

El comportamiento no documentado, como campos que aparecen en una respuesta pero no en la referencia de la API, puede cambiar sin aviso. Construye tu integración solo sobre lo que está documentado.

Cómo anunciamos un cambio incompatible​

  1. Marcamos lo que va a cambiar como deprecado: el campo o endpoint aparece con la etiqueta deprecated en la referencia de la API y en la especificación OpenAPI, junto a la alternativa que debes usar.
  2. Te escribimos por email: avisamos a los contactos técnicos de tu cuenta qué cambia, cómo migrar y desde qué fecha aplica.
  3. Mantenemos el comportamiento anterior durante el periodo de aviso: lo deprecado sigue funcionando hasta la fecha anunciada.

Mantén actualizados los contactos técnicos de tu cuenta para no perderte estos avisos.

Prepara tu integración​

Sigue estas prácticas para que los cambios compatibles no afecten tu integración:

  • Ignora los campos que no conoces: no rechaces una respuesta ni un evento porque trae campos nuevos. Si validas respuestas con un schema estricto, permite propiedades adicionales.
  • Maneja valores de enum desconocidos: usa un caso por defecto cuando recibas un estado o tipo que tu código no reconoce, en lugar de fallar.
  • Usa el type y el código HTTP para manejar errores: no dependas del texto de title, detail o errors, porque puede cambiar. Revisa los tipos de error.
  • Lee los campos por nombre: no dependas del orden de los campos en el JSON.
  • Trata los identificadores como strings opacos: guárdalos sin asumir un largo fijo.
  • Suscríbete solo a los eventos que procesas: si usas el wildcard *, vas a recibir también los tipos de evento nuevos. Revisa los wildcards de suscripción.
  • Revisa los campos deprecados: si un campo que usas aparece como deprecated en la referencia, migra a la alternativa indicada.