Valida compliance antes de consultar CMF

Valida compliance antes de consultar CMF

Antes de consultar la base de deuda consolidada de la CMF, debes verificar que la entidad tiene un consentimiento REDEC vigente y que este consentimiento cubre los datos requeridos por tu template. Esta validación es el paso previo a consultar la API de deuda de la CMF.

Paso obligatorio antes de consultar CMF

No consultes la base de deuda si el compliance status no es complies. Hacerlo sin consentimiento válido infringe la NCG 540 de la CMF.

Cuándo validar

Valida el compliance status inmediatamente antes de cada consulta a la base de deuda. Un consentimiento puede haber sido revocado o expirado entre el momento en que se capturó y el momento en que vas a consultar.

La regla de decisión es:

Estado	Acción
complies	Continúa con la consulta CMF
non_compliant	Detén el flujo. No consultes la base de deuda
partially_compliant	Detén el flujo. No consultes la base de deuda
Respuesta vacía (sin agreements)	Detén el flujo. No consultes la base de deuda

Consulta el estado de compliance

Soyio ofrece dos endpoints equivalentes: uno que identifica a la entidad por su id y otro por su user_reference.

Por entity_id

GET /entities/{id}/agreement/compliance_statuses

Por user_reference

GET /entities/reference/{user_reference}/agreement/compliance_statuses

Usa user_reference cuando tu sistema identifica a los usuarios con tu propio identificador interno. Ambos endpoints retornan la misma respuesta.

Por entity_id

cURL

GET /entities/{id}/agreement/compliance_statuses

curl -X GET "https://api.soyio.id/entities/ent_abc123/agreement/compliance_statuses?where=%7B%22consent_template_id%22%3A%7B%22%3D%22%3A%22constpl_xyz789%22%7D%7D" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

Verificar compliance por entity_id

const entityId = 'ent_abc123';
const templateId = 'constpl_xyz789';
const where = JSON.stringify({ consent_template_id: { '=': templateId } });

const response = await fetch(
  `https://api.soyio.id/entities/${entityId}/agreement/compliance_statuses?where=${encodeURIComponent(where)}`,
  {
    headers: {
      Authorization: `Bearer ${YOUR_API_KEY}`,
    },
  },
);

const data = await response.json();
const status = data.compliance_statuses?.[0]?.status;

if (status === 'complies') {
  // Continuar con la consulta CMF
} else {
  // Detener el flujo
}

Python

Verificar compliance por entity_id

import requests
import json

entity_id = 'ent_abc123'
template_id = 'constpl_xyz789'
where = json.dumps({'consent_template_id': {'=': template_id}})

response = requests.get(
    f'https://api.soyio.id/entities/{entity_id}/agreement/compliance_statuses',
    headers={'Authorization': f'Bearer {YOUR_API_KEY}'},
    params={'where': where},
)

data = response.json()
statuses = data.get('compliance_statuses', [])
status = statuses[0]['status'] if statuses else None

if status == 'complies':
    pass  # Continuar con la consulta CMF
else:
    pass  # Detener el flujo

Por user_reference

cURL

GET /entities/reference/{user_reference}/agreement/compliance_statuses

curl -X GET "https://api.soyio.id/entities/reference/my_internal_user_id/agreement/compliance_statuses?where=%7B%22consent_template_id%22%3A%7B%22%3D%22%3A%22constpl_xyz789%22%7D%7D" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

Verificar compliance por user_reference

const userReference = 'my_internal_user_id';
const templateId = 'constpl_xyz789';
const where = JSON.stringify({ consent_template_id: { '=': templateId } });

const response = await fetch(
  `https://api.soyio.id/entities/reference/${userReference}/agreement/compliance_statuses?where=${encodeURIComponent(where)}`,
  {
    headers: {
      Authorization: `Bearer ${YOUR_API_KEY}`,
    },
  },
);

const data = await response.json();
const status = data.compliance_statuses?.[0]?.status;

if (status === 'complies') {
  // Continuar con la consulta CMF
} else {
  // Detener el flujo
}

Python

Verificar compliance por user_reference

import requests
import json

user_reference = 'my_internal_user_id'
template_id = 'constpl_xyz789'
where = json.dumps({'consent_template_id': {'=': template_id}})

response = requests.get(
    f'https://api.soyio.id/entities/reference/{user_reference}/agreement/compliance_statuses',
    headers={'Authorization': f'Bearer {YOUR_API_KEY}'},
    params={'where': where},
)

data = response.json()
statuses = data.get('compliance_statuses', [])
status = statuses[0]['status'] if statuses else None

if status == 'complies':
    pass  # Continuar con la consulta CMF
else:
    pass  # Detener el flujo

Filtra por consent_template_id para evaluar el cumplimiento respecto al template específico que usaste para capturar el consentimiento REDEC. Sin filtro, el endpoint retorna el estado para todos los templates activos de tu empresa.

Interpreta la respuesta

Respuesta positiva (complies)

La entidad tiene consentimiento vigente que cubre todos los data_requirements del template. Puedes continuar con la consulta CMF.

Respuesta: entidad cumple

{
  "compliance_statuses": [
    {
      "status": "complies",
      "consent_template_id": "constpl_xyz789",
      "consent_template_version": 1,
      "last_consent_action_id": "consact_def456",
      "last_related_consent_action_id": "consact_def456",
      "last_related_consent_action_template_version": 1
    }
  ]
}

Respuesta negativa (non_compliant)

La entidad no tiene consentimiento activo o el consentimiento no cubre los datos requeridos. Detén el flujo.

Respuesta: entidad no cumple

{
  "compliance_statuses": [
    {
      "status": "non_compliant",
      "consent_template_id": "constpl_xyz789",
      "consent_template_version": 1,
      "last_consent_action_id": null,
      "last_related_consent_action_id": null,
      "last_related_consent_action_template_version": null
    }
  ]
}

Respuesta vacía

Si el array compliance_statuses está vacío, la entidad no tiene ningún agreement asociado a tu empresa. Trata esto igual que non_compliant.

Respuesta: sin agreements

{
  "compliance_statuses": []
}

Por qué depende del consentimiento

El compliance status refleja dos condiciones simultáneas:

1. Consentimiento vigente: el usuario otorgó el consentimiento y no lo ha revocado ni ha expirado.
2. Permiso compatible: el template de consentimiento incluye los data_requirements que autorizan la consulta a la base de deuda (los data uses finance.credit_risk_assessment o finance.commercial_risk_assessment).

Si alguna de las dos condiciones no se cumple, el status no será complies.

Qué hacer si no cumple

Si el compliance status no es complies, debes volver a capturar el consentimiento antes de consultar la base de deuda:

1. Presenta nuevamente el flujo de consentimiento al usuario con el template REDEC correspondiente.
2. Una vez que el usuario confirme, registra la nueva acción de consentimiento.
3. Vuelve a consultar el compliance status para confirmar que ahora es complies.
4. Continúa con la consulta CMF y reporta el acceso en RDC31.

No intentes consultar la base de deuda como acción por omisión si el compliance status no es complies. En ese caso el consentimiento no existe o no es válido, lo que impide el acceso legítimo al historial crediticio bajo la NCG 540.

Próximos pasos

• Registra consentimientos REDEC - Cómo capturar y registrar el consentimiento inicial
• Genera reportes RDC31 - Reporta cada acceso exitoso a la base de deuda
• Referencia: compliance status por entity_id - Documentación completa del endpoint
• Referencia: compliance status por user_reference - Documentación completa del endpoint alternativo