Crear Consentimiento

POST /cl/consent_manager/create_consent

Registra un nuevo consentimiento de consulta de información comercial o crediticia según normativa RDC30 (NCG 540).

URL Completa: https://api.floid.app/cl/consent_manager/create_consent

Versión API: 3.0.0 (RDC30 Compliance)

Headers Requeridos

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

Parámetros de Entrada

Campos Obligatorios (Todos los Consentimientos)

Campo	Tipo	Descripción	Ejemplo
`id_cliente`	integer	ID del cliente en sistema Floid	`123`
`codigo_institucion`	string	Código de 9 dígitos de la institución (CMF)	`"123456789"`
`codigo_interno_consentimiento`	string	Código único por institución (máx 20 caracteres)	`"BCH-2026-001"`
`tipo_persona`	string	Tipo de persona: `NATURAL` o `JURIDICA`	`"NATURAL"`
`person_rut`	string	RUT de la persona/empresa que otorga consentimiento	`"12345678-9"`
`medio`	integer	Medio de obtención: `1`=Electrónico, `2`=Verbal, `3`=Físico	`1`
`finalidad`	integer	Finalidad: `1`=Riesgo comercial, `2`=Riesgo crediticio	`2`
`objetivo`	string	Código de objetivo (01-07, ver tabla de referencia)	`"02"`

Evidencia

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	Si	`PDF_A` o `MP3`

Nota 1: En modo EXTERNAL_URL_ONLY, el hash SHA-256 es obligatorio y debe ser proporcionado por el cliente.

Nota 2: En modo FLOID_STORAGE, Floid descargará el archivo, calculará el hash SHA-256 y almacenará en GCS. El hash es opcional (se genera automáticamente si no se provee).

Campos Condicionales - Persona Natural

Si tipo_persona = "NATURAL", se requiere al menos uno de:

Campo	Tipo	Requerido	Descripción
`person_email`	string	Sí*	Email de la persona
`person_cellphone`	string	Sí*	Teléfono celular (formato: +56912345678)
`person_name`	string	No	Nombre completo (formato: APELLIDO/APELLIDO/NOMBRES)

*Al menos uno requerido (email O celular)

Campos Condicionales - Persona Jurídica

Si tipo_persona = "JURIDICA", se requiere el objeto persona_juridica:

Campo	Tipo	Requerido	Descripción
`persona_juridica.razon_social`	string	Sí	Razón social de la empresa
`persona_juridica.rut_empresa`	string	Sí	RUT de la empresa (debe coincidir con person_rut)
`persona_juridica.representantes_legales`	array	Sí	Mínimo 1 representante legal
`persona_juridica.representantes_legales[].nombre`	string	Sí	Nombre del representante
`persona_juridica.representantes_legales[].rut`	string	Sí	RUT del representante
`persona_juridica.representantes_legales[].cargo`	string	No	Cargo del representante
`persona_juridica.apoderados`	array	No	Lista de apoderados
`persona_juridica.apoderados[].nombre`	string	Sí	Nombre del apoderado
`persona_juridica.apoderados[].rut`	string	Sí	RUT del apoderado
`persona_juridica.apoderados[].cargo`	string	No	Cargo del apoderado
`persona_juridica.otorgante`	object	Sí	Persona que otorgó el consentimiento
`persona_juridica.otorgante.tipo`	string	Sí	`REPRESENTANTE_LEGAL` o `APODERADO`
`persona_juridica.otorgante.nombre`	string	Sí	Nombre del otorgante
`persona_juridica.otorgante.rut`	string	Sí	RUT del otorgante (debe existir en las listas)
`persona_juridica.otorgante.cargo`	string	No	Cargo del otorgante

Campos Opcionales

Campo	Tipo	Descripción
`rut_ejecutivo`	string	RUT del ejecutivo (si vacío, usa default de configuración)
`rut_empresa`	string	RUT de empresa relacionada
`custom_id`	string	ID externo para referencia (máx 100 caracteres, backward compatibility)
`metadata_json`	string	JSON string con metadata adicional
`origen_batch`	boolean	Indica si proviene de carga masiva
`sandbox`	boolean	Activa modo sandbox para testing

Ejemplo 1: Persona Natural Simple

