Crear Consentimiento

POST /cl/consent_manager/create_consent

Registra un nuevo consentimiento para consultar información comercial o crediticia según la normativa RDC30 (NCG 540).

URL de producción: https://api.floid.app/cl/consent_manager/create_consent
URL de sandbox: https://sandbox.floid.app/cl/consent_manager/create_consent

Contrato en inglés. Los nombres de los campos del request y de la respuesta van en inglés. Los errores usan el envelope legacy con un error_code granular (ver Errores).

Headers requeridos

Authorization: Bearer {{TOKEN}}
Content-Type: application/json

El client_id se deriva del Bearer token. Si lo envías en el body, el servidor lo ignora. No lo incluyas.

Body del request

Campos obligatorios (todos los consentimientos)

Campo	Tipo	Descripción	Ejemplo
`framework`	string	Marco del consentimiento. `REDEC` (default) o `LPDP`.	`"REDEC"`
`institution_code`	string	Código de institución CMF de 9 dígitos.	`"123456789"`
`internal_code`	string	Código único por institución (máx 20 caracteres, `A-Z 0-9 . _ - /`). Estrictamente obligatorio — no se autogenera.	`"BCH-2026-001"`
`person_type`	string	`NATURAL` o `JURIDICA`.	`"NATURAL"`
`person_rut`	string	RUT que otorga el consentimiento (formato chileno con guion y dígito verificador).	`"12345678-9"`
`medium`	integer	`1` = Electrónico, `2` = Verbal, `3` = Físico. Default `1`.	`1`
`purpose`	integer	`1` = Riesgo comercial, `2` = Riesgo crediticio.	`2`
`objective`	string	Código de objetivo (`"01"` a `"07"`). Mantén el cero a la izquierda.	`"02"`

Evidencia (siempre obligatoria)

Campo	Tipo	Requerido	Descripción
`evidence.url`	string	Sí	URL HTTPS del archivo de evidencia.
`evidence.hash`	string	Condicional¹	Hash SHA-256 del archivo (64 caracteres hexadecimales).
`evidence.file_format`	string	Sí	`PDF_A` o `MP3`.

¹ Depende del modo de almacenamiento de la institución: EXTERNAL_URL_ONLY → hash obligatorio; FLOID_STORAGE → Floid descarga el archivo, calcula el hash y lo guarda en GCS, por lo que hash es opcional. El modo se configura por institución, no en el request.

Campos condicionales — Persona natural

Cuando person_type = "NATURAL":

Campo	Tipo	Requerido	Descripción
`person_email`	string	Sí	Email válido de la persona.
`person_phone`	string	No	Teléfono celular (8–15 dígitos, prefijo `+` opcional. Ej.: `"+56912345678"`).
`person_name`	string	No	Nombre completo en formato RDC30: `APELLIDO_PATERNO/APELLIDO_MATERNO/NOMBRES` (mayúsculas).

Campos condicionales — Persona jurídica

Cuando person_type = "JURIDICA", el objeto company es obligatorio. Todas las sub-claves van en inglés.

Campo	Tipo	Requerido	Descripción
`company.legal_name`	string	Sí	Razón social de la empresa.
`company.company_rut`	string	Sí	RUT de la empresa (debe coincidir con el `person_rut` del top-level).
`company.corporate_email`	string	No	Email corporativo.
`company.legal_representatives`	array	Sí	Al menos 1 representante legal.
`company.legal_representatives[].name`	string	Sí	Nombre del representante.
`company.legal_representatives[].last_name`	string	No	Apellidos del representante.
`company.legal_representatives[].rut`	string	Sí	RUT del representante.
`company.legal_representatives[].role`	string	No	Cargo del representante.
`company.grantor`	object	Sí	Persona que efectivamente otorgó el consentimiento.
`company.grantor.type`	string	Sí	`REPRESENTANTE_LEGAL` o `APODERADO`.
`company.grantor.name`	string	Sí	Nombre del otorgante.
`company.grantor.rut`	string	Sí	RUT del otorgante (debe existir en `legal_representatives` o `attorneys`).
`company.grantor.role`	string	No	Cargo del otorgante.
`attorneys`	array	No	Lista de apoderados: `[{ name, last_name, rut, role }]`.
`has_attorneys`	boolean	No	Si el consentimiento tiene apoderados. Se infiere de `attorneys` si se omite.

Campos opcionales

Campo	Tipo	Descripción
`executive_rut`	string	RUT del ejecutivo. Si se omite, se usa el default de la institución.
`branch`	string	Identificador de sucursal.

Ejemplo 1 — Persona natural

curl --location 'https://api.floid.app/cl/consent_manager/create_consent' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{TOKEN}}' \
  --data '{
    "framework": "REDEC",
    "institution_code": "123456789",
    "internal_code": "BCH-NAT-001",
    "person_type": "NATURAL",
    "person_rut": "12345678-9",
    "person_name": "GARCIA/PEREZ/JUAN CARLOS",
    "person_email": "[email protected]",
    "person_phone": "+56912345678",
    "medium": 1,
    "purpose": 2,
    "objective": "02",
    "executive_rut": "98765432-1",
    "evidence": {
      "url": "https://institution.com/evidence/consent-001.pdf",
      "hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
      "file_format": "PDF_A"
    }
  }'

