Version: v2 (beta)

Migración v1 → v2

La v2 de la API moderniza el resumen de perfil en dos secciones y agrega el estado de carga:

finanzas, alineada con el nuevo modelo de información del sistema financiero de Sheriff: la deuda se presenta por situación (vigente, refinanciada/reestructurada, vencida, judicial) y por período, junto con la peor calificación, los días de atraso y el bloque de codeudores y avales en dos sentidos.
comex, alineada con la nueva vista de comercio exterior: tres ventanas anuales ancladas al corte de publicación de aduanet, con número de operaciones, principal país y principal partida arancelaria.
Estado de carga del perfil: el resumen indica qué tan completa quedó la carga (estado, subhelpers_fallidos) y cada sección viene envuelta en { statusCode, data } para distinguir "sin datos" de "fuente caída", "en carga" o "no contratado".

v2 está en beta

/v2 ya responde en paralelo a /v1 y puedes probarla, pero su contrato todavía se está moviendo: vienen más cambios antes de declararla estable. No integres producción contra v2 todavía — quédate en v1, que sigue estable y sin fecha de deprecación. Te avisaremos cuando v2 quede estable y este sea el momento de migrar.

Qué cambia

El resumen de perfil cambia en tres frentes: las secciones finanzas y comex, y la envoltura de estado de carga que ahora llevan todas las secciones. El resto de los recursos (autenticacion, carga de perfiles y webhooks) se comporta exactamente igual en /v2 que en /v1.

	v1	v2
Endpoint	`GET /v1/perfiles/:taxId/resumen`	`GET /v2/perfiles/:taxId/resumen`
Estado	Estable — versión vigente, sin fecha de deprecación	Beta

Sección `finanzas`

Campos que desaparecen en v2

Campo v1	Reemplazo en v2
`finanzas.variaciones_financieras` (montos por tramo de días de mora)	`finanzas.situacion` — la deuda por situación en tres períodos (`actual`, `seis_meses`, `doce_meses`), con directa, indirecta y `exposicion_total`
`finanzas.fechas_financieras`	`finanzas.situacion.<periodo>.periodo` — cada período lleva su propia fecha

Campos nuevos en v2

Campo	Descripción
`finanzas.peor_calificacion`	Peor calificación del último período (`{calificacion, porcentaje}`). `SCAL` = sin calificación.
`finanzas.max_dias_vencidos`	Días de atraso máximos reportados en el último período.
`finanzas.situacion`	Situación de la deuda por período. Cada período incluye `vigente`, `ref_rees`, `vencida`, `judicial`, `otros`, `directa`, `indirecta`, `exposicion_total`, `linea_credito`, `castigada`, `garantias` y `provisiones`.
`finanzas.codeudores_avales`	Codeudores y avales en dos sentidos: `a_favor` (terceros que respaldan al perfil) y `como_garante` (obligaciones de terceros por las que el perfil responde — exposición contingente, no suma a `exposicion_total`). Cada sentido trae totales, conteos de contrapartes distintas y `vinculos[]`; siempre presente, con listas vacías si no hay vínculos. Es del último corte disponible (`corte`), no una serie mensual.

Campos que se mantienen

finanzas.calificaciones_financieras — mismo shape que en v1 (distribución porcentual de calificaciones).
finanzas.ultima_actualizacion — mismo significado.

Semántica de los valores

null = sin dato: garantías/provisiones no reportadas, o período sin histórico. Los montos que la fuente no reporta van en 0.
exposicion_total = directa + indirecta. La linea_credito es cupo disponible no desembolsado y la castigada está fuera de balance: ninguna de las dos suma a la exposición.
finanzas.situacion puede venir null durante la transición si un perfil aún no fue reprocesado con el modelo nuevo; peor_calificacion se entrega igualmente (derivada de la distribución de calificaciones). El dato se completa con la siguiente actualización del perfil (consulta nueva o monitoreo mensual).
En codeudores_avales, la calificacion de un vínculo viene solo donde la fuente la entrega: los vínculos de rol aval la traen de su entidad acreedora; los de rol codeudor van con null porque la fuente no la incluye en ese feed — no se rellena ni se deriva.

Ejemplo del bloque `finanzas` en v2