curl --location 'https://api.floid.app/cl/consent_manager/create_consent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{TOKEN}}' \
--data '{
  "id_cliente": 123,
  "codigo_institucion": "123456789",
  "codigo_interno_consentimiento": "BCH-NAT-001",
  "tipo_persona": "NATURAL",
  "person_rut": "12345678-9",
  "person_name": "GARCIA/PEREZ/JUAN CARLOS",
  "person_email": "[email protected]",
  "person_cellphone": "+56912345678",
  "medio": 1,
  "finalidad": 2,
  "objetivo": "02",
  "rut_ejecutivo": "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 '{
  "id_cliente": 123,
  "codigo_institucion": "123456789",
  "codigo_interno_consentimiento": "BCH-JUR-001",
  "tipo_persona": "JURIDICA",
  "person_rut": "76543210-K",
  "person_email": "[email protected]",
  "persona_juridica": {
    "razon_social": "EMPRESA EJEMPLO S.A.",
    "rut_empresa": "76543210-K",
    "representantes_legales": [
      {
        "nombre": "GONZALEZ/SILVA/MARIA TERESA",
        "rut": "11111111-1",
        "cargo": "GERENTE GENERAL"
      }
    ],
    "apoderados": [
      {
        "nombre": "FERNANDEZ/LOPEZ/CARLOS ANDRES",
        "rut": "33333333-3",
        "cargo": "APODERADO FINANCIERO"
      }
    ],
    "otorgante": {
      "tipo": "REPRESENTANTE_LEGAL",
      "nombre": "GONZALEZ/SILVA/MARIA TERESA",
      "rut": "11111111-1",
      "cargo": "GERENTE GENERAL"
    }
  },
  "medio": 1,
  "finalidad": 2,
  "objetivo": "01",
  "rut_ejecutivo": "98765432-1",
	"evidence": {
    "url": "https://institution.com/evidence/consent-001.pdf",
    "hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
    "file_format": "PDF_A"
  }
}'

Respuesta Exitosa (200)

{
  "code": "200",
  "msg": "OK",
  "caseid": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "consent_id": 12345,
    "consent_token": "550e8400-e29b-41d4-a716-446655440000",
    "codigo_interno_consentimiento": "BCH-2026-001",
    "codigo_encriptado_consentimiento": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
    "custom_id": null,
    "tipo_persona": "NATURAL",
    "timestamp_otorgamiento": "20260202 143022",
    "timestamp_expiracion": "20260223 143022",
    "estado": "ACTIVE",
    "origen": "API",
    "fingerprint_processed": false,
    "fingerprint_hash": null,
    "ip_captured": "172.19.0.7",
    "user_agent_captured": true,
    "file_uploaded": false,
    "file_url": null,
    "gcs_path": null,
    "evidence": {
      "url": "https://institution.com/evidence/consent-001.pdf",
      "hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
      "format": "PDF_A",
      "storage_mode": "FLOID_STORAGE",
      "status": "SUCCESS"
    }
  }
}

Campos Importantes en Respuesta:

codigo_interno_consentimiento: Código único proporcionado por la institución
codigo_encriptado_consentimiento: Hash SHA-256 de la evidencia (si aplica)
consent_token: UUID del sistema (para consultas posteriores)
evidence.status: Estado del procesamiento (PENDING, SUCCESS, FAILED, EXTERNAL)

Respuesta Persona Jurídica (200)

{
  "code": "200",
  "msg": "OK",
  "caseid": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "consent_id": 12346,
    "consent_token": "660f9511-f5bd-5bc3-c5e1-065g02340e71",
    "codigo_interno_consentimiento": "BCH-JUR-001",
    "codigo_encriptado_consentimiento": null,
    "tipo_persona": "JURIDICA",
    "persona_juridica": {
      "razon_social": "EMPRESA EJEMPLO S.A.",
      "rut_empresa": "76543210-K",
      "representantes_legales": [
        {
          "nombre": "GONZALEZ/SILVA/MARIA TERESA",
          "rut": "11111111-1",
          "cargo": "GERENTE GENERAL"
        }
      ],
      "apoderados": [
        {
          "nombre": "FERNANDEZ/LOPEZ/CARLOS ANDRES",
          "rut": "33333333-3",
          "cargo": "APODERADO FINANCIERO"
        }
      ],
      "otorgante": {
        "tipo": "REPRESENTANTE_LEGAL",
        "nombre": "GONZALEZ/SILVA/MARIA TERESA",
        "rut": "11111111-1",
        "cargo": "GERENTE GENERAL"
      }
    },
    "timestamp_otorgamiento": "20260202 143022",
    "timestamp_expiracion": "20260223 143022",
    "estado": "ACTIVE",
    "origen": "API",
		"evidence": {
      "url": "https://institution.com/evidence/consent-001.pdf",
      "hash": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
      "format": "PDF_A",
      "storage_mode": "FLOID_STORAGE",
      "status": "SUCCESS"
    }
  }
}

Posibles Errores

