Cómo interpretar la respuesta del Screening

Manual para que una aplicación cliente interprete la respuesta del endpoint público POST /v1/screening, incluso cuando la consulta avanzada expande la red societaria mediante ownership_network.

Los textos presentados al usuario pueden ser localizados por la capa cliente. La documentación interactiva (/docs) es la referencia de tipos y campos; este manual explica la semántica y el orden de lectura.

La recomendación de la API apoya la decisión de compliance. No sustituye la política, las aprobaciones ni el análisis humano exigido por el cliente.

Orden seguro de lectura

Una respuesta larga no debe leerse como una lista única de coincidencias. El consumidor debe seguir esta secuencia:

1. Confirmar si la respuesta es concluyente (status).
2. Leer la decisión sobre el sujeto consultado directamente.
3. Evaluar las coincidencias y la cobertura de las fuentes.
4. Evaluar por separado la red societaria, cuando se solicite.
5. Usar el dossier y la facturación como evidencia y trazabilidad.

1. ¿La respuesta es concluyente?

{
  "status": "COMPLETE",
  "billable": true,
  "warnings": [],
  "notices": []
}

Ejemplo de respuesta que exige repetición o revisión, y no aprobación:

{
  "status": "PARTIAL",
  "billable": false,
  "notices": [
    {
      "code": "PARTIAL_SOURCE_FAILURE",
      "severity": "WARNING",
      "message": "Partial screening: at least one selected live source was unavailable. The result is not conclusive and was not charged. Run the screening again."
    }
  ]
}

2. Decisión sobre el sujeto consultado directamente

{
  "risk_level": "HIGH",
  "identity_class": "TRUE_MATCH",
  "recommendation": "REJECT",
  "summary": "One or more high-risk matches have confirmed identity. Blocking is recommended subject to your compliance policy."
}

Estos cuatro campos describen solamente a la persona o empresa enviada en el request. No deben asumirse como un resumen automático de la red de QSA.

Clases de identidad

Niveles de riesgo

Una política de integración típica es:

COMPLETE + CLEAR + NO_MATCH             -> continuar, respetando el alcance consultado
COMPLETE + MEDIUM o POTENTIAL_MATCH     -> revisión humana
COMPLETE + HIGH + TRUE_MATCH            -> bloquear o escalar según la política
PARTIAL o ERROR                         -> no aprobar automáticamente

El PEP es un caso aparte: requires_edd: true exige diligencia reforzada, pero la condición de PEP, por sí sola, no es motivo de bloqueo automático.

3. Coincidencias directas: hits

{
  "total_hits": 2,
  "actionable_hits_count": 2,
  "informational_hits_count": 3,
  "returned_hits_count": 2,
  "hits_truncated": false,
  "hits": [
    {
      "source": "OFAC_SDN",
      "category": "Financial Sanction",
      "name_similarity": 0.98,
      "identity_confidence": 1.0,
      "document_evidence": "EXACT_MATCH",
      "identity_class": "TRUE_MATCH",
      "risk_level": "HIGH",
      "requires_edd": true,
      "downgraded": false
    }
  ]
}

Nunca tome una decisión solo por name_similarity. Use identity_class, risk_level, document_evidence y el contexto de la fuente.

4. Cobertura de las fuentes: sources_checked

sources_checked es la prueba de qué fuentes fueron efectivamente consultadas y qué ocurrió en cada una.

{
  "sources_checked": {
    "OFAC_SDN": {
      "list_status": "AVAILABLE",
      "query_result": "MATCH",
      "risk_level": "HIGH",
      "hits": 1,
      "confirmed_hits": 1,
      "potential_hits": 0,
      "skip_reason": null
    },
    "PY_DNIT_RUC": {
      "list_status": "NOT_APPLICABLE",
      "query_result": "NOT_QUERIED",
      "hits": 0,
      "skip_reason": "COMPATIBLE_DOCUMENT_REQUIRED"
    }
  }
}

