Cargar un perfil en Compliance

Este endpoint carga un perfil de compliance a partir de un nombre o razón social y envía a tu webhook el resultado de su búsqueda: malla societaria, PEP, familiares de PEP, funcionarios públicos, listas internacionales, penal y noticias. Opcionalmente, puedes incluir en la misma entrega el análisis Marshal del perfil. La solicitud responde de inmediato con un webhookId, y Sheriff envía el resultado a tu webhook cuando está listo.

Debes tener configurado un webhook activo de tipo Carga Perfil (ver Configurar Webhooks).
Si el perfil es nuevo, se aplica un cobro conforme a tu acuerdo comercial. Si ya existe un perfil completado con los mismos datos de búsqueda, recibes su resultado sin el cobro de una búsqueda nueva (ver Perfiles existentes).
El perfil queda disponible en la plataforma y en los endpoints de Compliance por nombre.

Qué cambia respecto a la v2

El body se valida: todos los campos son opcionales salvo fullName, y la tolerancia se envía en searchTolerance (se sigue aceptando searchErrors).
Nuevo campo includeMarshal: la entrega incluye el bloque marshal con el resultado del análisis.
tipPersona usa "juridica" en lugar de "juridical".
Si tu webhook tiene autenticación OAuth, la entrega incluye el header Authorization: Bearer.
Puedes consultar el resultado después con Detalle de un perfil.

Ver la Guía de Migración.

Detalle de API

Request

URL: /webhook/compliance/cargarPerfil
Método: POST

Body

Valor	Tipo	Es requerido	Descripción
`fullName`	`string`	Sí	Nombre completo de la persona natural o razón social de la persona jurídica (hasta 500 caracteres). Para una persona natural, debe incluir al menos un nombre y un apellido.
`isJuridicalPerson`	`bool`	No	`true` para persona jurídica; `false` para persona natural. Por defecto `false`.
`searchTolerance`	`number`	No	Tolerancia de la búsqueda: `0` (exacta), `1` o `2` (más flexibles, incluyen nombres parecidos). Por defecto `0`. También se acepta como `searchErrors`.
`isMonitoring`	`bool`	No	`true` carga el perfil en monitoreo; `false`, como consulta. Por defecto `false`.
`country`	`string`	No	Código del país de la búsqueda (ej: `CL`). Si envías un país, la búsqueda incluye también las listas por país. Los códigos están en el Glosario de la API v2.
`includeMarshal`	`bool`	No	`true` solicita el análisis Marshal del perfil. Requiere que tu plan cuente con Marshal. Por defecto `false`.

Ejemplos de body:

Persona jurídica
{
  "fullName": "Empresa Ficticia SpA",
  "isJuridicalPerson": true,
  "searchTolerance": 0,
  "isMonitoring": false
}

Persona natural con Marshal
{
  "fullName": "Juan Pérez Soto",
  "isJuridicalPerson": false,
  "searchTolerance": 1,
  "isMonitoring": true,
  "country": "CL",
  "includeMarshal": true
}

Headers requeridos

Content-Type: application/json
Authorization: Bearer {tu-token}

Ejemplo request con curl

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/clients/v3/webhook/compliance/cargarPerfil' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9EjemploDeToken123' \
  -d '{
    "fullName": "Juan Pérez Soto",
    "isJuridicalPerson": false,
    "searchTolerance": 1,
    "isMonitoring": true,
    "country": "CL",
    "includeMarshal": true
  }'

Respuesta inicial

La respuesta inicial es la misma para personas naturales y jurídicas.

Status code: 200
Example response body:

{
  "success": true,
  "data": {
    "message": "Su solicitud ha sido recibida y está siendo procesada",
    "webhookId": 123
  }
}

Campo	Tipo	Descripción
`success`	`boolean`	Indica si la solicitud fue aceptada.
`data.message`	`string`	Mensaje informativo.
`data.webhookId`	`number`	Identificador de la solicitud. Viaja también en la entrega, para que puedas asociarla a esta solicitud. Cada solicitud recibe un `webhookId` nuevo.

Entrega del resultado

Cuando el resultado está listo, Sheriff hace un POST a la URL configurada en tu webhook Carga Perfil:

