Saltar al contenido principal

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.

Cambios principales que afectan tu integración
  1. URL base: /api/clients/v2/ → /api/clients/v3/.
  2. Carga de RUT (POST /helper/cargarRut): acepta includeMarshal para solicitar el análisis Marshal, data pasa a ser un objeto con rut y message, y un RUT que ya estaba en tu cartera responde 409.
  3. Resumen (GET /helper/resumen): el bloque legal pasa de objeto a arreglo de sociedades, ayudantesFallidos entrega códigos numéricos, se agrega ayudanteFallido, las secciones de fuentes fallidas sin información previa viajan con su estructura completa en lugar de omitirse, algunos campos de identificacion y bienes cambian de tipo, y compliance agrega marshal y estadoMarshal y usa tipoPersona: "juridica" en lugar de "juridical".
  4. Webhook de resumen (POST /webhook/profile/resumen): la solicitud acepta isMonitoring e includeMarshal; el body que recibes incluye success, usa el contrato v3 del resumen y se entrega aunque falle alguna fuente.
  5. Legal: la respuesta de GET /helper/legal/{rut}/mallaSocietaria cambia, y se documentan endpoints nuevos: Capas y Niveles de la Malla Societaria, y CMF.
  6. Compliance (GET /helper/compliance/{rut}): agrega la detección de Marshal y entrega periodo en formato DD-MM-YYYY.
  7. Marshal: nuevo endpoint POST /helper/compliance/{rut}/actualizarMarshal para solicitar un análisis Marshal de un RUT ya cargado, y endpoints para consultar las investigaciones y sus reportes (ver Marshal).
  8. Compliance por nombre: POST /webhook/compliance/cargarPerfil valida el body, acepta includeMarshal y entrega tipPersona como "juridica" en lugar de "juridical", y los perfiles cargados se pueden consultar con endpoints nuevos (ver Compliance por nombre).
  9. Errores: todos los errores usan la estructura { success, code, error } con mensajes en español, incluidos los 401 de autenticación, los 403 por plan y el 429 (ver Estructura de los errores).

📋 Resumen de cambios principales​

1. Cambio en la URL base​

VersiónURL baseEjemplo completo
V2https://prod.api.thesheriff.cl/api/clients/v2/https://prod.api.thesheriff.cl/api/clients/v2/helper/resumen?rut=76123456-0
V3https://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​

V2V3Cambios
POST /helper/cargarRutPOST /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/resumenPOST /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}/mallaSocietariaGET /helper/legal/{rut}/mallaSocietaria⚠️ Cambia la respuesta: socios, administradores, participaciones y extractos consolidados
❌ No disponibleGET /helper/legal/{rut}/capasMallaSocietaria✨ NUEVO: Malla societaria por niveles, paginada
❌ No disponibleGET /helper/legal/{rut}/capasMallaSocietaria/niveles✨ NUEVO: Niveles disponibles de la malla y cantidad de relaciones por nivel
❌ No disponibleGET /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 disponiblePOST /helper/compliance/{rut}/actualizarMarshal✨ NUEVO: Solicitud de un nuevo análisis Marshal para un RUT ya cargado
POST /webhook/compliance/cargarPerfilPOST /webhook/compliance/cargarPerfil⚠️ Body validado, searchTolerance, nuevo includeMarshal y entrega con OAuth
❌ No disponibleGET /compliance/perfiles✨ NUEVO: Lista de perfiles de compliance buscados por nombre
❌ No disponibleGET /compliance/perfiles/{id}✨ NUEVO: Resultado completo de un perfil de compliance
❌ No disponibleGET /compliance/perfiles/{id}/investigaciones✨ NUEVO: Investigaciones Marshal de un perfil de compliance
❌ No disponibleGET /marshal/investigaciones?rut={rut}✨ NUEVO: Investigaciones Marshal de un RUT
❌ No disponibleGET /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:

