Estados de Carga

A partir de la v2, el resumen de perfil indica explícitamente qué tan completa quedó la carga y en qué estado está cada sección. Esto resuelve una ambigüedad de v1: un null o un array vacío podía significar "la empresa no tiene datos en esa fuente", "la fuente falló en la última carga", "el perfil todavía está cargando" o "el ayudante no está contratado" — sin forma de distinguirlos.

Aplica en dos lugares, con el mismo contrato:

• La respuesta de GET /v2/perfiles/:taxId/resumen (Resumen de Perfil).
• El data de los webhooks cuya configuración usa la versión de payload v2.

Estado global

Dos campos 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ó ninguno.

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) es un objeto { 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 o SH11); en cualquier otro caso viene {}.

Catálogo de códigos

Escala propia de Sheriff, organizada por familias (la decena indica la familia):

Código	Familia	Significado	data
SH10	Éxito	Todas las fuentes de la sección cargaron bien.	Completa
SH11	Éxito parcial	Parte de las fuentes de la sección falló; hay datos útiles.	Visible con lo que cargó
SH20	En proceso	La sección tiene fuentes aún cargando.	{}
SH30	Plan	El ayudante no está contratado en tu plan.	{}
SH40	Error del cliente	Reservado: error atribuible a la configuración del cliente.	{}
SH41	Error del cliente	Reservado: credenciales del cliente inválidas ante la fuente del sistema financiero.	{}
SH50	Fallo	Todas las fuentes de la sección fallaron en la última carga.	{}
SH51	Fallo	Reservado: error interno.	{}

Códigos reservados

Los códigos marcados como reservado están definidos en el contrato pero todavía no se emiten. Trata cualquier código desconocido de forma tolerante: si no es SH10 ni SH11, asume que data viene vacío.

Semántica

• alerta_compliance: su data tiene la forma { "alerta": string } (en v1 esta sección era un string plano).
• alerta_sheriff y alerta_sentinel derivan su código del estado global: loading → SH20, failed → SH50, en el resto SH10.
• Perfiles anteriores al tracking por fuente reportan estado: "succeeded" y secciones SH10 con la data disponible; el tracking se genera en la siguiente actualización del perfil.
• El estado se recalcula en cada actualización: si una fuente que falló se recupera en la siguiente carga, el estado y los códigos vuelven a éxito. No se conserva el histórico de fallos.
• El estado describe la calidad del dato; en los webhooks, el estado del evento del dashboard describe la salud de la entrega HTTP. Son dimensiones independientes.

Relación con v1

v1 no incluye nada de esto: ni estado, ni subhelpers_fallidos, ni la envoltura por sección. El detalle del cambio de contrato está en la guía de migración v1 → v2.