Ejemplo 2 — Persona jurídica

curl --location 'https://api.floid.app/cl/consent_manager/create_consent' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{TOKEN}}' \
  --data '{
    "framework": "REDEC",
    "institution_code": "123456789",
    "internal_code": "BCH-JUR-001",
    "person_type": "JURIDICA",
    "person_rut": "76543210-K",
    "person_email": "[email protected]",
    "company": {
      "legal_name": "EMPRESA EJEMPLO S.A.",
      "company_rut": "76543210-K",
      "legal_representatives": [
        { "name": "GONZALEZ/SILVA/MARIA TERESA", "rut": "11111111-1", "role": "GERENTE GENERAL" }
      ],
      "grantor": {
        "type": "REPRESENTANTE_LEGAL",
        "name": "GONZALEZ/SILVA/MARIA TERESA",
        "rut": "11111111-1",
        "role": "GERENTE GENERAL"
      }
    },
    "attorneys": [
      { "name": "FERNANDEZ/LOPEZ/CARLOS ANDRES", "rut": "33333333-3", "role": "APODERADO FINANCIERO" }
    ],
    "medium": 1,
    "purpose": 2,
    "objective": "01",
    "executive_rut": "98765432-1",
    "evidence": {
      "url": "https://institution.com/evidence/consent-001.pdf",
      "hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
      "file_format": "PDF_A"
    }
  }'

Respuesta exitosa (200) — Persona natural