DatoV2V3
includeMarshalNo existebool, por defecto false. Solicita el análisis Marshal del RUT.
includeEquifaxSin validarDebe 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 cartera200409 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 409 como "ya estaba cargado", no como una falla.
  • Si usas Marshal, envía includeMarshal: true y maneja el 403 que 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​

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.casos y empresaEnUnDia.casos ahora están en legal[].extractos, con actuacion, fecha, cve, linkPdf y fuente ("DO" o "EEUD").
  • Los socios de cada publicación ahora están consolidados en legal[].socios, con sus roles en el arreglo tipos y el porcentaje como número en porcentaje.
  • Los administradores y representantes legales están en legal[].administradores.
  • mallaSocietariaExterna y mallaSocietariaInterna ahora se representan con legal[].participaciones (sociedades en las que participa) y legal[].socios (quiénes participan en ella). Para la malla completa por niveles, usa Capas de la Malla Societaria.
  • legal[].tieneCmf indica si la sociedad tiene registro en la CMF, que puedes consultar con CMF.
  • Si no hay información legal, legal es un arreglo vacío ([]).
  • legal mantiene su posición en la respuesta: después de cobranzaLaboral y antes de deudaBancaria.

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:

FuenteV2 (nombre)V3 (código)
Identificación (SII)"SII"101
Tamaño de empresa (solo persona jurídica)Nombre de la fuente102
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 fuente301
Boletín comercial: DicomNombre de la fuente302
Boletín laboral"Boletín Laboral"303
Mora previsional"Mora Previsional"401
Multas laborales"Multa Laboral"402
Legal"Legal"501
Información del sistema financieroNombre de la fuente701
Bienes: propiedades"Propiedades"801
Bienes: vehículos"Vehículos"802
Análisis Marshal (solo webhook)No existe1101

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​

CampoV2V3
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 cantidadDocumentosnull si no hay0 si no hay
identificacion.tamanoEmpresaSii.cantidadTrabajadoresNúmero o "Sin información"Número; null si no se informa
bienes.propiedades.tasacionTotalTexto (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:

CampoDescripción
marshaltrue 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:

CampoV2V3
isMonitoringNo existe (siempre es consulta)true carga el RUT en monitoreo. Por defecto false.
includeMarshalNo existeSolicita 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"
}
DatoV2V3
Publicaciones de Empresa en un DíaempresaEnUnDia[]extractos[] con fuente: "EEUD"
Publicaciones del Diario OficialdiarioOficial[]extractos[] con fuente: "DO"
Sociossocios[] dentro de cada publicaciónsocios[] consolidados, con porcentaje numérico, vigente y tipos
Administradoresadministradores[] dentro de cada publicaciónadministradores[] consolidados
Participaciones en otras sociedadesparticipaciones[][] (listas anidadas de rut/sociedad)participaciones[] plano, con nombre, rut, porcentaje y tipos
Registro CMFNo disponibletieneCmf y el endpoint CMF
Persona naturalEndpoint 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 modo beneficiariosFinales o ampliada.
  • 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:

DatoV2V3
Detección PEP de MarshalNo disponiblepepChile.marshal.detectado y familiaresPep.marshal.detectado
Hallazgos de MarshalNo disponibleAl inicio de noticias.coincidencias, sumados a totalCoincidencias
periodoTal como lo entrega la fuenteFechas 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 periodo como fecha, ajusta el formato a DD-MM-YYYY.
  • Si comparas tipoPersona, usa "juridica" en lugar de "juridical".
  • Si no usas Marshal, marshal.detectado viaja en null y noticias no 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:

EndpointUso de Marshal
POST /helper/cargarRutincludeMarshal: true solicita el análisis al cargar un RUT que no estaba activo en tu cuenta.
POST /webhook/profile/resumenincludeMarshal: 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/resumencompliance.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/cargarPerfilincludeMarshal: 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:

DatoV2V3
BodySin validaciónValidado: solo fullName es obligatorio; isJuridicalPerson, isMonitoring e includeMarshal por defecto false
Tolerancia de búsquedasearchErrorssearchTolerance (se sigue aceptando searchErrors)
Análisis MarshalNo disponibleincludeMarshal: 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 entregaHeaders configuradosAdemás, Authorization: Bearer si el webhook tiene OAuth
Consulta posteriorNo disponibleListar 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."
}
ErrorV2V3
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 planAlgunos endpoints usaban la key messageSiempre 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ónMensajes 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 internoVaría según el endpointOcurrió 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​

¿Necesitas ayuda?​

Si tienes dudas durante la migración:

  1. Consulta la documentación: la mayoría de las dudas están resueltas aquí.
  2. Revisa el glosario: para entender valores y campos específicos.
  3. Contacta a tu ejecutivo comercial: para dudas comerciales o de integración específicas.
  4. Contacta a soporte técnico: para problemas técnicos o errores.