Formato: el body es un JSON comprimido con gzip. Tu servidor debe aceptar el header Content-Encoding: gzip y descomprimir el body.
Headers: Content-Type: application/json, Content-Encoding: gzip, los headers que configuraste en el webhook y, si el webhook tiene autenticación OAuth, Authorization: Bearer {token}.
Intentos: la entrega se envía una sola vez. Si tu servidor no responde o falla, no se reintenta. En ese caso, consulta el resultado con Detalle de un perfil.

Formato de la entrega

Campo	Tipo	Descripción
`webhookId`	`number`	El mismo identificador entregado en la respuesta inicial.
`estado`	`string`	Siempre `"SUCCESS"` en la entrega del resultado.
`esPerfilNuevo`	`boolean`	`true` si se creó un perfil nuevo; `false` si se usó un perfil existente (ver Perfiles existentes).
`marshal`	`object`	Solo con `includeMarshal: true`: resultado del análisis Marshal (ver Análisis Marshal).
resto		Los mismos campos de `resultado` en Detalle de un perfil: `nombreCompleto`, `tipPersona`, `toleranciaBusqueda`, `resumen`, `riesgo` y los `datos` y `total` de cada fuente.

Diferencias por tipo de persona

Aspecto	Persona jurídica (`isJuridicalPerson: true`)	Persona natural (`isJuridicalPerson: false`)
`fullName`	Razón social completa; se convierte a mayúsculas	Debe tener al menos un nombre y un apellido
`datosPepChile`, `datosFuncionarioPublico`, `datosFamiliarPep`	Siempre `[]`, con sus totales en `0`: estas búsquedas no se hacen para personas jurídicas	Coincidencias encontradas
`tipPersona`	`"juridica"`	`"natural"`

Entrega para persona natural (con Marshal)

{
  "webhookId": 123,
  "estado": "SUCCESS",
  "nombreCompleto": "JUAN PEREZ SOTO",
  "tipPersona": "natural",
  "toleranciaBusqueda": 1,
  "esPerfilNuevo": true,
  "resumen": {
    "mallaSocietaria": { "totalResultados": 1, "riesgo": "free" },
    "pepChile": { "totalResultados": 1, "riesgo": "critical" },
    "funcionariosPublicos": { "totalResultados": 0, "riesgo": "free" },
    "pepChileFamiliares": { "totalResultados": 0, "riesgo": "free" },
    "listasInternacionales": { "totalResultados": 0, "riesgo": "free" },
    "penal": { "totalResultados": 0, "riesgo": "free" },
    "noticias": { "totalResultados": 0, "riesgo": "free" }
  },
  "riesgo": "critical",
  "datosMallaSocietaria": [
    {
      "nombreSociedad": "EMPRESA FICTICIA SPA",
      "rutSociedad": "76123456-0",
      "nombreSocio": "JUAN PEREZ SOTO",
      "rutSocio": "11111111-1",
      "fecha": "2021-06-02",
      "socios": [
        {
          "nombre": "JUAN PEREZ SOTO",
          "rut": "11111111-1",
          "domicilio": null,
          "tipoDeParticipacion": "Socio",
          "cargo": null,
          "cargoEjecutivoPrincipal": null,
          "fechaNombramiento": null,
          "porcentajeParticipacion": "70"
        }
      ],
      "extractos": [],
      "ultimaFecha": "2021-06-02",
      "fuente": "Empresa en un Día"
    }
  ],
  "totalMallaSocietaria": 1,
  "datosPepChile": [
    {
      "nombre": "JUAN PEREZ SOTO",
      "cargo": "CONCEJAL",
      "institucion": "MUNICIPALIDAD FICTICIA",
      "periodo": "2018 - 2022"
    }
  ],
  "totalPepChile": 1,
  "datosFuncionarioPublico": [],
  "totalFuncionarioPublico": 0,
  "datosFamiliarPep": [],
  "totalFamiliarPep": 0,
  "datosListasInternacionales": [],
  "totalListasInternacionales": 0,
  "datosPenal": [],
  "totalPenal": 0,
  "datosNoticias": [],
  "totalNoticias": 0,
  "marshal": {
    "id": "0b6c1d9e-7a7f-4a2b-9c55-3f1e2d4a5b6c",
    "estado": "COMPLETADA",
    "motivo": null,
    "detalleMotivo": null,
    "riesgo": "ALTO",
    "indicadorPep": "SI",
    "totalHallazgos": 2,
    "pais": "Chile"
  }
}