"finanzas": {
  "ultima_actualizacion": "2026-01-09T03:00:00.000Z",
  "peor_calificacion": { "calificacion": "NOR", "porcentaje": 100 },
  "max_dias_vencidos": 0,
  "situacion": {
    "actual": {
      "periodo": "2025-12-01",
      "vigente": 160487612,
      "ref_rees": 0,
      "vencida": 0,
      "judicial": 0,
      "otros": 0,
      "directa": 160487612,
      "indirecta": 964497446,
      "exposicion_total": 1124985058,
      "linea_credito": 44773271,
      "castigada": 0,
      "garantias": 2111161250,
      "provisiones": null
    },
    "seis_meses": { "...": "mismo shape que actual" },
    "doce_meses": null
  },
  "calificaciones_financieras": [
    { "calificacion": "NOR", "porcentaje": 100 }
  ],
  "codeudores_avales": {
    "corte": "2025-12",
    "a_favor": {
      "total": 44793056,
      "por_aval": 44793056,
      "por_codeudor": 0,
      "avales": 1,
      "codeudores": 0,
      "contrapartes": 1,
      "vinculos": [
        {
          "rol": "aval",
          "contraparte": { "doc": "20567788990", "tipo_doc": "RUC", "nombre": "HOLDING RESPALDO SA" },
          "entidad": "BANCO A",
          "monto": 44793056,
          "calificacion": "NOR"
        }
      ]
    },
    "como_garante": {
      "total": 3322500,
      "por_aval": 3180000,
      "por_codeudor": 142500,
      "avales": 1,
      "codeudores": 1,
      "contrapartes": 2,
      "vinculos": [
        {
          "rol": "aval",
          "contraparte": { "doc": "20481122334", "tipo_doc": "RUC", "nombre": "AGROEXPORTADORA DEL NORTE SAC" },
          "entidad": "BANCO A",
          "monto": 3180000,
          "calificacion": "CPP"
        },
        {
          "rol": "codeudor",
          "contraparte": { "doc": "20334455667", "tipo_doc": "RUC", "nombre": "TRANSPORTES UNIDOS SRL" },
          "entidad": "CAJA C",
          "monto": 142500,
          "calificacion": null
        }
      ]
    }
  }
}

Sección `comex`

Campos que desaparecen en v2

Campo v1	Reemplazo en v2
`comex.resumen[].monto_ultimo_periodo` / `monto_seis_meses_anteriores` / `monto_doce_meses_anteriores` (montos de un solo mes)	`comex.resumen[].ventanas[].monto_soles` — el monto acumulado de cada ventana de 12 meses, convertido a soles mes a mes
`comex.resumen[].fecha_ultimo_periodo` / `fecha_seis_meses_anteriores` / `fecha_doce_meses_anteriores`	`comex.resumen[].ventanas[].desde` / `hasta` — cada ventana declara su rango, anclado al `corte_publicacion`
`comex.resumen[].variacion_seis_meses` / `variacion_doce_meses` (diferencias absolutas entre meses)	`comex.resumen[].ventanas[].variacion_porcentaje` — variación % entre ventanas consecutivas

Campos nuevos en v2

Campo	Descripción
`comex.es_importador` / `comex.es_exportador`	Actividad en la ventana actual de cada flujo. `null` cuando el indicador aún no se calculó.
`comex.pendiente_de_calculo`	`true` = el indicador aún no se calcula para este perfil. Distinto de "sin actividad": un importador sin indicador no es un no-importador.
`comex.corte_publicacion`	Último mes con datos publicados por aduanet, por flujo. Las ventanas se anclan acá, no en la fecha de la consulta.
`comex.resumen[].valor`	`CIF` (importaciones) o `FOB` (exportaciones). No son la misma unidad: no sumes importaciones con exportaciones.
`comex.resumen[].ventanas[].numero_operaciones`	Cantidad de operaciones de la ventana.
`comex.resumen[].ventanas[].principal_pais` + `participacion_principal_pais`	País principal de cada ventana (origen en importaciones, destino en exportaciones) y su participación %.
`comex.resumen[].principal_partida`	Principal partida arancelaria de la ventana actual (`codigo`, `nombre`, `participacion`).

Campos que se mantienen

comex.resumen[].tipo — Importaciones / Exportaciones, ambos items siempre presentes.
comex.ultima_actualizacion_* — mismo significado que en v1.

Semántica de los valores

