Versiones de la API
La API se versiona por URL: todas las rutas llevan el prefijo de la versión que estás usando.
https://api-public.thesheriff.pe/v1/perfiles/{taxId}/resumen
↑
Una versión es un contrato: mientras la uses, la forma de las respuestas no cambia de manera incompatible. Cuando necesitamos cambiar el contrato, publicamos una versión nueva y la anterior sigue funcionando en paralelo.
Versiones disponibles
| Versión | Estado | Qué significa para ti |
|---|---|---|
v1 | Estable | La versión que debes usar en producción hoy. Sin fecha de deprecación. |
v2 | Beta | Ya responde en paralelo a v1 y puedes probarla, pero su contrato todavía puede cambiar. No integres producción contra ella. |
En la Referencia API puedes alternar entre las dos versiones con el selector que está en la barra superior — cada versión tiene su documentación completamente separada.
Qué cambia en v2
La v2 moderniza el resumen de perfil, empezando por la sección finanzas: la información del sistema financiero pasa de los tramos de variación por mora a un modelo de situación por período (vigente, refinanciada/reestructurada, vencida, judicial), con la peor calificación y los días de atraso. Además incorpora el estado de carga del perfil: estado y subhelpers_fallidos a nivel raíz, y cada sección envuelta en { statusCode, data } para distinguir "sin datos" de "fuente caída", "en carga" o "no contratado". El detalle campo a campo, con ejemplos, está en la guía de migración v1 → v2.
Antes de declarar v2 estable se anunciarán cambios adicionales en otras secciones del resumen. Por eso la versión sigue en beta: preferimos que migres una sola vez, cuando el contrato nuevo esté completo.
El resto de la API (autenticación, carga de perfiles, webhooks) responde igual en las dos versiones.
Cómo probar v2
- No necesitas credenciales nuevas. Tus API credentials y tus tokens JWT sirven para las dos versiones — la autenticación es común.
- Cambia el prefijo de la URL en el ambiente donde quieras probar:
/v1/...→/v2/.... - Las dos versiones responden en paralelo, así que puedes comparar las respuestas del mismo perfil lado a lado.
Mientras v2 esté en beta, mantén producción en v1. Los cambios que hagamos en v2 durante la beta no se anuncian con el mismo protocolo que un cambio sobre una versión estable.
Cómo será la migración
Cuando v2 se declare estable:
- Te contactaremos directamente con el detalle de los cambios y los plazos.
- La guía de migración tendrá el listado final de qué campos desaparecen y por cuáles se reemplazan.
- v1 seguirá funcionando durante la transición. Si en algún momento se define una fecha de retiro para v1, se anunciará con anticipación por los mismos canales.
- No hace falta migrar todo de una vez: puedes tener endpoints apuntando a versiones distintas durante la transición, porque la autenticación es común a todas.
Cómo escribir tu integración para que los cambios no te rompan
Tres reglas que hacen que los cambios normales (campos nuevos, endpoints nuevos) sean transparentes para ti:
- Ignora los campos que no conoces. Configura tu deserialización en modo permisivo: si tu parser falla ante una clave inesperada, cualquier campo nuevo te rompe.
- No dependas del orden de las claves de un objeto JSON, ni del orden de los elementos de un array salvo que la documentación lo garantice.
- No uses campos que no estén documentados. Si ves una clave que no aparece en la Referencia API, puede desaparecer sin aviso.
¿Dudas?
Si no estás seguro de si un cambio te afecta, o quieres que revisemos tu integración antes de migrar, escríbenos. Preferimos resolverlo antes que después.