Entrega para persona jurídica (sin Marshal)

{
  "webhookId": 124,
  "estado": "SUCCESS",
  "nombreCompleto": "EMPRESA FICTICIA SPA",
  "tipPersona": "juridica",
  "toleranciaBusqueda": 0,
  "esPerfilNuevo": false,
  "resumen": {
    "mallaSocietaria": { "totalResultados": 1, "riesgo": "free" },
    "pepChile": { "totalResultados": 0, "riesgo": "free" },
    "funcionariosPublicos": { "totalResultados": 0, "riesgo": "free" },
    "pepChileFamiliares": { "totalResultados": 0, "riesgo": "free" },
    "listasInternacionales": { "totalResultados": 1, "riesgo": "medium" },
    "penal": { "totalResultados": 0, "riesgo": "free" },
    "noticias": { "totalResultados": 0, "riesgo": "free" }
  },
  "riesgo": "medium",
  "datosMallaSocietaria": [
    {
      "nombreSociedad": "EMPRESA FICTICIA SPA",
      "rutSociedad": "76123456-0",
      "nombreSocio": null,
      "rutSocio": null,
      "fecha": "2021-06-02",
      "socios": [],
      "extractos": [],
      "ultimaFecha": "2021-06-02",
      "fuente": null
    }
  ],
  "totalMallaSocietaria": 1,
  "datosPepChile": [],
  "totalPepChile": 0,
  "datosFuncionarioPublico": [],
  "totalFuncionarioPublico": 0,
  "datosFamiliarPep": [],
  "totalFamiliarPep": 0,
  "datosListasInternacionales": [
    {
      "nombre": "EMPRESA FICTICIA SPA",
      "lista": "CMF - Sanciones",
      "enlace": "https://www.cmfchile.cl/sitio/EJEMPLO"
    }
  ],
  "totalListasInternacionales": 1,
  "datosPenal": [],
  "totalPenal": 0,
  "datosNoticias": [],
  "totalNoticias": 0
}

Cuando la búsqueda tiene country, cada elemento de datosListasInternacionales incluye además tipo, codigoPais y activo (ver Detalle de un perfil).

Análisis Marshal

Con includeMarshal: true, Sheriff solicita el análisis Marshal del perfil y la entrega espera su resultado:

Requiere que tu plan cuente con Marshal; de lo contrario, la solicitud responde 403.
Si el perfil ya tiene un análisis Marshal en curso, la entrega espera ese análisis.
La entrega se envía cuando terminan la búsqueda y el análisis Marshal, o cuando pasan 15 minutos desde la solicitud. Si se cumple el plazo, el bloque marshal viaja con estado: "EN_CURSO" y puedes consultar el resultado final en Investigaciones de un perfil.
El análisis se cobra cuando se completa, conforme a tu acuerdo comercial. Si falla o no se inicia, no se cobra.

Campos dentro de marshal:

Campo	Tipo	Descripción
`id`	`string`	Identificador de la investigación (UUID), para consultar su reporte en Detalle de una investigación; `null` si no se inició.
`estado`	`string`	`EN_CURSO`, `COMPLETADA` o `FALLIDA`.
`motivo`	`string`	Solo si `FALLIDA`: motivo de la falla (ver Motivos de falla), o `NO_LANZADA` si el análisis no pudo iniciarse.
`detalleMotivo`	`string`	Solo si `FALLIDA`: descripción del motivo.
`riesgo`	`string`	Solo si `COMPLETADA`: nivel de riesgo del análisis (ej: `"ALTO"`).
`indicadorPep`	`string`	Solo si `COMPLETADA`: indicador PEP del análisis (ej: `"NO"`, `"SI"`).
`totalHallazgos`	`number`	Solo si `COMPLETADA`: cantidad de hallazgos en medios.
`pais`	`string`	País del análisis, o `"Global"` si se buscó sin país; `null` si no se inició.