Las ventanas son tres periodos consecutivos de 12 meses cada uno, contados hacia atrás desde el corte de publicación de cada flujo. El campo ventana es el número de orden: 1 es la más reciente (termina en el corte), 2 son los 12 meses anteriores y 3 los 12 previos a esos. El número indica qué ventana es, no cuántos meses cubre: todas cubren 12.
monto_soles se convierte mes a mes con el tipo de cambio de cada periodo y recién después se suma. null = sin tipo de cambio disponible (no se entregan montos en dólares bajo esta clave).
variacion_porcentaje compara cada ventana con la siguiente (1 contra 2, 2 contra 3). Es null cuando no hay base de comparación: siempre en la última ventana, y cuando la ventana siguiente está en cero o sin monto. Nunca significa "sin cambio".
pendiente_de_calculo: true aparece en perfiles cargados antes de este indicador; el dato se completa con la siguiente actualización del perfil (consulta nueva o monitoreo mensual). En ese estado, es_importador y es_exportador van en null y las ventanas vacías: no interpretes ese perfil como una empresa sin comercio exterior. Si necesitas una señal mientras tanto, identificacion.actividad_comercio_exterior viene de SUNAT y es independiente de este indicador.

Ejemplo del bloque `comex` en v2

"comex": {
  "es_importador": true,
  "es_exportador": false,
  "pendiente_de_calculo": false,
  "corte_publicacion": {
    "importaciones": "2025-12",
    "exportaciones": "2025-12"
  },
  "resumen": [
    {
      "tipo": "Importaciones",
      "valor": "CIF",
      "ventanas": [
        {
          "ventana": 1,
          "desde": "2025-01",
          "hasta": "2025-12",
          "monto_soles": 1897180382.12,
          "numero_operaciones": 1640,
          "variacion_porcentaje": 2.0,
          "principal_pais": "ARGENTINA",
          "participacion_principal_pais": 51.0
        },
        {
          "ventana": 2,
          "desde": "2024-01",
          "hasta": "2024-12",
          "monto_soles": 1861471175.40,
          "numero_operaciones": 1306,
          "variacion_porcentaje": 13.0,
          "principal_pais": "CANADA",
          "participacion_principal_pais": 41.0
        },
        {
          "ventana": 3,
          "desde": "2023-01",
          "hasta": "2023-12",
          "monto_soles": 1651071166.00,
          "numero_operaciones": 1334,
          "variacion_porcentaje": null,
          "principal_pais": "ARGENTINA",
          "participacion_principal_pais": 34.0
        }
      ],
      "principal_partida": {
        "codigo": "1507100000",
        "nombre": "Aceite en bruto, incluso desgomado",
        "participacion": 41.0
      }
    },
    {
      "tipo": "Exportaciones",
      "valor": "FOB",
      "ventanas": [
        { "ventana": 1, "desde": "2025-01", "hasta": "2025-12", "monto_soles": 0, "numero_operaciones": 0, "variacion_porcentaje": null, "principal_pais": null, "participacion_principal_pais": null },
        { "...": "ventanas 2 y 3, mismo shape" }
      ],
      "principal_partida": null
    }
  ],
  "ultima_actualizacion_agentes_importacion": "2026-01-02T03:00:00.000Z",
  "ultima_actualizacion_exportaciones": "2026-01-02T03:00:00.000Z",
  "ultima_actualizacion_importaciones": "2026-01-02T03:00:00.000Z"
}

En este ejemplo el perfil importa y no exporta: el item de Exportaciones igual está presente, con las ventanas en cero y los null correspondientes, para que no tengas que buscarlo en el array.

Los números de COMEX en v1 también mejoran

Junto con este cambio, los montos del bloque comex de v1 pasan a calcularse desde la misma fuente anclada al corte de publicación. La forma de v1 no cambia en nada, pero los montos — que hasta ahora podían salir en cero por el rezago de publicación de aduanet — pasan a reflejar el último mes efectivamente publicado.

Estado de carga del perfil (v2)

En v1 no hay forma de distinguir si un null o un array vacío significa "la empresa no tiene datos en esa fuente", "la fuente falló en la última carga" o "el perfil todavía está cargando". En v2 el resumen lo hace explícito en dos niveles.

Estado global

Dos campos nuevos a nivel raíz del resumen:

Campo	Tipo	Descripción
`estado`	`'succeeded' \| 'partial' \| 'failed' \| 'loading'`	Qué tan completa quedó la última carga del perfil.
`subhelpers_fallidos`	`string[]`	Subhelpers que fallaron en la última carga (ej: `"DeudoresMorosos"`). Vacío si no falló nada.

