REDEC

El boundary REDEC es permanente:

grant → Evidence constitutiva + internalConsentCode (artifact pending | ready)
Consensa authorize → authorized | denied (no depende del artifact)
authorized → banco/reportante consulta CMF directamente
banco/reportante → Consensa confirm accessed | failed | cancelled

Consensa no consulta /consultarDeudas, no recibe ni almacena deuda CMF y no custodia credenciales CMF del reportante.

1. Crear la interacción

POST /v1/redec/consent-interactions crea una interacción vinculada al titular y a una configuración publicada con REDEC. Los identifiers y su provenance deben satisfacer el canal y Regulatory Profile aplicables. No existe un nivel de identityAssurance universalmente suficiente.

2. Registrar el grant

POST /v1/redec/consent-interactions/{interactionId}/grant registra el consentimiento, scopes, finalidad, objetivos y el snapshot de obligación reportable. Puede responder artifactStatus: "pending" o artifactStatus: "ready".

Este endpoint registra un consentimiento capturado fuera de Consensa (captura externa diferida). Por eso exige:

Este contrato deferred es distinto del Embed Flow: en Embed, finalidad, objetivos y sistema origen de la obligación se congelan al publicar el Flow; el integrador sólo envía status + referencia dinámica y Consensa fija el timestamp síncrono.

• occurredAt: el instante en que el titular otorgó el consentimiento. Es el grantedAt regulatorio y ancla la ventana de 15 días hábiles bancarios.
• sourceSystem y sourceReference: el sistema y la referencia de la captura en tu plataforma.

Un request sin cualquiera de ellos responde 400 VALIDATION_ERROR.

Consensa rechaza un occurredAt posterior a su recepción (recordedAt) o con un desfase mayor al del Regulatory Profile (baseline: 7 días corridos). Si adjuntas la grabación de la llamada, su instante debe coincidir con occurredAt dentro de la tolerancia del profile (baseline: 5 minutos). La fecha en que digitalizaste un consentimiento en papel no se compara con occurredAt. Una fecha anterior sólo acorta la ventana; nunca la amplía.

El medio del consentimiento (electrónico, audio o respaldo físico) lo deriva Consensa desde la evidencia que entregas y lo valida contra el canal según el profile; no se envía un código de medio.

Cuando el consentimiento se captura en el Embed de Consensa, la captura es síncrona y el reloj regulatorio es la recepción de Consensa (grantedAt = recordedAt).

La respuesta del grant incluye internalConsentCode, el código interno regulatorio del consentimiento. Lo genera Consensa al registrar el grant, es único en tu tenant y no cambia. No lo envíes: un grant que traiga internalConsentCode responde 400 VALIDATION_ERROR (internal_consent_code_is_server_generated).

Si el actor fue un representante del deudor, agrega representation al grant (también dentro del payload redec de una decisión Multi-Consent):

{
  "type": "representative",
  "identifierRutInput": "12.345.678-5",
  "authorityBasis": "reporter_asserted_representation",
  "authorityReference": "poder-notarial-2026-001",
  "assertedAt": 1787702300000
}

Omitir el bloque significa que actuó el propio titular (self). Consensa normaliza y protege el RUT y conserva la aserción/provenance del banco; no verifica ni declara verificadas las facultades legales. El objeto es cerrado: no acepta tenantId, propiedades desconocidas ni vocabularios como legally_verified.

3. Readiness del artifact (para descargarlo, no para autorizar)

El consentimiento vale desde el grant: su Evidence constitutiva, alcance y vigencia son lo que evalúa POST /v1/redec/accesses/authorize, aunque el artifact siga pending. NCG 576 no exige hash para autorizar.

Si necesitas el respaldo (por ejemplo, para responder a la CMF por tus canales) y el grant respondió pending, consulta GET /v1/redec/consents/{redecConsentId} con polling acotado y backoff hasta observar artifactStatus: "ready". No uses polling agresivo ni asumas un SLA que no haya sido acordado para tu ambiente.

artifactStatus: "ready" no es una autorización: sólo indica que el artifact está custodiado y es descargable. POST /v1/redec/accesses/authorize es la autoridad final.

Lectura regulatoria

GET /v1/redec/consents/{redecConsentId} entrega la representación regulatoria vigente del consentimiento: los valores congelados al grant (código interno, canal, clase de captura, finalidad, medio, objetivos) y el estado derivado de los hechos posteriores (revocación, corrección de revocación, extensiones por crédito).