• Una fuente con NO_MATCH solo sustenta una conclusión si fue realmente consultada.
• skip_reason: COMPATIBLE_DOCUMENT_REQUIRED no es una falla: esa fuente exige un documento compatible y no puede buscarse solo por el nombre.
• Un error completado, una fuente no disponible o un aviso de alcance parcial impiden tratar la respuesta como cobertura íntegra.
• confirmed_hits, potential_hits, weak_hits y best_match_class ayudan a explicar la calidad de la evidencia por fuente.

5. Solicitud de QSA

El QSA es un enriquecimiento interno devuelto por la misma llamada de Screening. Para solicitarlo, el consumidor agrega estos campos al cuerpo de POST /v1/screening:

{
  "name": "EMPRESA ALFA LTDA",
  "cnpj": "12345678000190",
  "groups": ["national", "sanctions"],
  "advanced": true,
  "ownership_depth": 3
}

ownership_depth puede ir de 1 a 8 y exige advanced: true más CPF o CNPJ. El QSA no se ejecuta en profundidad 0.

6. Qué representa un nivel de QSA

Un nivel es una ronda completa de expansión societaria, no una alternancia fija entre empresas y socios.

Raíz CPF

Persona consultada
└── nivel 1: empresas en las que la persona figura como socia
    └── nivel 2: socios de esas empresas y empresas en las que participan
        └── nivel 3: expansión de las entidades nuevas del nivel 2

Raíz CNPJ

Empresa consultada (nivel 0)
├── nivel 1: sus socios
├── nivel 1: empresas en las que también participa
└── nivel 2: expansión de las personas y empresas nuevas del nivel 1
    └── nivel 3: expansión de las entidades nuevas del nivel 2

El nivel mide distancia en la expansión, no riesgo, participación societaria ni control. Una entidad de nivel 3 puede ser más grave que una de nivel 1, y viceversa.

7. Cómo leer una respuesta en varios niveles

{
  "ownership_network": {
    "status": "FOUND",
    "queried_cnpj_root": "12345678",
    "requested_depth": 3,
    "reached_depth": 3,
    "billable_depth": 3,
    "total_companies": 4,
    "companies": [
      {
        "cnpj_root": "12345678",
        "legal_name": "EMPRESA CONSULTADA LTDA",
        "level": 0,
        "partners": [
          {
            "level": 1,
            "name": "ANA EXEMPLO",
            "party_type": "PF",
            "role": "SOCIO-ADMINISTRADOR"
          }
        ]
      },
      {
        "cnpj_root": "87654321",
        "legal_name": "HOLDING ALFA LTDA",
        "level": 1,
        "originating_partner_name": "EMPRESA CONSULTADA LTDA",
        "screening": {
          "risk_level": "CLEAR",
          "identity_class": "NO_MATCH",
          "recommendation": "APPROVE"
        }
      },
      {
        "cnpj_root": "11223344",
        "legal_name": "BETA PARTICIPACOES LTDA",
        "level": 2,
        "originating_partner_name": "ANA EXEMPLO",
        "screening": {
          "risk_level": "MEDIUM",
          "identity_class": "TRUE_MATCH",
          "recommendation": "REVIEW",
          "actionable_hits_count": 1
        }
      },
      {
        "cnpj_root": "55667788",
        "legal_name": "GAMMA INVESTIMENTOS LTDA",
        "level": 3,
        "originating_partner_name": "BETA PARTICIPACOES LTDA",
        "screening": {
          "risk_level": "HIGH",
          "identity_class": "TRUE_MATCH",
          "recommendation": "REJECT",
          "actionable_hits_count": 1
        }
      }
    ]
  }
}

El cliente debe analizar cada company.screening y cada company.partners[].screening como una conclusión sobre esa entidad relacionada.

En el ejemplo anterior, el resultado principal puede seguir siendo CLEAR, pero el cliente debe mostrar algo como:

Sujeto principal: sin coincidencia accionable.
Red societaria: riesgo alto encontrado en el nivel 3 en GAMMA INVESTIMENTOS LTDA.
Próxima acción: revisión de compliance de la red societaria.

Esto preserva la verdad del contrato: el riesgo directo y el riesgo de relación no son la misma afirmación.

Presentación recomendada

Agrupar la lista por level es más seguro que intentar dibujar un árbol jurídico exacto:

Red societaria — 3 de 3 niveles completados

Nivel 0
• EMPRESA CONSULTADA LTDA

