Flujo completo de consulta de deuda bajo consentimiento
Flujo completo de consulta de deuda bajo consentimiento
Ya viste cómo se generan y verifican los recibos PDF REDEC. Esta guía da un paso atrás y conecta esa pieza con el resto del flujo: desde el registro del consentimiento hasta la consulta de deuda en la CMF y su registro en RDC31, en el orden exacto en que ocurren en producción.
Úsala como mapa de referencia cuando ya conoces cada guía modular (registro de consentimientos, validación de compliance, construcción del payload CMF y recibos) pero necesitas ver cómo encajan sus IDs y condiciones de detención antes de pasar a generar los reportes RDC30 y RDC31 de cumplimiento.
Cada sección enlaza a la guía modular correspondiente para el detalle completo; aquí encontrarás el orden de los pasos, los IDs que debes conservar y las condiciones que detienen el flujo.
Diagrama de secuencia completo
El diagrama omite la captura del consentimiento en el frontend (action_token) y la descarga del recibo PDF, ya que no son llamadas obligatorias para completar la consulta CMF. Revisa captura de consentimientos y recibos PDF REDEC si necesitas esos detalles.
Resumen del flujo
| # | Paso | Endpoint / recurso | IDs que obtienes | Campos clave |
|---|---|---|---|---|
| 1 | Captura el consentimiento | SDK de Soyio | action_token | — |
| 2 | Registra la acción REDEC | POST /redec/consent_actions | consent_action.id, redec_data.redec_id, entity_id | consent_template_id, redec_pdf_hash (puede ser null) |
| 3 | Consulta la acción registrada | GET /redec/consent_actions/{id} | — | redec_pdf_hash, agreement_id, evidence_id |
| 4 | Consulta el agreement | GET /agreements?where={"user_reference":...}&latest=true | — | data_permissions[].expires_at |
| 5 | Descarga el recibo PDF | GET /redec/consent_actions/{id}/download_receipt | — | Archivo PDF verificable contra redec_pdf_hash |
| 6 | Valida compliance status | GET /entities/{id}/agreement/compliance_statuses | — | status (complies / non_compliant / partially_compliant) |
| 7 | Construye el payload CMF | Mapeo Soyio → CMF | — | rut_consultado, hash.hash, medio_consentimiento |
| 8 | Consulta deuda en la CMF | POST /consultarDeudas (API CMF) | — | Respuesta de deuda consolidada |
| 9 | Registra el acceso RDC31 | POST /redec/accesses | accesses[].id | redec_id, access_date, access_time, mandatary_nin |
Paso 1: Captura el consentimiento con el SDK
Muestra el componente de consentimiento con una plantilla REDEC-compliant y obtén el action_token cuando el usuario acepte. Revisa la guía de captura de consentimientos si aún no implementaste este paso.
Obtienes: action_token
Paso 2: Registra la acción de consentimiento REDEC
Envía el action_token junto con el RUT del usuario al endpoint específico de REDEC.
{
"action_token": "at_abc123...",
"entity_nin": "12.345.678-9",
"executive_nin": "98.765.432-1",
"user_reference": "cliente_123"
}
Obtienes: consent_action.id, redec_data.redec_id, entity_id, consent_template_id
Revisa la guía completa de registro de consentimientos REDEC para los escenarios de sucursal, solicitud online y usuario existente.
Paso 3: Consulta la acción registrada
El PDF del recibo se genera en segundo plano, así que redec_pdf_hash puede venir null en la respuesta del paso 2. Consulta la acción con GET /redec/consent_actions/{id} para obtener el hash una vez disponible, junto con agreement_id y evidence_id.
GET /api/v1/redec/consent_actions/{id}
Obtienes: redec_pdf_hash, agreement_id, evidence_id
Si redec_pdf_hash sigue en null, espera el webhook consent_action.redec_receipt_generated antes de continuar al paso 7. No puedes construir el payload de la CMF sin este hash.
Revisa la referencia del API para Obtener un consent action REDEC para mas detalles.
Paso 4: Consulta el agreement
Consulta el agreement vigente de la entidad para obtener las fechas de expiración de los permisos otorgados. Filtra por el user_reference que enviaste en el paso 2 a través del parámetro where en formato JSON, y agrega latest=true como parámetro de nivel superior para obtener siempre la versión activa, no el historial completo.
GET /api/v1/agreements?where={"user_reference":{"=":"<user_reference>"}}&latest=true
Obtienes: data_permissions[].expires_at
Revisa la guía de acuerdos y permisos para entender el modelo completo de versionado.
Paso 5: Descarga el recibo PDF
Descarga el recibo y verifica su integridad contra el redec_pdf_hash obtenido en el paso 3.
GET /api/v1/redec/consent_actions/{id}/download_receipt
Revisa la guía de recibos PDF REDEC para el flujo completo de generación, descarga y verificación de integridad.
Paso 6: Valida compliance status
Antes de consultar la CMF, verifica que el consentimiento sigue vigente. Esta validación es independiente del paso 4: usa el endpoint de compliance status, no el agreement crudo.
GET /entities/{id}/agreement/compliance_statuses?where={"consent_template_id":{"=":"<consent_template_id>"}}
Obtienes: status (complies / non_compliant / partially_compliant)
Si status no es complies, detén el flujo. No consultes la base de deuda de la CMF con un consentimiento no vigente. Vuelve a capturar el consentimiento y repite desde el paso 1. Revisa la guía de validación de compliance para el detalle completo.
Paso 7: Construye el payload para la CMF
Mapea los campos obtenidos en los pasos anteriores a la estructura que espera POST /consultarDeudas.
| Campo CMF | Fuente en Soyio |
|---|---|
rut_consultado | entity_nin (sin puntos ni guion) |
fecha_inicio_otorgamiento / hora_inicio_otorgamiento | consent_action.created_at |
fecha_fin_consentimiento / hora_fin_consentimiento | data_permissions[].expires_at |
hash.hash | redec_pdf_hash |
codigo_institucion | Código REDEC de tu empresa |
medio_consentimiento | consent_action.channel |
Precondición: redec_pdf_hash no es null y el compliance status del paso 6 es complies.
Si data_permissions[].expires_at es null, no envíes null directamente en fecha_fin_consentimiento / hora_fin_consentimiento. Consulta con la CMF si el endpoint acepta omitir esos campos o si requiere una fecha de referencia. Revisa la nota sobre fechas sin expiración para el detalle completo.
Revisa la tabla de mapeo completa y los catálogos CMF para las transformaciones de formato y los códigos numéricos exactos.
Paso 8: Consulta deuda en la CMF
Envía el payload construido al endpoint oficial de la CMF.
POST /consultarDeudas
Consulta la documentación oficial de la CMF para los detalles de autenticación y respuesta de este endpoint externo.
Si la CMF rechaza la consulta (por ejemplo, RUT inválido o consentimiento no reconocido), registra el error en tu sistema y no reportes un acceso en RDC31. Solo informa accesos que la CMF respondió exitosamente.
Paso 9: Registra el acceso RDC31
Solo si el paso 8 fue exitoso, informa el acceso usando el redec_id obtenido en el paso 2.
{
"redec_id": "REDECIDABC1234567890",
"access_date": "20250616",
"access_time": "213000",
"mandatary_nin": "11.111.111-1"
}
Obtienes: accesses[].id
Revisa la guía completa de RDC31 para el registro en lote y la generación del reporte semanal.
Condiciones de detención
| Condición | Paso donde se valida | Qué hacer |
|---|---|---|
Compliance status ≠ complies | Paso 6 | Vuelve a capturar el consentimiento (paso 1) antes de consultar la CMF |
redec_pdf_hash es null | Paso 3 / 7 | Espera el webhook consent_action.redec_receipt_generated antes de construir el payload |
Respuesta vacía de compliance_statuses | Paso 6 | Trata igual que non_compliant: la entidad no tiene agreement asociado |
| La CMF rechaza la consulta | Paso 8 | Registra el error, no informes el acceso en RDC31 |
Próximos pasos
- RDC30 - Genera el reporte semanal de consentimientos y programa reportes automáticos
- RDC31 - Registro en lote de accesos y generación del reporte semanal
- Configuración - Opciones avanzadas de configuración REDEC