{
  "redecConsentId": "redec-consent-id",
  "internalConsentCode": "R0K7Q2M9X4V8B1N6C3Z",
  "customerId": "customer-tenant-id",
  "status": "extended",
  "channel": "digital",
  "captureTiming": "deferred_external",
  "grantedAt": 1787702400000,
  "initialAccessValidUntil": 1789430400000,
  "finalityCode": "2",
  "mediumCode": "1",
  "objectiveCodes": ["01"],
  "revocation": { "revokedAt": 1787788800000, "channel": "digital", "effective": false, "correctedAt": 1787875200000 },
  "creditExtensions": [
    { "creditExtensionId": "credit-extension-id", "objectiveCode": "01", "creditOperationReference": "OP-2026-000981",
      "creditGrantedAt": 1787702460000, "extendedAt": 1787875200000, "status": "active", "endReason": null, "endedAt": null }
  ],
  "artifactStatus": "ready"
}

• status: granted (ventana inicial), extended (hay una extensión sin término; no es revocable), revoked (revocación efectiva) o expired (ya no habilita accesos y no fue revocado efectivamente).
• retentionUntil / retentionBasis: piso mínimo de conservación de 5 años desde la revocación efectiva, la pérdida de vigencia o la extinción de la obligación. Es null mientras el consentimiento sigue vigente o extendido. No es una fecha de borrado automático.
• Si el titular revocó pero el crédito ya se había otorgado antes, la revocación queda en revocation con effective: false: Consensa la conserva como hecho y no la presenta como revocación efectiva.

Para ubicar un consentimiento sin su id usa GET /v1/redec/consents?internalConsentCode=... o GET /v1/redec/consents?creditOperationReference=... (exactamente uno). Responde { "consents": [...] }; un valor desconocido o de otro tenant devuelve una lista vacía.

Notificación al titular

Tan pronto se registra un grant o una revocación, Consensa emite el evento webhook redec.notification.required con notification_reason grant o revoke, internal_consent_code, redec_consent_id, consent_action_id, el canal y la fecha (granted_at o revoked_at); el grant incluye además finalidad, medio y objetivos. Suscríbelo desde el Portal. Consensa no envía la notificación: la envía tu banco, con los datos de contacto que tú custodias.

Después de enviarla, registra la evidencia con POST /v1/redec/consents/{redecConsentId}/notification-evidence (consent:runtime, Idempotency-Key):

