Descripción General

Esta documentación ofrece una guía para integrar la API de Sheriff en su entorno. A continuación, encontrará detalles sobre el proceso de autenticación y las dos modalidades de integración, con una descripción de cada endpoint disponible.

Glosario de Términos

¿Necesitas interpretar los valores devueltos por la API? Consulta el Glosario de Términos para una referencia completa de campos como postura, estado, riesgo, tipos de proceso judicial, y más.

Formas de integrarse con Sheriff

1. Integración API de la plataforma

Consultas directas a la Plataforma para cargar RUTs y obtener información sobre los RUTs cargados, casos civiles, credit scoring, y más.

2. Integración con Webhook/Callback

Integrarse a través de un Webhook/Callback.

Especificaciones técnicas

URL base de la API

Ambiente de producción: https://prod.api.thesheriff.cl/api/clients/v2/

Ambiente de QA: https://qa.api.thesheriff.cl/api/clients/v2/

Rate Limits

La API v2 (/api/clients/v2/*) aplica límites de tasa con ventana de 15 minutos para garantizar la disponibilidad del servicio. Existen tres límites independientes:

#	Endpoint	Límite	Calculado por	Header en 429
1	POST /apiCredentials/getToken	100 req / 15 min	IP del cliente	X-RateLimit-Source: ip
2	POST /apiCredentials/getToken	20 req / 15 min	accessKey	X-RateLimit-Source: credential
3	Resto de endpoints v2 autenticados¹	1000 req / 15 min	accessKey con fallback a IP	—

¹ Aplica a /profiles, /helper, /creditScore, /webhook y /usage.

En el endpoint getToken se aplican los límites 1 y 2 en cascada: la solicitud debe pasar tanto el límite por IP como el límite por credencial. Si excede el primero devuelve X-RateLimit-Source: ip; si excede el segundo, X-RateLimit-Source: credential.

Headers de respuesta

Todas las respuestas incluyen los headers estándar IETF:

• RateLimit-Limit — límite total para la ventana actual.
• RateLimit-Remaining — solicitudes restantes en la ventana.
• RateLimit-Reset — segundos hasta que se restablezca el contador.

Respuesta 429 — Demasiadas solicitudes

El cuerpo del error incluye el campo retryAfter con los segundos a esperar antes de reintentar (900 equivale a 15 minutos). El token JWT tiene un TTL de 2 horas: los límites de getToken están dimensionados asumiendo que el token se cachea y reutiliza durante toda su vida útil.

Almacenamiento compartido

Los contadores son globales y no se reinician al rotar entre distintos nodos o servidores. Un mismo cliente cuenta contra el mismo cupo independientemente de la instancia que reciba la solicitud.

Recomendaciones de integración

1. Cachear el token JWT durante su vida útil (2 h) en lugar de solicitarlo en cada request.
2. Ante un 429, leer el header RateLimit-Reset para saber cuántos segundos esperar antes de reintentar.
3. Si tu integración requiere más de 1000 req / 15 min sostenidos, contáctanos para evaluar alternativas (por ejemplo, ajuste por credencial).

Colección Postman - API Sheriff V2

Descarga la colección oficial de Postman y el environment para probar la API V2 localmente. Ambos archivos contienen variables y tests que facilitan las pruebas.

Descarga rápida

• Colección Postman: 📥 Sheriff API v2 - Collection
• Variables de Entorno: 📥 Sheriff API v2 - Environment

Instrucciones rápidas:

• Importa la Colección y el Environment en Postman.
• En el Environment, configura solo la variable rut con el RUT que quieras probar, y las variables accessKey y accessSecret con tus credenciales. Para saber cómo generar estas credenciales, consulta Generar Credenciales de API.
• Ejecuta las requests de autenticación para obtener el token; la colección tiene tests que guardan automáticamente el token como variable de entorno (token), por lo que no necesitas setearlo manualmente.
• Luego, prueba los endpoints de la colección directamente.

Versión: 2.0.0
Última actualización: Noviembre 2025