Guía de Migración: API v2 → API v3
Esta guía explica cómo migrar tu integración de la API v2 de Sheriff a la API v3. La migración no requiere cambios profundos en tu código: la autenticación, los headers y el sobre de respuesta (success / data) se mantienen. Principalmente debes actualizar la URL base y el parseo de algunas respuestas.
- URL base:
/api/clients/v2/→/api/clients/v3/. - Carga de RUT (
POST /helper/cargarRut): aceptaincludeMarshalpara solicitar el análisis Marshal,datapasa a ser un objeto conrutymessage, y un RUT que ya estaba en tu cartera responde409. - Resumen (
GET /helper/resumen): el bloquelegalpasa de objeto a arreglo de sociedades,ayudantesFallidosentrega códigos numéricos, se agregaayudanteFallido, las secciones de fuentes fallidas sin información previa viajan con su estructura completa en lugar de omitirse, algunos campos deidentificacionybienescambian de tipo, ycomplianceagregamarshalyestadoMarshaly usatipoPersona: "juridica"en lugar de"juridical". - Webhook de resumen (
POST /webhook/profile/resumen): la solicitud aceptaisMonitoringeincludeMarshal; el body que recibes incluyesuccess, usa el contrato v3 del resumen y se entrega aunque falle alguna fuente. - Legal: la respuesta de
GET /helper/legal/{rut}/mallaSocietariacambia, y se documentan endpoints nuevos: Capas y Niveles de la Malla Societaria, y CMF. - Compliance (
GET /helper/compliance/{rut}): agrega la detección de Marshal y entregaperiodoen formatoDD-MM-YYYY. - Marshal: nuevo endpoint
POST /helper/compliance/{rut}/actualizarMarshalpara solicitar un análisis Marshal de un RUT ya cargado, y endpoints para consultar las investigaciones y sus reportes (ver Marshal). - Compliance por nombre:
POST /webhook/compliance/cargarPerfilvalida el body, aceptaincludeMarshaly entregatipPersonacomo"juridica"en lugar de"juridical", y los perfiles cargados se pueden consultar con endpoints nuevos (ver Compliance por nombre). - Errores: todos los errores usan la estructura
{ success, code, error }con mensajes en español, incluidos los401de autenticación, los403por plan y el429(ver Estructura de los errores).
📋 Resumen de cambios principales
1. Cambio en la URL base
| Versión | URL base | Ejemplo completo |
|---|---|---|
| V2 | https://prod.api.thesheriff.cl/api/clients/v2/ | https://prod.api.thesheriff.cl/api/clients/v2/helper/resumen?rut=76123456-0 |
| V3 | https://prod.api.thesheriff.cl/api/clients/v3/ | https://prod.api.thesheriff.cl/api/clients/v3/helper/resumen?rut=76123456-0 |
Cambio: reemplaza v2 por v3 en la URL. El token y las credenciales no cambian.
2. Headers requeridos (sin cambios)
-H 'Authorization: Bearer <TU_TOKEN>'
-H 'accept: application/json'
🔄 Tabla de equivalencias de endpoints
| V2 | V3 | Cambios |
|---|---|---|
POST /helper/cargarRut | POST /helper/cargarRut | ⚠️ Nuevo campo opcional includeMarshal; data pasa a { rut, message }; 409 si el RUT ya estaba en tu cartera |
GET /helper/resumen?rut={rut} | GET /helper/resumen?rut={rut} | ⚠️ Cambia la estructura: legal es un arreglo, ayudantesFallidos usa códigos, se agrega ayudanteFallido, las secciones de fuentes fallidas viajan con su estructura y compliance suma marshal y estadoMarshal |
POST /webhook/profile/resumen | POST /webhook/profile/resumen | ⚠️ Acepta isMonitoring e includeMarshal; el body entregado en tu webhook incluye success y usa el contrato v3 del resumen |
GET /helper/legal/{rut}/mallaSocietaria | GET /helper/legal/{rut}/mallaSocietaria | ⚠️ Cambia la respuesta: socios, administradores, participaciones y extractos consolidados |
| ❌ No disponible | GET /helper/legal/{rut}/capasMallaSocietaria | ✨ NUEVO: Malla societaria por niveles, paginada |
| ❌ No disponible | GET /helper/legal/{rut}/capasMallaSocietaria/niveles | ✨ NUEVO: Niveles disponibles de la malla y cantidad de relaciones por nivel |
| ❌ No disponible | GET /helper/legal/{rut}/cmf | ✨ NUEVO: Registro CMF de la sociedad |
GET /helper/compliance/{rut} | GET /helper/compliance/{rut} | ⚠️ Agrega marshal.detectado, hallazgos de Marshal en noticias y periodo en DD-MM-YYYY |
| ❌ No disponible | POST /helper/compliance/{rut}/actualizarMarshal | ✨ NUEVO: Solicitud de un nuevo análisis Marshal para un RUT ya cargado |
POST /webhook/compliance/cargarPerfil | POST /webhook/compliance/cargarPerfil | ⚠️ Body validado, searchTolerance, nuevo includeMarshal y entrega con OAuth |
| ❌ No disponible | GET /compliance/perfiles | ✨ NUEVO: Lista de perfiles de compliance buscados por nombre |
| ❌ No disponible | GET /compliance/perfiles/{id} | ✨ NUEVO: Resultado completo de un perfil de compliance |
| ❌ No disponible | GET /compliance/perfiles/{id}/investigaciones | ✨ NUEVO: Investigaciones Marshal de un perfil de compliance |
| ❌ No disponible | GET /marshal/investigaciones?rut={rut} | ✨ NUEVO: Investigaciones Marshal de un RUT |
| ❌ No disponible | GET /marshal/investigaciones/{id} | ✨ NUEVO: Reporte completo de una investigación Marshal |
📥 Carga de RUT
POST /helper/cargarRut mantiene su body, agrega un campo opcional y cambia su respuesta:
| Dato | V2 | V3 |
|---|---|---|
includeMarshal | No existe | bool, por defecto false. Solicita el análisis Marshal del RUT. |
includeEquifax | Sin validar | Debe ser booleano; un valor distinto de true o false responde 400. |
Respuesta 200 | {"success": true, "data": ["<rut>"]} | {"success": true, "data": {"rut": "<rut>", "message": "..."}} |
| RUT ya en tu cartera | 200 | 409 con El RUT <rut> ya estaba cargado en tu cartera. |
❌ V2 (Anterior)
{
"success": true,
"data": ["76123456-0"]
}
✅ V3 (Nuevo)
{
"success": true,
"data": {
"rut": "76123456-0",
"message": "El RUT 76123456-0 se ha cargado en la cartera de la corporación."
}
}
Cómo migrar:
- Lee el RUT cargado en
data.rut. - Trata el
409como "ya estaba cargado", no como una falla. - Si usas Marshal, envía
includeMarshal: truey maneja el403que responde la API cuando tu plan no cuenta con Marshal. - Si el RUT ya está en tu cartera, la carga no solicita un análisis nuevo: para eso usa Actualizar Marshal.
📊 Cambios en el resumen
legal: de objeto a arreglo
En la v2, legal era un objeto con listas por fuente. En la v3 es un arreglo de sociedades: una sola entrada para una persona jurídica, o una por cada sociedad en la que participa una persona natural.
❌ V2 (Anterior)
"legal": {
"diarioOficial": {
"casos": [ { "fecha": "...", "razonSocial": "...", "seccion": "MODIFICACIÓN", "socios": [] } ],
"ultimaActualizacion": "23-07-2025 11:00:00"
},
"empresaEnUnDia": {
"casos": [ { "fecha": "...", "actuacion": "CONSTITUCIÓN", "socios": [], "administradores": [] } ],
"ultimaActualizacion": "23-07-2025 11:00:00"
},
"mallaSocietariaExterna": [ { "participaciones": [], "socios": [] } ],
"mallaSocietariaInterna": [ { "participaciones": [], "socios": [] } ]
}
✅ V3 (Nuevo)
"legal": [
{
"nombre": "EMPRESA FICTICIA SPA",
"rut": "76123456-0",
"fechaConstitucion": "02-06-2021",
"estado": "VIGENTE",
"trabajadores": 24,
"socios": [
{
"nombre": "SOCIO FICTICIO UNO",
"rut": "11111111-1",
"domicilio": "CALLE EJEMPLO 123, LAS CONDES",
"tipoPersona": "natural",
"tipos": ["ADMINISTRADOR", "SOCIO"],
"porcentaje": 70,
"vigente": true
}
],
"administradores": [
{
"nombre": "SOCIO FICTICIO UNO",
"rut": "11111111-1",
"domicilio": "CALLE EJEMPLO 123, LAS CONDES"
}
],
"participaciones": [],
"extractos": [
{
"fecha": "02-06-2021",
"actuacion": "CONSTITUCION",
"linkPdf": "https://www.registrodeempresasysociedades.cl/Certificados/",
"cve": "1234567",
"fuente": "EEUD"
}
],
"tieneCmf": false
}
]
Cómo migrar:
- Las publicaciones de
diarioOficial.casosyempresaEnUnDia.casosahora están enlegal[].extractos, conactuacion,fecha,cve,linkPdfyfuente("DO"o"EEUD"). - Los socios de cada publicación ahora están consolidados en
legal[].socios, con sus roles en el arreglotiposy el porcentaje como número enporcentaje. - Los administradores y representantes legales están en
legal[].administradores. mallaSocietariaExternaymallaSocietariaInternaahora se representan conlegal[].participaciones(sociedades en las que participa) ylegal[].socios(quiénes participan en ella). Para la malla completa por niveles, usa Capas de la Malla Societaria.legal[].tieneCmfindica si la sociedad tiene registro en la CMF, que puedes consultar con CMF.- Si no hay información legal,
legales un arreglo vacío ([]). legalmantiene su posición en la respuesta: después decobranzaLaboraly antes dedeudaBancaria.
ayudanteFallido y secciones sin información
❌ V2 (Anterior)
Cuando una fuente fallaba, su nombre aparecía en ayudantesFallidos. La sección conservaba la última información disponible y, si nunca se había obtenido, se omitía.
{
"rut": "76123456-0",
"incluyeEquifax": false,
"ayudantesFallidos": ["SII"]
}
✅ V3 (Nuevo)
Se agrega el booleano ayudanteFallido y ayudantesFallidos pasa a informar códigos numéricos. La sección conserva la última información disponible, igual que en la v2; si no la hay, viaja con su estructura completa en lugar de omitirse.
{
"rut": "76123456-0",
"identificacion": {
"razonSocial": null,
"inicioActividades": null,
"actividadEconomicaVigente": null,
"ultimaActualizacion": null
},
"incluyeEquifax": false,
"ayudanteFallido": true,
"ayudantesFallidos": [101]
}
Cómo migrar: evalúa ayudanteFallido antes de procesar el resumen y prepara tu integración para recibir secciones con sus campos en null o en 0. El detalle está en Secciones fallidas.
ayudantesFallidos: de nombres a códigos
En la v2, ayudantesFallidos traía el nombre de cada fuente que falló. En la v3 trae un código numérico por fuente, sin repetidos y en orden ascendente:
| Fuente | V2 (nombre) | V3 (código) |
|---|---|---|
| Identificación (SII) | "SII" | 101 |
| Tamaño de empresa (solo persona jurídica) | Nombre de la fuente | 102 |
| Judicial: causas civiles | "Judicial - Civil" | 201 |
| Judicial: causas de cobranza | "Judicial - Cobranza" | 202 |
| Judicial: causas laborales | "Judicial - Laboral" | 203 |
| Judicial: boletín concursal | "Boletín Concursal" | 204 |
| Boletín comercial (Bolcom o Cámara de Comercio) | Nombre de la fuente | 301 |
| Boletín comercial: Dicom | Nombre de la fuente | 302 |
| Boletín laboral | "Boletín Laboral" | 303 |
| Mora previsional | "Mora Previsional" | 401 |
| Multas laborales | "Multa Laboral" | 402 |
| Legal | "Legal" | 501 |
| Información del sistema financiero | Nombre de la fuente | 701 |
| Bienes: propiedades | "Propiedades" | 801 |
| Bienes: vehículos | "Vehículos" | 802 |
| Análisis Marshal (solo webhook) | No existe | 1101 |
Las fuentes que no alimentan ninguna sección del resumen ya no aparecen en ayudantesFallidos y no ponen ayudanteFallido en true.
Cómo migrar: reemplaza la comparación por nombre por una comparación por código. La tabla completa, con la sección que afecta cada código, está en Valores de ayudantesFallidos.
identificacion y bienes: tipos de datos
| Campo | V2 | V3 |
|---|---|---|
identificacion.presentaActividades | "SI" / "NO" | true / false; null si no se informa |
identificacion.autorizadoMonedaExtranjera | "SI" / "NO" | true / false; null si no se informa |
identificacion.empresaMenor | "SI" / "NO" | true / false; null si no se informa |
identificacion.actividadEconomicaVigente[].afectaIva | "Si" / "No" | true / false; null si no se informa |
identificacion.cantidadActividades y cantidadDocumentos | null si no hay | 0 si no hay |
identificacion.tamanoEmpresaSii.cantidadTrabajadores | Número o "Sin información" | Número; null si no se informa |
bienes.propiedades.tasacionTotal | Texto (ej: "1234") | Número (ej: 1234) |
Cómo migrar: ajusta el parseo de estos campos para leerlos como booleanos y números.
compliance: estado de Marshal
El bloque compliance del resumen agrega dos campos:
| Campo | Descripción |
|---|---|
marshal | true cuando tu plan cuenta con Marshal y el RUT está marcado con Marshal en tu cuenta (con includeMarshal o Actualizar Marshal). |
estadoMarshal | "PROCESADO" cuando el RUT tiene Marshal (marshal: true) y algún análisis Marshal completado; "NO PROCESADO" en otro caso. |
🔔 Webhook de resumen
Solicitud
La solicitud (POST /webhook/profile/resumen) mantiene rut, format e includeEquifax, y agrega dos campos opcionales:
| Campo | V2 | V3 |
|---|---|---|
isMonitoring | No existe (siempre es consulta) | true carga el RUT en monitoreo. Por defecto false. |
includeMarshal | No existe | Solicita el análisis Marshal si el RUT no estaba activo en tu cuenta y, si tu plan incluye Compliance, la entrega espera su resultado hasta 15 minutos (ver Análisis Marshal). |
Entrega del informe
El body que recibes en tu webhook agrega success y usa el contrato v3 del resumen. Si falla alguna fuente, el informe se entrega igual, con ayudanteFallido: true, en lugar de reemplazarse por una notificación de error.
❌ V2 (Anterior)
{
"identificador": 1,
"rut": "76123456-0",
"esPersonaJuridica": true,
"legal": { "diarioOficial": {}, "empresaEnUnDia": {} },
"ayudantesFallidos": []
}
✅ V3 (Nuevo)
{
"success": true,
"identificador": 1,
"rut": "76123456-0",
"esPersonaJuridica": true,
"legal": [],
"ayudanteFallido": false,
"ayudantesFallidos": []
}
Con includeMarshal: true, la entrega puede esperar hasta 15 minutos el análisis Marshal. Si el análisis no se completa, la entrega sale igual, con el código 1101 en ayudantesFallidos. El detalle está en Análisis Marshal.
⚖️ Malla Societaria
GET /helper/legal/{rut}/mallaSocietaria conserva su ruta, pero cambia la respuesta.
❌ V2 (Anterior)
{
"rut": "76123456-0",
"empresaEnUnDia": [
{
"fecha": "...",
"actuacion": "CONSTITUCIÓN",
"socios": [],
"administradores": []
}
],
"diarioOficial": [
{ "fecha": "...", "seccion": "MODIFICACIÓN", "socios": [] }
],
"participaciones": [[{ "rut": "...", "sociedad": "..." }]]
}
✅ V3 (Nuevo)
{
"rut": "76123456-0",
"nombre": "EMPRESA FICTICIA SPA",
"tipoPersona": "juridica",
"tieneCmf": false,
"fuentes": ["EEUD", "DO"],
"socios": [
{
"nombre": "...",
"rut": "...",
"tipoPersona": "natural",
"porcentaje": 70,
"vigente": true,
"tipos": ["SOCIO"]
}
],
"administradores": [{ "nombre": "...", "rut": "...", "domicilio": "..." }],
"participaciones": [
{
"nombre": "...",
"rut": "...",
"porcentaje": 50,
"vigente": true,
"tipos": ["ACCIONISTA"],
"fechaConstitucion": "..."
}
],
"extractos": [
{
"fecha": "...",
"actuacion": "CONSTITUCION",
"cve": "...",
"fuente": "EEUD",
"linkPdf": "..."
}
],
"ultimaActualizacion": "15-08-2026 13:45:10"
}
| Dato | V2 | V3 |
|---|---|---|
| Publicaciones de Empresa en un Día | empresaEnUnDia[] | extractos[] con fuente: "EEUD" |
| Publicaciones del Diario Oficial | diarioOficial[] | extractos[] con fuente: "DO" |
| Socios | socios[] dentro de cada publicación | socios[] consolidados, con porcentaje numérico, vigente y tipos |
| Administradores | administradores[] dentro de cada publicación | administradores[] consolidados |
| Participaciones en otras sociedades | participaciones[][] (listas anidadas de rut/sociedad) | participaciones[] plano, con nombre, rut, porcentaje y tipos |
| Registro CMF | No disponible | tieneCmf y el endpoint CMF |
| Persona natural | Endpoint aparte (mallaSocietariaPersonas) | Misma ruta: tipoPersona: "natural" y sociedades[] |
Además, la v3 documenta endpoints nuevos del ayudante Legal:
- Capas de la Malla Societaria (
GET /helper/legal/{rut}/capasMallaSocietaria): relaciones por nivel, paginadas, en modobeneficiariosFinalesoampliada. - Niveles de la Malla Societaria (
GET /helper/legal/{rut}/capasMallaSocietaria/niveles): cantidad de niveles y de relaciones por nivel. - CMF (
GET /helper/legal/{rut}/cmf): accionistas, directores, ejecutivos y socios registrados en la CMF.
🛡️ Compliance
GET /helper/compliance/{rut} conserva su ruta y su estructura (sociedades, listasInternacionales, penal, noticias, pepChile, familiaresPep, funcionariosPublicos), con estos cambios:
| Dato | V2 | V3 |
|---|---|---|
| Detección PEP de Marshal | No disponible | pepChile.marshal.detectado y familiaresPep.marshal.detectado |
| Hallazgos de Marshal | No disponible | Al inicio de noticias.coincidencias, sumados a totalCoincidencias |
periodo | Tal como lo entrega la fuente | Fechas exactas en DD-MM-YYYY; años o rangos tal cual; sin dato, null |
tipoPersona | "juridical" o "natural" | "juridica" o "natural", igual que en el bloque compliance del resumen |
Cómo migrar:
- Si parseas
periodocomo fecha, ajusta el formato aDD-MM-YYYY. - Si comparas
tipoPersona, usa"juridica"en lugar de"juridical". - Si no usas Marshal,
marshal.detectadoviaja ennullynoticiasno cambia.
El detalle está en Detalle de Compliance.
🔍 Marshal
Marshal no existe en la v2. En la v3 complementa el compliance con hallazgos en medios de prensa y detección de PEP, y se usa en estos endpoints:
| Endpoint | Uso de Marshal |
|---|---|
POST /helper/cargarRut | includeMarshal: true solicita el análisis al cargar un RUT que no estaba activo en tu cuenta. |
POST /webhook/profile/resumen | includeMarshal: true incorpora el análisis a la entrega y puede esperarlo hasta 15 minutos. |
POST /helper/compliance/{rut}/actualizarMarshal | ✨ Solicita un análisis nuevo de un RUT ya cargado. |
GET /helper/resumen | compliance.marshal y compliance.estadoMarshal informan si el RUT tiene Marshal y si tiene algún análisis completado. |
GET /helper/compliance/{rut} | Hallazgos de Marshal en noticias y detección de PEP en pepChile.marshal y familiaresPep.marshal. |
POST /webhook/compliance/cargarPerfil | includeMarshal: true incorpora el bloque marshal a la entrega del perfil buscado por nombre y puede esperarlo hasta 15 minutos. |
GET /marshal/investigaciones?rut={rut} | ✨ Lista las investigaciones de un RUT, con estado, motivo de falla y canal. |
GET /marshal/investigaciones/{id} | ✨ Entrega el reporte completo de una investigación. |
GET /compliance/perfiles/{id}/investigaciones | ✨ Lista las investigaciones de un perfil de compliance buscado por nombre. |
Todos los análisis son asíncronos y requieren que tu plan cuente con Marshal. Sin Marshal, las solicitudes con includeMarshal: true, Actualizar Marshal y las consultas de investigaciones responden 403 con el mensaje El plan no cuenta con Marshal..
🔎 Compliance por nombre
POST /webhook/compliance/cargarPerfil conserva su ruta, su respuesta inicial (webhookId) y el formato de la entrega (estado, resumen, datos*, total*), con estos cambios:
| Dato | V2 | V3 |
|---|---|---|
| Body | Sin validación | Validado: solo fullName es obligatorio; isJuridicalPerson, isMonitoring e includeMarshal por defecto false |
| Tolerancia de búsqueda | searchErrors | searchTolerance (se sigue aceptando searchErrors) |
| Análisis Marshal | No disponible | includeMarshal: true agrega el bloque marshal a la entrega |
tipPersona de la entrega | "juridical" o "natural" | "juridica" o "natural", igual que en el resto de la v3 |
| Autenticación de la entrega | Headers configurados | Además, Authorization: Bearer si el webhook tiene OAuth |
| Consulta posterior | No disponible | Listar perfiles y Detalle de un perfil |
Cómo migrar: cambia la URL base. Si usas searchErrors, puedes mantenerlo o pasar a searchTolerance. Si comparas tipPersona, usa "juridica" en lugar de "juridical". El detalle está en Cargar perfil en Compliance.
❗ Estructura de los errores
En la v3, todos los errores tienen la misma estructura y sus mensajes están en español:
{
"success": false,
"code": 403,
"error": "El plan no cuenta con el ayudante legal."
}
| Error | V2 | V3 |
|---|---|---|
401 de autenticación | {"error": "No token provided"} o {"error": "Token expirado", "details": ..., "errorType": ...} | {"success": false, "code": 401, "error": "El token de autenticación expiró. Solicita uno nuevo."} |
403 por plan | Algunos endpoints usaban la key message | Siempre la key error |
429 por límite de solicitudes | {"error": "...", "retryAfter": 900} | {"success": false, "code": 429, "error": "..."}; usa el header Retry-After para saber cuánto esperar |
400 de validación | Mensajes en inglés (ej: "query.nivel" must be ...), unidos por ". " | Mensajes en español (ej: El campo 'nivel' debe ser menor o igual a 50.), separados por un espacio |
500 interno | Varía según el endpoint | Ocurrió un error interno. Intenta nuevamente más tarde. |
Cómo migrar: lee siempre el mensaje desde error y usa code para decidir cómo reaccionar. Los errores comunes a todos los endpoints están en Errores.
🆘 Ayuda y soporte
Recursos disponibles
- 📖 Documentación completa v3
- 📖 Documentación completa v2
- 📚 Glosario de Términos v3 - Valores del bloque legal, CMF, Marshal y secciones fallidas
- 📚 Glosario de Términos v2 - Términos de los demás bloques del resumen
- ❓ Preguntas Frecuentes
- 🔐 Guía de Autenticación
¿Necesitas ayuda?
Si tienes dudas durante la migración:
- Consulta la documentación: la mayoría de las dudas están resueltas aquí.
- Revisa el glosario: para entender valores y campos específicos.
- Contacta a tu ejecutivo comercial: para dudas comerciales o de integración específicas.
- Contacta a soporte técnico: para problemas técnicos o errores.