{
  "notificationReason": "grant",
  "notificationChannel": "email",
  "recipientHash": "sha256-of-normalized-recipient-address",
  "status": "sent",
  "sentAt": 1787702520000,
  "sourceSystem": "bank-notifications",
  "sourceReference": "notice-grant-5521",
  "contentSha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

• Consensa ancla la evidencia al grant o a la revocación del consentimiento; no envíes consentActionId ni internalConsentCode (la respuesta los devuelve). Una evidencia revoke antes de la revocación responde redec_consent_not_revoked.
• contentSha256 es el SHA-256 del mensaje exacto que enviaste; tú conservas el mensaje (puedes referenciarlo con contentReference). recipientHash identifica el destino sin revelarlo.
• La evidencia es append-only: registra cada estado de entrega que conozcas (sent, luego delivered o bounced) como un registro nuevo. Las fechas no pueden ser anteriores al hecho notificado ni posteriores a la recepción de Consensa.
• No existe una notificación de corrección: si una revocación se corrige por un crédito ya otorgado, la lectura regulatoria refleja el estado correcto.

Evidence y Artifact

Evidence ≠ Artifact. Un consentimiento REDEC tiene superficies separadas:

Consentimiento REDEC
├── estado
├── evidence
└── artifact, cuando corresponde

GET /v1/redec/consents/{redecConsentId}/evidence muestra la vista auditable del hecho regulatorio: decisión, timestamps, template, autenticación/provenance, profile, canal, finalidad, objetivos y timing canónico. No contiene deuda CMF ni bytes documentales.

GET /v1/redec/consents/{redecConsentId}/artifact muestra metadata pública como estado, tipo de medio, origen, MIME y hash de contenido. Un Artifact puede ser un PDF generado, un PDF externo o un audio/original capturado cuando el profile y canal lo permiten; no se promete un PDF universal.

GET /v1/redec/consents/{redecConsentId}/artifact/download descarga únicamente los bytes exactos de un Artifact READY custodiado por Consensa. Los recursos externos no se proxifican y un Artifact pending no es descargable.

4. Autorizar el acceso externo

Antes de consultar CMF, el backend llama POST /v1/redec/accesses/authorize:

{
  "authorizationBasis": "consent",
  "consentAuthorizationMode": "initial_window",
  "redecConsentId": "redec-consent-id",
  "dataCategoryCode": "redec.consolidated_debt_record",
  "scopeId": "scope-credit-information",
  "objectiveCode": "01",
  "reportingObligation": {
    "status": "none",
    "sourceSystem": "core-banking",
    "sourceReference": "obligation-check-4821",
    "assertedAt": 1787702460000
  },
  "sourceSystem": "bank-channel",
  "sourceReference": "access-request-882"
}

Sólo una decisión explícita "status": "authorized" habilita al reportante para continuar. "denied" (con denyReasonCode) es una decisión de negocio; un timeout o error nunca equivale a una autorización. La respuesta es { "decision": { ... }, "replayed": false }.

5. Consultar CMF y confirmar

El reportante consulta CMF directamente con sus propias credenciales. Luego ejecuta POST /v1/redec/accesses/{redecAccessId}/confirm con exactamente uno de estos outcomes:

{ "outcome": { "kind": "accessed", "accessedAt": 1787702475000 } }

{ "outcome": { "kind": "failed" } }

{ "outcome": { "kind": "cancelled" } }

No envíes a Consensa el payload de deuda ni las credenciales usadas para acceder a CMF.

Extensión por crédito otorgado

Si otorgas un crédito bajo el consentimiento, tu core bancario lo informa con POST /v1/redec/consents/{redecConsentId}/credit-extensions. El consentimiento sigue vigente más allá de la ventana inicial mientras exista la obligación. Si el titular ya había revocado, Consensa registra la corrección de la revocación.

{
  "customerTenantId": "customer-tenant-id",
  "objectiveCode": "01",
  "creditOperationReference": "OP-2026-000981",
  "creditGrantedAt": 1787702460000,
  "sourceSystem": "core-banking",
  "sourceReference": "ledger-9"
}

Cuando la obligación se extingue o se ejecuta la aceleración, informa el término una sola vez con POST /v1/redec/consents/{redecConsentId}/credit-extensions/{creditExtensionId}/end y endReason obligation_extinguished, acceleration_executed o superseded_by_new_obligation (refinanciamiento: la obligación fue reemplazada por una nueva). Este último exige supersededByObligationReference con la creditOperationReference de la obligación nueva — la nueva obligación no hereda este consentimiento; necesita su propio tratamiento. Ambas operaciones requieren Idempotency-Key.

Si la extensión se registra después de que Consensa ya había aceptado una revocación (creditGrantedAt anterior a revokedAt), la corrección append-only que deja esa revocación sin efecto exige sourceReference no vacío en el body — una referencia checkeable del sistema fuente al otorgamiento del crédito. Sin ella, el registro se rechaza con redec_revocation_correction_requires_source_reference.

POST /v1/redec/accesses/authorize con consentAuthorizationMode: "credit_lifecycle_extension" exige además accessPurpose: "manage_existing_obligation" (la única forma de obtener authorized) o "evaluate_new_credit" — este último es un "denied" auditable (redec_credit_extension_purpose_not_obligation_management"), nunca un error de validación: la extensión sólo gestiona la EXACTA obligación de la que nació, nunca una evaluación de crédito nueva para el mismo cliente. initial_window no lleva este campo.

Codigo de consentimiento para RDC01/RDC02

Cuando el banco confirma que una obligacion fue efectivamente otorgada, registra la relacion exacta con POST /v1/redec/reportable-obligations/bindings (consent:runtime, Idempotency-Key). Este hecho no se crea al evaluar un grant: la evaluacion puede terminar sin credito.

El lookup GET /v1/redec/reportable-obligations/consent-code?sourceSystem=...&obligationReference=... (consent:read) usa ambos componentes de la identidad de la obligacion y nunca busca por cliente, por consentimiento mas reciente ni por una operacion parecida. Devuelve una semantica explicita:

• consent_code: codigo interno congelado para esa obligacion;
• legacy_pre_redec: campo MSI X(20) compuesto por 9;
• no_applicable_consent: campo MSI X(20) compuesto por 0;
• unresolved o ambiguous: el banco debe detener la generacion de RDC01/RDC02 y reconciliar el dato.

Los 9 y 0 son solo serializacion en la frontera MSI; no se persisten como codigos internos ficticios. Registrar una extension de ciclo de vida produce naturalmente el mismo binding exacto, pero la extension no es requisito para obligaciones sin ese lifecycle.

Revocar un consentimiento REDEC

Cuando el titular revoca, llama a POST /v1/redec/consents/{redecConsentId}/revoke con una Idempotency-Key estable para esa operación. Un retry exacto devuelve el mismo resultado; reutilizar la clave con un request distinto produce conflicto.

curl --request POST "$CONSENSA_API_URL/v1/redec/consents/$REDEC_CONSENT_ID/revoke" \
  --header "Authorization: Bearer $CONSENSA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: redec-revoke-$REDEC_CONSENT_ID-01" \
  --data '{
    "channel": "digital",
    "occurredAt": 1787702460000,
    "sourceType": "direct",
    "identityAssurance": "client_authenticated"
  }'

La revocación queda registrada por el flujo canónico y los permisos REDEC dejan de habilitar nuevos accesos según las reglas de dominio existentes. El valor de assurance debe corresponder a la evidencia real aceptada para el canal y profile.