`estado`	Significado
`succeeded`	Todas las fuentes terminaron correctamente.
`partial`	Algunas fuentes fallaron pero hay datos útiles; `subhelpers_fallidos` lista cuáles.
`failed`	Ninguna fuente pudo cargarse.
`loading`	La carga sigue en curso; las secciones pendientes vienen con `statusCode: "SH20"`.

Envoltura por sección

Cada sección del resumen (identificacion, finanzas, legal, boletin, comex, laboral, judicial, alerta_sheriff, alerta_sentinel, alerta_compliance) pasa de ser el objeto directo a un wrapper { statusCode, data }:

{
  "taxId": "20100000001",
  "activo": true,
  "estado": "partial",
  "subhelpers_fallidos": ["Exportaciones", "Importaciones", "ImportacionesAgentes"],
  "finanzas": { "statusCode": "SH10", "data": { /* contrato v2 de finanzas */ } },
  "comex": { "statusCode": "SH50", "data": {} },
  "laboral": { "statusCode": "SH30", "data": {} }
}

data trae los campos completos de la sección solo con código de éxito (SH10/SH11); en cualquier otro caso viene {}.

Alerta Sheriff: secciones y campos renombrados

En v2 el ex "puntaje de riesgo" pasa a llamarse alerta. Cambian los nombres de dos secciones y de tres campos:

v1	v2
`puntaje_riesgo_sheriff`	`alerta_sheriff`
`puntaje_riesgo_sentinel`	`alerta_sentinel`
`puntaje_riesgo_sheriff.puntaje_riesgo_total`	`alerta_sheriff.puntaje_total`
`puntaje_riesgo_sheriff.puntaje_riesgo_maximo`	`alerta_sheriff.puntaje_maximo`
`puntaje_riesgo_sheriff.clasificacion_riesgo` (`"Riesgo medio"`)	`alerta_sheriff.clasificacion` (`"Alerta media"`)

Los valores de clasificacion cambian de escala (Riesgo * → Alerta *): si tu integración compara la clasificación, actualiza los valores esperados. El resto de los campos de la sección (modulos_incluidos, puntaje_finanzas, etc.) no cambia. Los campos internos de alerta_sentinel tampoco cambian.

Códigos de estado por sección

Los statusCode usan una escala propia de Sheriff organizada por familias: SH1x éxito, SH2x en proceso, SH3x plan, SH4x error del cliente, SH5x fallo. data trae los campos completos solo con SH10/SH11.

👉 El catálogo completo de códigos y la semántica de cada estado (incluidos alerta_compliance, los puntajes y los perfiles anteriores al tracking) están en Estados de Carga.

Webhooks

La versión del data que entrega el webhook de resumen de perfil la eliges tú, por configuración, desde el dashboard en Integraciones → Webhooks: v1 (estable, por defecto) o v2 (beta). La regla es la misma de esta guía — el payload del webhook es el resumen de la versión elegida — y puedes probar v2 en una configuración de pruebas mientras producción sigue recibiendo v1. Ver Versión del Payload.

Los campos de estado del envelope se deprecarán

El envelope del webhook mantiene profileLoadStatus y failedSubhelpers por compatibilidad con v1, pero con payload v2 la misma información llega dentro de data con más detalle (estado, subhelpers_fallidos y statusCode por sección). Los campos del envelope se eliminarán en una fecha que anunciaremos cuando v2 sea estable — si los consumes, planifica leer el estado desde data al migrar a v2.

Qué cambia​

Sección finanzas

Campos que desaparecen en v2​

Campos nuevos en v2​

Campos que se mantienen​

Semántica de los valores​

Ejemplo del bloque finanzas en v2​

Sección comex

Campos que desaparecen en v2​

Campos nuevos en v2​

Campos que se mantienen​

Semántica de los valores​

Ejemplo del bloque comex en v2​

Estado de carga del perfil (v2)

Estado global​

Envoltura por sección​

Alerta Sheriff: secciones y campos renombrados​

Códigos de estado por sección​

Webhooks​

Qué cambia

Sección `finanzas`

Campos que desaparecen en v2

Campos nuevos en v2

Campos que se mantienen

Semántica de los valores

Ejemplo del bloque `finanzas` en v2

Sección `comex`

Campos que desaparecen en v2

Campos nuevos en v2

Campos que se mantienen

Semántica de los valores

Ejemplo del bloque `comex` en v2

Estado global

Envoltura por sección

Alerta Sheriff: secciones y campos renombrados

Códigos de estado por sección

Webhooks