Nivel 1 — vínculos directos
• ANA EXEMPLO — socia administradora
• HOLDING ALFA LTDA — sin coincidencia accionable

Nivel 2 — vínculos de los relacionados
• BETA PARTICIPAÇÕES LTDA — revisión necesaria

Nivel 3 — expansión adicional
• GAMMA INVESTIMENTOS LTDA — riesgo alto confirmado

companies es una lista plana. originating_partner_name indica a través de qué socio se encontró la empresa, pero el contrato no incluye un identificador de empresa matriz ni de arista. Por eso, nombres iguales pueden hacer ambiguo un árbol gráfico. La interfaz debe preferir la formulación "encontrada en el nivel X vía Y".

8. Completitud, límites y costo del QSA

{
  "ownership_network": {
    "requested_depth": 3,
    "reached_depth": 2,
    "warnings": ["The ownership entity limit was reached."],
    "derived_screening": {
      "entities_processed": 100,
      "unique_entities": 98,
      "relationships_found": 156,
      "entity_limit": 100,
      "interpol_excluded": true
    },
    "billing": {
      "base_groups": ["national", "sanctions"],
      "base_group_cost": 2,
      "billable_depth": 2,
      "ownership_tokens": 4,
      "interpol_excluded": true
    }
  }
}

Cuando el QSA se ejecuta, la profundidad facturable mínima es 1, incluso sin vínculos encontrados. El costo de expansión se basa en el costo de los grupos de fuentes y en la profundidad efectivamente facturable. Si el QSA no está disponible, la consulta principal puede continuar; en ese caso, trate el bloque societario como no disponible y siga los avisos y la facturación devueltos.

9. Dossier y trazabilidad de auditoría

dossier organiza las evidencias del sujeto principal para auditoría:

{
  "dossier": {
    "audit_trail": {
      "api_version": "v1",
      "timestamp_utc": "2026-08-04T12:15:18Z",
      "groups_checked": ["national", "sanctions"],
      "tokens_charged": 6
    },
    "decision": {
      "risk_level": "MEDIUM",
      "identity_class": "POTENTIAL_MATCH",
      "recommendation": "REVIEW"
    },
    "regulatory_taxonomy": {
      "by_category": {
        "Politically Exposed Person (PEP)": 1
      },
      "risk_by_category": {
        "Politically Exposed Person (PEP)": "MEDIUM"
      }
    },
    "proof_of_compliance": {
      "status": "RECORDED",
      "ledger_ref": "SCR-20260804-ABC123",
      "hash": "..."
    }
  }
}

El dossier no debe usarse para recalcular la decisión: es una presentación auditable de decision, detailed_hits, taxonomía y evidencia de facturación.

10. Resultado resumido para la interfaz del cliente

Una aplicación puede mostrar su propio resumen, siempre que preserve la respuesta original para auditoría:

{
  "screening_completeness": "COMPLETE",
  "direct_subject": {
    "risk": "CLEAR",
    "identity": "NO_MATCH",
    "recommendation": "APPROVE",
    "actionable_hits": 0
  },
  "ownership_network": {
    "status": "FOUND",
    "requested_depth": 3,
    "reached_depth": 3,
    "related_entities_with_actionable_hits": 2,
    "highest_related_risk": "HIGH"
  },
  "next_action": "MANUAL_REVIEW"
}

related_entities_with_actionable_hits, highest_related_risk y next_action son ejemplos de campos calculados por la aplicación cliente. No sustituyen los campos oficiales devueltos por la API.

11. Checklist de implementación

• Validar status antes de consumir cualquier recomendación.
• Tratar risk_level e identity_class como ejes independientes.
• Mostrar notices y registrar la respuesta íntegra.
• No confundir el resultado directo con el riesgo de la red societaria.
• Evaluar cada company.screening y partners[].screening del QSA.
• Mostrar requested_depth, reached_depth, avisos y límites de la red.
• Señalar que INTERPOL queda excluido del análisis derivado de QSA.
• Usar tokens_charged, token_balance, billing y proof_of_compliance para trazabilidad.
• Nunca inferir que una fuente fue consultada solo porque no hay hits; usar sources_checked.