Si el análisis no pudo iniciarse (por ejemplo, porque tu plan no tiene cupo de investigaciones Marshal), la entrega se envía igual, con este bloque:

{
  "marshal": {
    "id": null,
    "estado": "FALLIDA",
    "motivo": "NO_LANZADA",
    "detalleMotivo": "No se pudo iniciar la investigación Marshal.",
    "riesgo": null,
    "indicadorPep": null,
    "totalHallazgos": null,
    "pais": null
  }
}

El resumen y el riesgo de la entrega corresponden al momento en que terminó la búsqueda: no se recalculan cuando el análisis Marshal termina después. El resultado del análisis viaja en el bloque marshal, y el perfil actualizado se consulta con Detalle de un perfil.

Perfiles existentes

Si ya existe en tu cuenta un perfil completado con el mismo fullName, tipo de persona, searchTolerance y country, la solicitud usa ese perfil:

No se crea un perfil nuevo ni se cobra una búsqueda nueva. Si envías isMonitoring: true, el perfil puede pasar a monitoreo, que se cobra conforme a tu acuerdo comercial.
La entrega llega con esPerfilNuevo: false.

Envía country siempre con el mismo valor (por ejemplo, siempre CL) para que Sheriff reconozca el perfil existente.

Notificación de error

Si la búsqueda no pudo completarse, o si tu servidor responde con un error a la entrega, recibirás una notificación de error en el mismo webhook. Su body no viaja comprimido:

{
  "webhookId": 123,
  "status": "FAILED",
  "error": "Error al procesar el perfil: JUAN PEREZ SOTO",
  "details": "500 - Internal Server Error",
  "fullName": "JUAN PEREZ SOTO",
  "requestBodySizeInBytes": 18432
}

Campo	Tipo	Descripción
`webhookId`	`number`	El mismo identificador entregado en la respuesta inicial.
`status`	`string`	Siempre `"FAILED"` en una notificación de error.
`error`	`string`	Descripción del error.
`details`	`string`	Detalle técnico del error.
`fullName`	`string`	Nombre buscado.
`requestBodySizeInBytes`	`number` o `string`	Tamaño en bytes del body que se intentó entregar, o `"Tamaño desconocido"` si no se conoce.

Cómo distinguir una entrega de una notificación de error

Una entrega del resultado trae estado: "SUCCESS"; una notificación de error trae status: "FAILED". Evalúa ambos campos antes de procesar el body.

Con includeMarshal: true, si la entrega falla, no se envía una notificación de error. En ese caso, consulta el resultado con Detalle de un perfil.

Errores de la solicitud

Además de los errores comunes, este endpoint puede responder:

400 - Parámetros inválidos

Algún campo del body falta o no es válido. El mensaje indica el campo rechazado; si hay más de uno, los mensajes vienen uno a continuación del otro, separados por un espacio. Corrige los campos indicados y vuelve a enviar la solicitud.

Cuándo ocurre	Mensaje en `error`
Falta `fullName` o viene vacío	`El nombre es requerido.`
`isJuridicalPerson` no booleano	`El campo 'isJuridicalPerson' debe ser verdadero o falso.`
`isMonitoring` no booleano	`El campo 'isMonitoring' debe ser verdadero o falso.`
`includeMarshal` no booleano	`El campo 'includeMarshal' debe ser verdadero o falso.`
`searchTolerance` mayor a 2	`El campo 'searchTolerance' debe ser menor o igual a 2.`
`searchErrors` no numérico	`El campo 'searchErrors' debe ser un número.`
`country` inválido	`El país no es válido.`

{
  "success": false,
  "code": 400,
  "error": "El nombre es requerido."
}

400 - Nombre de persona natural incompleto

Para una persona natural (isJuridicalPerson: false), fullName no incluye al menos un nombre y un apellido. Completa el nombre y vuelve a enviar la solicitud.

{
  "success": false,
  "code": 400,
  "error": "Los nombres de personas naturales deben tener mínimo un Nombre y un Apellido."
}

400 - Nombre no procesable

No fue posible interpretar el nombre enviado en fullName. Revisa que esté bien escrito y vuelve a intentarlo.

