Descripción general

Esta documentación explica cómo integrar la API v3 de Sheriff en tu sistema. Incluye el proceso de autenticación, las dos formas de integrarse y el detalle de cada endpoint disponible.

Glosario de Términos

¿Necesitas interpretar los valores que devuelve la API? Consulta el Glosario de Términos, con la referencia de campos como tipoPersona, vigente, fuente, ayudanteFallido y otros.

Endpoints disponibles

Método	Endpoint	Descripción
POST	/helper/cargarRut	Carga de RUT: carga de un RUT en tu cuenta como consulta o monitoreo, con análisis Marshal opcional.
GET	/helper/resumen?rut={rut}	Resumen de un perfil: información consolidada de un RUT cargado en tu cuenta.
POST	/webhook/profile/resumen	Webhook de resumen: resumen de un RUT en JSON o PDF, entregado en tu webhook.
GET	/helper/legal/{rut}/mallaSocietaria	Malla Societaria: socios, administradores, participaciones y extractos.
GET	/helper/legal/{rut}/capasMallaSocietaria	Capas de la Malla Societaria: relaciones societarias por niveles, con paginación.
GET	/helper/legal/{rut}/capasMallaSocietaria/niveles	Niveles de la Malla Societaria: cantidad de niveles y de relaciones por nivel.
GET	/helper/legal/{rut}/cmf	CMF: accionistas, directores, ejecutivos y socios registrados en la CMF.
GET	/helper/compliance/{rut}	Detalle de Compliance: coincidencias por fuente y hallazgos del análisis Marshal.
POST	/helper/compliance/{rut}/actualizarMarshal	Actualizar Marshal: solicitud de un nuevo análisis Marshal para un RUT ya cargado.
POST	/webhook/compliance/cargarPerfil	Cargar perfil en Compliance: búsqueda de compliance por nombre, con análisis Marshal opcional, entregada en tu webhook.
GET	/compliance/perfiles	Listar perfiles: perfiles de compliance buscados por nombre, con filtros y paginación.
GET	/compliance/perfiles/{id}	Detalle de un perfil: resultado completo de una búsqueda de compliance por nombre.
GET	/compliance/perfiles/{id}/investigaciones	Investigaciones de un perfil: investigaciones Marshal de un perfil buscado por nombre.
GET	/marshal/investigaciones?rut={rut}	Listar investigaciones: investigaciones Marshal de un RUT, con filtros y paginación.
GET	/marshal/investigaciones/{id}	Detalle de una investigación: reporte completo de una investigación Marshal.

¿Vienes de la API v2?

Revisa la Guía de Migración v2 → v3.

Formas de integrarse con Sheriff

1. Integración con la API de la plataforma

Consultas la información directamente en la Plataforma: cargas un RUT con Carga de RUT y luego consultas su resumen y su detalle legal y de compliance.

2. Integración con webhook

Envías un RUT al webhook de resumen y recibes el resumen en tu webhook cuando la información está lista.

Especificaciones técnicas

URL base de la API

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

Rate Limits

La API v3 (/api/clients/v3/*) limita la cantidad de solicitudes en ventanas de 15 minutos para asegurar la disponibilidad del servicio. Hay 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 v3 autenticados¹	1000 req / 15 min	accessKey con fallback a IP	—

¹ Aplica a /helper, /webhook, /compliance y /marshal.

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

Límite compartido entre versiones

Los contadores se calculan por accessKey y se comparten entre todas las versiones de la API. Las solicitudes que hagas a /api/clients/v2/* y a /api/clients/v3/* con la misma credencial descuentan del mismo límite de 1000 req / 15 min.

Headers de respuesta

Las respuestas que cuentan para el límite incluyen los headers estándar IETF:

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

Respuesta 429 — Demasiadas solicitudes

La respuesta trae este body:

{
  "success": false,
  "code": 429,
  "error": "Demasiadas solicitudes desde esta API externa, intente más tarde."
}

En getToken, el mensaje indica qué límite se superó (ver Obtener Token). La respuesta incluye el header Retry-After con los segundos que debes esperar antes de reintentar. El token JWT tiene una vigencia (TTL) de 2 horas, y los límites de getToken están pensados para que lo guardes en caché y lo reutilices durante toda esa vigencia.

Almacenamiento compartido

Los contadores son globales y no se reinician al rotar entre distintos nodos o servidores. Todas las solicitudes de un mismo cliente cuentan para el mismo límite, sin importar qué instancia las reciba.

Recomendaciones de integración

1. Guarda en caché el token JWT durante su vigencia (2 h), en lugar de pedir uno nuevo en cada solicitud. El mismo token autentica todas las versiones de la API.
2. Ante un 429, lee el header Retry-After para saber cuántos segundos esperar antes de reintentar.
3. Si tu integración necesita más de 1000 req / 15 min de forma sostenida, contáctanos para evaluar alternativas.

Errores

En Errores encontrarás la estructura de un error y los errores que puede responder cualquier endpoint. Los errores propios de cada endpoint están en su página.