Saltar al contenido principal

Descarga Resumen de Perfil

Este webhook entrega el resumen consolidado de un perfil en tus URLs configuradas. Si el perfil no está cargado en tu cuenta, Sheriff lo carga primero y entrega cuando termine. Si ya está cargado y vigente, encola la entrega de inmediato.

Webhook Preconfigurado

Antes de usar este endpoint, debes tener al menos una configuración activa de tipo Descarga Resumen de Perfil desde el dashboard web en Integraciones → Webhooks. Si no hay ninguna activa, la API retornará un error 400. Recuerda que puedes tener hasta 3 configuraciones activas y el mismo resumen se envía a cada destino de forma independiente, todas vinculadas al mismo triggerId.

Respuesta Asíncrona

Este endpoint responde inmediatamente con un 202 Accepted retornando el identificador del evento (triggerId). La entrega real ocurre en segundo plano y puedes auditarla desde el dashboard en Integraciones → Webhooks.

Endpoint para Disparar el Webhook​

POST /v1/webhook/perfiles/resumen

Parámetros del Body​

ParámetroTipoRequeridoPor DefectoDescripción
taxIdstringSí-Documento del perfil cuyo resumen se enviará (ej: 20XXXXXX056).
docTypestringSí-Tipo de documento del taxId. Puede ser RUC, DNI o CE.
isMonitoringbooleanNotrueAplica solo si el perfil necesita ser cargado. true deja el perfil monitoreado; false lo carga como consulta (visible 48 horas).

Ejemplo de Solicitud​

curl -X POST https://api-public.thesheriff.pe/v1/webhook/perfiles/resumen \
  -H "Authorization: Bearer <TU_TOKEN_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
        "taxId": "20100000001",
        "docType": "RUC",
        "isMonitoring": true
      }'

Comportamiento según el estado del perfil​

Estado del perfil para tu corporaciónAcciónTiempo aprox. de entrega
Activo y al díaEncola la entrega de inmediato sin recargar.Segundos
No cargado / vencidoInicia la carga del perfil. El evento queda en LOADING_PROFILE y se entrega al terminar.Variable (1 - 45 segundos)
Carga en curso (otro trigger)Si se inicia la carga del mismo perfil que ya se está cargando. Retorna 409 Conflict.—

Payload que Recibirás en tus URLs​

Además de los campos comunes a todo webhook (triggerId, data), este tipo agrega información sobre el estado de la carga del perfil:

{
  "triggerId": "trg_a1b2c3d4e5f6789012345678",
  "taxId": "20100000001",
  "profileLoadStatus": "succeeded",
  "failedSubhelpers": null,
  "data": {
    /* mismo objeto que retorna el endpoint público de Resumen de Perfil */
  }
}

Campos del Payload​

CampoTipoDescripción
triggerIdstringIdentificador único del evento. Mismo valor que en el header X-Sheriff-Trigger-Id.
taxIdstringDocumento del perfil enviado.
profileLoadStatus'succeeded' | 'partial' | 'failed'Indica qué tan completa quedó la carga del perfil. Deprecación programada — ver aviso abajo.
failedSubhelpersstring[] | nullLista de subhelpers que fallaron durante la carga. Solo viene poblada cuando profileLoadStatus === 'partial'; en los otros casos null.
dataobjectResumen del perfil. Misma estructura que la respuesta del endpoint público de Resumen de Perfil.
profileLoadStatus y failedSubhelpers se deprecarán

Con la versión de payload v2, el estado de carga viaja dentro de data con más detalle: campos estado y subhelpers_fallidos a nivel raíz del resumen, más un statusCode por sección (ver Estados de Carga). Los campos del envelope se mantienen por compatibilidad con v1, pero se eliminarán en una fecha que anunciaremos cuando v2 sea estable. Si consumes estos campos, planifica leer el estado desde data al migrar a v2.

Estado de carga vs estado del evento

El estado dentro de data (payload v2) describe la calidad del dato (si se logró cargar el perfil completamente). El estado del evento (SUCCEEDED/FAILED en el dashboard) describe la salud de la entrega HTTP. Son dimensiones independientes: una entrega puede ser SUCCEEDED en el dashboard (tu servidor respondió 2xx) y a la vez traer estado: 'failed' en el resumen (porque el perfil no pudo cargarse).

Garantía de entrega

Aunque la carga del perfil falle (total o parcialmente) o tome más tiempo del esperado (más de 30 minutos), Sheriff siempre entregará el webhook con el estado real de la carga (profileLoadStatus en el envelope y, con payload v2, estado dentro de data). Tu servidor nunca queda esperando indefinidamente una respuesta que no va a llegar.

Ejemplo — Perfil con fallos parciales (payload v2)​

{
  "triggerId": "trg_a1b2c3d4e5f6789012345678",
  "taxId": "20100000001",
  "data": {
    "taxId": "20100000001",
    "activo": true,
    "estado": "partial",
    "subhelpers_fallidos": ["DeudasMicroFinanzas", "EdictosJudiciales"],
    "finanzas": { "statusCode": "SH11", "data": { /* ... */ } },
    "judicial": { "statusCode": "SH50", "data": {} }
    /* resto de las secciones */
  }
}
Estructura de data

El contenido de data es exactamente el mismo que retorna el endpoint público de Resumen de Perfil, en la versión del payload que tenga elegida la configuración que recibe la entrega (v1 por defecto, v2 en beta). Consulta esa página para ver el detalle de cada campo del resumen. Evitamos duplicar la documentación para que siempre estés viendo la referencia más actualizada.

Respuestas al Disparar el Webhook​

Estas son las respuestas que recibirás inmediatamente al disparar el webhook desde la API. Cada una incluye el triggerId del evento, que te permitirá correlacionar después las entregas que lleguen a tus URLs configuradas con esta llamada inicial.

Ejemplo de Respuesta — Perfil ya activo​

{
  "statusCode": 202,
  "data": {
    "triggerId": "trg_a1b2c3d4e5f6789012345678",
    "message": "Carga existente. Evento recibido."
  }
}

Ejemplo de Respuesta — Perfil cargándose​

{
  "statusCode": 202,
  "data": {
    "triggerId": "trg_a1b2c3d4e5f6789012345678",
    "message": "Solicitud de carga recibida. Evento recibido."
  }
}
Correlación con la Entrega

Cada llamada al endpoint genera un único triggerId que agrupa todas las entregas del evento. Tu servidor recibirá ese mismo triggerId en el header X-Sheriff-Trigger-Id y dentro del body, en cada una de las configuraciones activas. Esto te permite correlacionar la respuesta de este endpoint con todas las entregas que efectivamente lleguen a tus URLs.

Errores Comunes​

400 - No hay webhook configurado​

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "No hay webhook activo configurado para este evento."
}

Solución: ingresa al dashboard web y crea/activa al menos una configuración de webhook de tipo Descarga Resumen de Perfil.

400 - taxId inválido o no coincide con docType​

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "El RUC '12345' no es válido."
}

Solución: verifica el formato del taxId y que coincida con el docType enviado:

  • RUC: 11 dígitos comenzando con 10, 15, 17 o 20.
  • DNI: 8 dígitos numéricos.
  • CE: alfanumérico de 9 a 12 caracteres.

409 - Carga en curso​

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Ya hay una carga en curso para el taxId 20100000001."
}

Solución: ya hay un evento en estado LOADING_PROFILE para este taxId. Espera a que se entregue (o falle) antes de disparar nuevamente. Puedes revisar el detalle del evento desde el dashboard en Integraciones → Webhooks.