Error Code	HTTP	Descripción
`INVALID_REQUEST`	400	Falta campo obligatorio (ver mensaje específico)
`RUT_NO_VALIDO`	400	RUT no tiene formato válido o no pasa validación modulo-11
`ERR_CONSENT_001`	400	`tipo_persona` debe ser NATURAL o JURIDICA
`ERR_CONSENT_002`	400	`codigo_interno_consentimiento` formato inválido (máx 20 chars, caracteres permitidos: A-Z, 0-9, &, ', /, _, -)
`ERR_CONSENT_003`	409	`codigo_interno_consentimiento` duplicado para esta institución
`ERR_CONSENT_004`	400	Estructura `persona_juridica` inválida o incompleta
`ERR_CONSENT_005`	400	`otorgante.rut` no existe en listas de representantes o apoderados
`ERR_CONSENT_006`	400	`evidence.hash` formato inválido (debe ser 64 caracteres hexadecimales)
`ERR_CONSENT_007`	400	`evidence.hash` requerido para modo EXTERNAL_URL_ONLY
`ERR_CONSENT_008`	500	Error descargando evidencia desde URL
`ERR_CONSENT_009`	400	Hash proporcionado no coincide con archivo descargado
`ERR_CONSENT_010`	404	Institución no configurada (contactar administrador)
`INVALID_REQUEST`	400	Código institución debe ser exactamente 9 dígitos
`INVALID_REQUEST`	400	Finalidad debe ser 1 o 2
`INVALID_REQUEST`	400	Medio debe ser 1, 2 o 3
`INVALID_REQUEST`	400	Objetivo debe estar entre 01 y 07
`INVALID_REQUEST`	400	person_email O person_cellphone requerido para NATURAL
`INVALID_REQUEST`	400	person_rut debe coincidir con rut_empresa para JURIDICA
`INVALID_REQUEST`	400	Evidence URL debe usar protocolo HTTPS
`INTERNAL_ERROR`	500	Error de conexión a base de datos

Tablas de Referencia

Códigos de Objetivo

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

Nota: Si aplica más de un objetivo, crear consentimientos separados.

Códigos de Finalidad

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

Códigos de Medio

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

Reglas de Validación

1. Formato de Campos

codigo_institucion: Exactamente 9 dígitos numéricos
codigo_interno_consentimiento: Máximo 20 caracteres. Permitidos: A-Z, 0-9, &, ', /, _, -
person_rut: Formato chileno válido (ej: 12345678-9) con validación modulo-11
person_name: Formato RDC30: APELLIDO_PATERNO/APELLIDO_MATERNO/NOMBRES (mayúsculas)
person_email: Formato email válido estándar
person_cellphone: 8-15 dígitos, opcionalmente con prefijo + (ej: +56912345678)
objetivo: Debe tener cero inicial (ej: "01", "02", no "1", "2")
evidence.hash: Exactamente 64 caracteres hexadecimales (0-9, A-F)

2. Reglas de Negocio

Unicidad: codigo_interno_consentimiento debe ser único por institución
Consistencia RUT: Para JURIDICA, person_rut debe igual persona_juridica.rut_empresa
Representantes: Mínimo 1 representante legal para JURIDICA
Otorgante: Debe existir en lista de representantes legales o apoderados
Contacto: Para NATURAL, al menos email O teléfono requerido
Evidence hash: Obligatorio para EXTERNAL_URL_ONLY, opcional para FLOID_STORAGE

3. Validaciones de Evidencia

URL debe usar protocolo HTTPS
Hash SHA-256 debe ser exactamente 64 caracteres hexadecimales
Tamaño máximo archivo: 8 MB
Formatos permitidos:
- PDF/A: Para medio Electrónico (1) o Físico (3)
- MP3: Para medio Verbal (2) - bitrate 192 kbps, sample rate 16-48 kHz

Notas Importantes

⚠️ Cambios desde v2.1

codigo_interno_consentimiento ahora es obligatorio (antes se auto-generaba)
tipo_persona ahora es obligatorio (nuevo campo)
rut_ejecutivo ahora es opcional (antes obligatorio)
person_email ya no es obligatorio para JURIDICA
Nuevo objeto persona_juridica para empresas
Nuevo objeto evidence para gestión de evidencias

💡 Backward Compatibility

✅ Campo custom_id sigue funcionando (mapea a id_externo)
✅ Si no se envía codigo_interno_consentimiento, se trunca custom_id a 20 caracteres
✅ Si no se envía tipo_persona, se asume NATURAL (con advertencia en logs)
✅ Si no se envía rut_ejecutivo, se usa el RUT contraparte de la configuración

🔒 Modos de Almacenamiento de Evidencia

El modo se configura por institución (no en el request):

FLOID_STORAGE:

Floid descarga el archivo desde la URL
Floid calcula el hash SHA-256 (si no se proporciona)
Floid almacena el archivo en Google Cloud Storage
evidence.hash es opcional

EXTERNAL_URL_ONLY:

Floid NO descarga el archivo
Cliente almacena el archivo
Floid solo guarda URL + hash
evidence.hash es obligatorio (64 chars hex)

Ejemplo de Error

{
  "code": "400",
  "msg": "INVALID_REQUEST",
  "caseid": "",
  "error": "Missing required field: tipo_persona"
}

{
  "code": "409",
  "msg": "INVALID_REQUEST",
  "caseid": "",
  "error": "Duplicate codigo_interno_consentimiento for this institution"
}

{
  "code": "400",
  "msg": "INVALID_REQUEST",
  "caseid": "",
  "error": "Invalid persona_juridica: otorgante.rut must exist in representantes_legales or apoderados list"
}

Versionamiento

v2.1: Versión anterior (hasta enero 2026)
v3.0: Versión actual (desde febrero 2026) - RDC30 Compliance
Fecha efectiva obligatoria: 1 de abril de 2026

Última actualización: 2 de febrero de 2026
Versión documento: 1.0