{
  "code": 200,
  "msg": "Consent created",
  "caseid": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": 12345,
    "consent_token": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": 42,
    "framework": "REDEC",
    "person_type": "NATURAL",
    "person_rut": "12345678-9",
    "person_name": "GARCIA/PEREZ/JUAN CARLOS",
    "person_last_name": null,
    "person_email": "[email protected]",
    "person_phone": "+56912345678",
    "institution_code": "123456789",
    "internal_code": "BCH-NAT-001",
    "purpose": 2,
    "objective": "02",
    "medium": 1,
    "executive_rut": "98765432-1",
    "branch": null,
    "state": "ACTIVE",
    "validity_origin": "REDEC_REGULATION",
    "granted_date": "20260512",
    "granted_time": "143022",
    "expiration_date": "20260602",
    "expiration_time": "235959",
    "accepted_at": "2026-05-12T14:30:22.000Z",
    "expires_at": "2026-06-02T23:59:59.000Z",
    "evidence_url": "https://institution.com/evidence/consent-001.pdf",
    "evidence_hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
    "evidence_status": "SUCCESS",
    "evidence_file_format": "PDF_A",
    "created_by": "GATEWAY_API",
    "has_attorneys": false,
    "caseid": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Respuesta exitosa (200) — Persona jurídica

{
  "code": 200,
  "msg": "Consent created",
  "caseid": "660f9511-f5bd-5bc3-c5e1-065g02340e71",
  "data": {
    "id": 12346,
    "consent_token": "660f9511-f5bd-5bc3-c5e1-065g02340e71",
    "client_id": 42,
    "framework": "REDEC",
    "person_type": "JURIDICA",
    "person_rut": "76543210-K",
    "person_email": "[email protected]",
    "company_rut": "76543210-K",
    "institution_code": "123456789",
    "internal_code": "BCH-JUR-001",
    "purpose": 2,
    "objective": "01",
    "medium": 1,
    "state": "ACTIVE",
    "validity_origin": "REDEC_REGULATION",
    "granted_date": "20260512",
    "expiration_date": "20260602",
    "expiration_time": "235959",
    "evidence_url": "https://institution.com/evidence/consent-001.pdf",
    "evidence_hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
    "evidence_status": "SUCCESS",
    "evidence_file_format": "PDF_A",
    "created_by": "GATEWAY_API",
    "has_attorneys": true,
    "company": {
      "legal_name": "EMPRESA EJEMPLO S.A.",
      "company_rut": "76543210-K",
      "legal_representatives": [
        { "name": "GONZALEZ/SILVA/MARIA TERESA", "rut": "11111111-1", "role": "GERENTE GENERAL" }
      ],
      "grantor": {
        "type": "REPRESENTANTE_LEGAL",
        "name": "GONZALEZ/SILVA/MARIA TERESA",
        "rut": "11111111-1",
        "role": "GERENTE GENERAL"
      }
    },
    "attorneys": [
      { "name": "FERNANDEZ/LOPEZ/CARLOS ANDRES", "rut": "33333333-3", "role": "APODERADO FINANCIERO" }
    ],
    "caseid": "660f9511-f5bd-5bc3-c5e1-065g02340e71"
  }
}

Campos importantes de la respuesta

Campo	Descripción
`consent_token`	UUID del sistema. Úsalo en `get_consent`, `revoke_consent`, `validate_consent`.
`caseid`	Igual a `consent_token`; correlaciona con el registro del request para facturación.
`state`	Estado del consentimiento: `ACTIVE`, `REVOKED`, `EXPIRED`, `EXPIRING_SOON`.
`validity_origin`	Para REDEC siempre `REDEC_REGULATION` (15 días hábiles bancarios).
`evidence_status`	`PENDING`, `SUCCESS`, `FAILED`, `EXTERNAL`. En `FLOID_STORAGE` puede tardar unos segundos en pasar de `PENDING` a `SUCCESS`/`FAILED`.
`granted_date` / `expiration_date`	Formato `YYYYMMDD`. `granted_time` / `expiration_time` en formato `HHMMSS`.

Errores

Todos los errores siguen el envelope legacy con un error_code granular. El error_message va en inglés (máquina/logs); el display_message en español (UI). El HTTP status coincide con code.

{
  "code": 400,
  "error_type": "VALIDATION",
  "error_code": "VALIDATION_ERROR",
  "error_message": "One or more request parameters are invalid",
  "display_message": "person_email es obligatorio para NATURAL",
  "caseid": ""
}

`error_code`	`error_type`	HTTP	Cuándo
`VALIDATION_ERROR`	VALIDATION	400	Falló una validación RDC30. El motivo específico va en `display_message` (RUT inválido, `institution_code` no de 9 dígitos, `purpose`/`medium`/`objective` inválidos, falta `person_email` para NATURAL, `company` inválido, etc.).
`INSTITUTION_CODE_REQUIRED`	VALIDATION	400	Falta `institution_code`.
`EVIDENCE_INVALID`	VALIDATION	400	Evidencia inválida o incompleta para el modo de almacenamiento de la institución (URL no HTTPS, hash mal formado, falta hash en `EXTERNAL_URL_ONLY`, archivo demasiado grande, etc.).
`INSTITUTION_NOT_CONFIGURED`	CONFIGURATION	400	Institución no configurada o inactiva para este cliente.
`DUPLICATE_INTERNAL_CODE`	CONFLICT	400	El `internal_code` ya existe para esta institución.
`INTERNAL_ERROR`	INTERNAL	500	Error de base de datos o excepción no controlada.

Tablas de referencia

Códigos de objetivo (`objective`)

Código	Descripción
`"01"`	Créditos comerciales
`"02"`	Créditos de consumo
`"03"`	Créditos para vivienda
`"04"`	Operaciones financieras
`"05"`	Instrumentos de deuda adquiridos
`"06"`	Créditos contingentes
`"07"`	Cupos de líneas de crédito de libre disposición

Si aplica más de un objetivo, se crea un consentimiento separado por cada uno.

Códigos de finalidad (`purpose`)

Código	Descripción
`1`	Evaluación de riesgo comercial
`2`	Evaluación de riesgo crediticio

Códigos de medio (`medium`)

Código	Descripción
`1`	Electrónico
`2`	Verbal (registro de audio)
`3`	Físico (respaldo documental)

Reglas de validación

Formato de campos

institution_code: exactamente 9 dígitos numéricos.
internal_code: máx 20 caracteres. Permitidos: A-Z, 0-9, ., _, -, /.
person_rut y todo RUT: formato chileno (12345678-9) con validación módulo-11.
person_name: formato RDC30 APELLIDO_PATERNO/APELLIDO_MATERNO/NOMBRES en mayúsculas.
person_email: email válido estándar.
person_phone: 8–15 dígitos, prefijo + opcional.
objective: siempre 2 dígitos con cero a la izquierda ("01"–"07").
evidence.hash: exactamente 64 caracteres hexadecimales.

Reglas de negocio

Unicidad: internal_code único por institución.
Consistencia de RUT (JURIDICA): person_rut debe ser igual a company.company_rut.
Representantes legales (JURIDICA): al menos 1.
Otorgante (JURIDICA): el rut del otorgante debe existir en legal_representatives o attorneys.
Contacto (NATURAL): person_email obligatorio. person_phone opcional.
Hash de evidencia: obligatorio para EXTERNAL_URL_ONLY, opcional para FLOID_STORAGE.

Vigencia

Los consentimientos REDEC tienen una vigencia de 15 días hábiles bancarios desde la fecha de aceptación (lógica única de vigencia, sin overrides). El día hábil 15 es la fecha de expiración y el consentimiento sigue vigente durante todo ese día (235959).

Modos de almacenamiento de evidencia

Se configuran por institución (no en el request).

`FLOID_STORAGE`

Floid descarga el archivo desde evidence.url.
Floid calcula el hash SHA-256 si no se envía.
Floid almacena el archivo en Google Cloud Storage.
evidence.hash es opcional.

`EXTERNAL_URL_ONLY`

Floid no descarga el archivo.
El cliente almacena el archivo.
Floid solo guarda la URL y el hash.
evidence.hash es obligatorio.