{
  "success": false,
  "code": 400,
  "error": "No se pudo procesar el nombre con IA. Revisá que esté bien escrito e intentá nuevamente."
}

400 - Usuario sin permiso

El usuario del token tiene rol de observador, que no puede cargar perfiles de Compliance por API.

{
  "success": false,
  "code": 400,
  "error": "No tienes permiso para cargar perfiles de Compliance por API."
}

400 - Sin webhook configurado

Tu cuenta no tiene un webhook activo de tipo Carga Perfil. Configúralo o actívalo en la plataforma (ver Configurar Webhooks).

{
  "success": false,
  "code": 400,
  "error": "Esta corporación no tiene activo el Webhook para cargar perfiles de Compliance por API."
}

400 - Nombre fuera del catálogo de pruebas

Tu cuenta opera en modo sandbox y el nombre enviado no pertenece al catálogo de pruebas. Usa un nombre del catálogo.

{
  "success": false,
  "code": 400,
  "error": "Esta cuenta opera en modo sandbox y sólo puede consultar los perfiles del catálogo de pruebas. \"JUAN PÉREZ SOTO\" no pertenece al catálogo."
}

400 / 403 / 503 - Cupo o plan

Se devuelven en planes prepago cuando tu plan no permite una nueva búsqueda de compliance por nombre. No se validan si la solicitud usa un perfil existente ni si la carga es en monitoreo (isMonitoring: true). El mensaje en error indica el motivo y qué hacer:

Código	Cuándo ocurre	Mensaje en `error`
`400`	No quedan búsquedas en la bolsa	`Has consumido el total de búsquedas de Compliance por nombre disponibles en tu plan. Escribe al área comercial para solicitar más búsquedas de Compliance por nombre.`
`403`	El plan no incluye búsquedas de compliance por nombre	`Tu plan no incluye búsquedas de Compliance por nombre. Si necesitas esta función, contacta a tu ejecutivo comercial.`
`403`	El plan venció	`Tu plan venció. Para renovarlo, contacta a tu ejecutivo comercial.`
`403`	El plan no está vigente	`Tu plan ya no está vigente. Contacta a tu ejecutivo comercial para reactivarlo.`
`503`	No se pudo consultar el saldo del plan	`No pudimos validar el saldo de tu plan en este momento. Intenta nuevamente en unos minutos.`

{
  "success": false,
  "code": 400,
  "error": "Has consumido el total de búsquedas de Compliance por nombre disponibles en tu plan. Escribe al área comercial para solicitar más búsquedas de Compliance por nombre."
}

401 - No autorizado

El token no se envió, expiró o no es válido (ver Errores de autenticación). Si expiró, solicita uno nuevo en Obtener Token.

{
  "success": false,
  "code": 401,
  "error": "El token de autenticación no es válido."
}

403 - Plan sin Marshal

Enviaste includeMarshal: true, pero tu plan no cuenta con Marshal.

{
  "success": false,
  "code": 403,
  "error": "El plan no cuenta con Marshal."
}

429 - Demasiadas solicitudes

Superaste el límite de solicitudes (ver Rate Limits). Espera los segundos que indica el header Retry-After antes de reintentar.

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

500 - Error interno del servidor

Ocurrió un error inesperado. Intenta nuevamente más tarde.

{
  "success": false,
  "code": 500,
  "error": "Ocurrió un error interno. Intenta nuevamente más tarde."
}

Detalle de API​

Request​

Body​

Headers requeridos​

Ejemplo request con curl​

Respuesta inicial​

Entrega del resultado​

Formato de la entrega​

Diferencias por tipo de persona​

Entrega para persona natural (con Marshal)​

Entrega para persona jurídica (sin Marshal)​

Análisis Marshal​

Perfiles existentes​

Notificación de error​

Errores de la solicitud​

400 - Parámetros inválidos​

400 - Nombre de persona natural incompleto​

400 - Nombre no procesable​

400 - Usuario sin permiso​

400 - Sin webhook configurado​

400 - Nombre fuera del catálogo de pruebas​

400 / 403 / 503 - Cupo o plan​

401 - No autorizado​

403 - Plan sin Marshal​

429 - Demasiadas solicitudes​

500 - Error interno del servidor​