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.
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 /api/v1/entities/{id}/agreement/compliance_statuses
Por user_reference
GET /api/v1/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
- Por user_reference
- cURL
- JavaScript
- Python
curl -X GET "https://app.soyio.id/api/v1/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"
const entityId = 'ent_abc123';
const templateId = 'constpl_xyz789';
const where = JSON.stringify({ consent_template_id: { '=': templateId } });
const response = await fetch(
`https://app.soyio.id/api/v1/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
}
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://app.soyio.id/api/v1/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
- cURL
- JavaScript
- Python
curl -X GET "https://app.soyio.id/api/v1/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"
const userReference = 'my_internal_user_id';
const templateId = 'constpl_xyz789';
const where = JSON.stringify({ consent_template_id: { '=': templateId } });
const response = await fetch(
`https://app.soyio.id/api/v1/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
}
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://app.soyio.id/api/v1/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.
Valida una evaluación u operación específica
Sin parámetros adicionales, el compliance status responde si la persona tiene algún consentimiento vigente del template. Si la persona tiene un consentimiento para una evaluación de crédito y le abres otra, la respuesta es complies para las dos, aunque la segunda no tenga consentimiento propio.
Para validar la consulta de deuda de una evaluación u operación en particular, agrega uno de estos parámetros:
| Etapa | Parámetro | El template REDEC queda en complies cuando |
|---|---|---|
| Evaluación | redec_evaluation_id | Existe un consentimiento vigente registrado con ese ID de evaluación. |
| Operación | redec_operation_id | Existe un consentimiento extendido con ese ID de operación y la extensión no ha terminado. |
Además, el agreement de la persona tiene que seguir cubriendo todos los datos del template para responder complies, igual que en la validación sin parámetros. Si no hay un consentimiento vigente que coincida con el ID, el template queda en non_compliant. Si el ID coincide, pero el agreement solo cubre algunos requisitos del template, responde partially_compliant; si no cubre ninguno, responde non_compliant.
curl -G "https://app.soyio.id/api/v1/entities/ent_abc123/agreement/compliance_statuses" \
--data-urlencode 'where={"consent_template_id":{"=":"constpl_xyz789"}}' \
--data-urlencode 'redec_evaluation_id=EVAL-2026-00042' \
-H "Authorization: Bearer YOUR_API_KEY"
Para validar una operación, envía redec_operation_id=OP-123 en lugar de redec_evaluation_id. Los dos parámetros funcionan igual en el endpoint por user_reference.
Después de extender, valida con el ID de operación
Cuando extiendes un consentimiento, ese consentimiento deja de identificarse por su ID de evaluación y pasa a identificarse por su ID de operación. Por eso, un consentimiento extendido no cumple con redec_evaluation_id, aunque el ID coincida.
Por ejemplo, si registraste un consentimiento con evaluation_id EVAL-2026-00042 y después lo extendiste con operation_id OP-123:
| Consulta | Antes de extender | Después de extender |
|---|---|---|
redec_evaluation_id=EVAL-2026-00042 | complies | non_compliant |
redec_operation_id=OP-123 | non_compliant | complies |
Cuando otorgues el crédito, extiende el consentimiento con su operation_id y cambia tus validaciones de esa operación a redec_operation_id.
Cuándo un ID no cumple aunque coincida
El template queda en non_compliant aunque el ID coincida si el consentimiento:
- Caducó: pasaron sus 15 días hábiles sin extenderlo
- El deudor lo revocó
- Tu empresa lo revocó, así que el agreement ya no tiene los permisos
- Está extendido y lo consultas con
redec_evaluation_id - Tiene la extensión cerrada y ya pasó la fecha en que terminó la obligación
Si no enviaste el ID al registrar el consentimiento o al extenderlo, Soyio no tiene cómo asociarlo y la respuesta es non_compliant. En ese caso, valida sin el parámetro.
Templates que no son REDEC
Los IDs solo cambian el estado de los templates REDEC, es decir, los que tienen los data uses finance.credit_risk_assessment o finance.commercial_risk_assessment. Si no filtras por consent_template_id, la respuesta también trae tus otros templates, por ejemplo uno de marketing, y esos se calculan igual que sin el parámetro: el ID de evaluación u operación no les aplica.
Para que la respuesta sea solo la que necesitas, filtra siempre por el consent_template_id del template REDEC, como en el ejemplo anterior.
Errores
Soyio responde 400 si:
- Envías
redec_evaluation_idyredec_operation_iden la misma llamada: usa uno u otro, según la etapa - Alguno de los dos viene vacío
- Alguno de los dos no es un texto, por ejemplo si lo envías como lista
{
"type": "invalid_request_error",
"title": "Invalid parameter",
"status": 400,
"detail": "`redec_evaluation_id` and `redec_operation_id` can't be sent together"
}
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.
{
"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.
{
"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.
{
"compliance_statuses": []
}
Por qué depende del consentimiento
El compliance status refleja dos condiciones simultáneas:
- Consentimiento vigente: el usuario otorgó el consentimiento y no lo ha revocado ni ha expirado. Un consentimiento extendido sigue vigente hasta que cierres la extensión.
- Permiso compatible: el template de consentimiento incluye los
data_requirementsque autorizan la consulta a la base de deuda (los data usesfinance.credit_risk_assessmentofinance.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:
- Presenta nuevamente el flujo de consentimiento al usuario con el template REDEC correspondiente.
- Una vez que el usuario confirme, registra la nueva acción de consentimiento.
- Vuelve a consultar el compliance status para confirmar que ahora es
complies. - 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