API de Creación de Consentimientos (RDC30)

Descripción General

Esta API permite crear y registrar consentimientos de consulta de información comercial y crediticia según la normativa chilena RDC30 de la Comisión para el Mercado Financiero (CMF). El sistema registra, almacena y audita todos los consentimientos otorgados por personas naturales para la consulta de sus datos en boletines comerciales.

Autenticación

La API requiere autenticación mediante token Bearer y cookie de sesión:

Authorization: Bearer {{TOKEN}}

Endpoint: Crear Consentimiento

POST /cl/consent_manager/consent

Registra un nuevo consentimiento de consulta de información comercial o crediticia.

URL de Producción: https://api.floid.app/cl/consent_manager/consent

Headers Requeridos

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

Parámetros de Entrada

Campo	Tipo	Requerido	Descripción
`person_rut`	string	Sí	RUT de la persona que otorga el consentimiento (formato: 12345678-9)
`codigo_institucion`	string	Sí	Código de 9 dígitos de la institución solicitante (formato: 001234567)
`finalidad`	integer	Sí	Finalidad del consentimiento: `1` = Riesgo comercial, `2` = Riesgo crediticio
`objetivo`	string	Sí	Código de objetivo de consulta (formato: "01" a "07")
`medio`	integer	Sí	Medio de obtención: `1` = Electrónico, `2` = Verbal, `3` = Escrito
`person_email`	string	No*	Email de la persona (requerido si `person_cellphone` no está presente)
`person_cellphone`	string	No*	Teléfono celular (formato: +56912345678, requerido si `person_email` no está)
`person_name`	string	No	Nombre completo de la persona
`rut_empresa`	string	No	RUT de la empresa relacionada (formato: 12345678-9)
`rut_ejecutivo`	string	No	RUT del ejecutivo que gestiona el consentimiento (formato: 12345678-9)
`custom_id`	string	No	ID externo único para referencia (alfanumérico, guiones, guiones bajos, max 100)
`metadata_json`	string	No	JSON string con metadata adicional (ej: fingerprint del navegador)
`origen_batch`	boolean	No	Indica si el consentimiento proviene de carga masiva

* Al menos uno de person_email o person_cellphone es requerido para consentimientos web.

Validaciones RDC30

La API valida estrictamente según normativa RDC30:

RUT: Formato chileno válido con dígito verificador (12345678-9)
Código Institución: Exactamente 9 dígitos numéricos
Finalidad: Solo valores 1 o 2
Medio: Solo valores 1, 2 o 3
Objetivo: Solo códigos del "01" al "07"
Custom ID: Si se proporciona, debe ser único (no duplicados)

Códigos de Objetivo

Código	Descripción
`01`	Evaluación crediticia inicial
`02`	Seguimiento de obligaciones vigentes
`03`	Renovación o restructuración de crédito
`04`	Evaluación comercial
`05`	Verificación de antecedentes
`06`	Consulta para garantías
`07`	Otras finalidades autorizadas

Subida de Archivos (Opcional)

El endpoint soporta subida de archivos adjuntos según el medio:

Medio 1 (Electrónico): JPG, PNG, PDF (máx 8MB)
Medio 2 (Verbal): MP3, WAV, M4A, OGG (máx 8MB)
Medio 3 (Escrito): PDF, DOCX, JPG, PNG (máx 8MB)

Para enviar archivos, usar Content-Type: multipart/form-data con el campo consent_file.

Ejemplo de Solicitud (JSON)

curl --location 'https://api.floid.app/cl/consent_manager/consent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{TOKEN}}' \
--data '{
  "person_rut": "12345678-9",
  "person_email": "[email protected]",
  "person_name": "Juan Pérez González",
  "codigo_institucion": "001234567",
  "finalidad": 2,
  "objetivo": "02",
  "medio": 1,
  "rut_empresa": "76123456-7",
  "rut_ejecutivo": "11223344-5",
  "custom_id": "CONSENT-2024-001"
}'

Ejemplo de Solicitud (Multipart con Archivo)

curl --location 'https://api.floid.app/cl/consent_manager/consent' \
--header 'Authorization: Bearer {{TOKEN}}' \
--form 'person_rut="12345678-9"' \
--form 'person_email="[email protected]"' \
--form 'codigo_institucion="001234567"' \
--form 'finalidad="2"' \
--form 'objetivo="02"' \
--form 'medio="1"' \
--form 'custom_id="CONSENT-2024-001"' \
--form 'consent_file=@"/ruta/al/archivo/consentimiento.pdf"'

Respuestas

200 - Consentimiento Creado Exitosamente

{
  "code": "200",
  "msg": "OK",
  "caseid": "a9a628a1-b4ac-4ab2-b4d0-954f91239d60",
  "data": {
    "consent_id": 123,
    "consent_token": "a9a628a1-b4ac-4ab2-b4d0-954f91239d60",
    "custom_id": "TEST-2024-001",
    "codigo_interno": "C2511201752588870878",
    "timestamp_otorgamiento": "20251120 175258",
    "timestamp_expiracion": "20261120 175258",
    "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
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
`consent_id`	integer	ID numérico interno del consentimiento
`consent_token`	string	UUID único del consentimiento (usar para consultas posteriores)
`custom_id`	string	ID externo proporcionado en el request (si aplica)
`codigo_interno`	string	Código interno generado por el sistema (max 20 caracteres)
`timestamp_otorgamiento`	string	Fecha y hora de otorgamiento (formato: YYYYMMDD HHMMSS)
`timestamp_expiracion`	string	Fecha y hora de expiración (formato: YYYYMMDD HHMMSS)
`estado`	string	Estado del consentimiento: `ACTIVE`, `REVOKED`, `EXPIRED`
`origen`	string	Origen del consentimiento: `API`, `WEB`, `BATCH`
`fingerprint_processed`	boolean	Indica si se procesó fingerprint del navegador
`fingerprint_hash`	string	Hash único del fingerprint (si aplica)
`ip_captured`	string	IP del cliente que otorgó el consentimiento
`user_agent_captured`	boolean	Indica si se capturó el User-Agent del navegador
`file_uploaded`	boolean	Indica si se subió un archivo adjunto
`file_url`	string	URL firmada para acceder al archivo (válida por 10 años)
`gcs_path`	string	Ruta del archivo en Google Cloud Storage

400 - Campo Requerido Faltante

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Missing required field: person_rut",
  "caseid": ""
}

400 - RUT Inválido

{
  "code": 400,
  "error_type": "INVALID_ID",
  "error_code": "RUT_NO_VALIDO",
  "error_message": "the provided ID is not valid",
  "display_message": "El rut no es valido.",
  "caseid": ""
}

400 - Código de Institución Inválido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid codigo_institucion: must be exactly 9 digits",
  "caseid": ""
}

400 - Finalidad Inválida

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid finalidad: must be 1 (commercial risk) or 2 (credit risk)",
  "caseid": ""
}

400 - Medio Inválido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid medio: must be 1 (electronic), 2 (verbal), or 3 (written)",
  "caseid": ""
}

400 - Objetivo Inválido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid objetivo: must be between 01 and 07",
  "caseid": ""
}

400 - Email Inválido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid person_email: must be a valid email address",
  "caseid": ""
}

400 - Custom ID Duplicado

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Duplicate custom_id: this custom_id already exists",
  "caseid": ""
}

400 - Archivo Demasiado Grande

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. File too large: maximum 8MB allowed",
  "caseid": ""
}

400 - Tipo de Archivo Inválido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Invalid file type for medio 1: expected images (JPG, PNG) or PDF, got application/msword",
  "caseid": ""
}

400 - Método No Permitido

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. Method not allowed. Use POST.",
  "caseid": ""
}

400 - Error Interno

{
  "code": 400,
  "error_type": "INTERNAL_ERROR",
  "error_code": "INTERNAL_ERROR",
  "error_message": "Something went wrong on our side. Please try again.",
  "display_message": "Algo falló desde nuestro lado. Por favor intenta nuevamente.",
  "caseid": ""
}

Códigos de Error

Formato Estándar de Errores

Todos los errores siguen el formato estándar de la compañía:

{
  "code": 400,
  "error_type": "API_ERROR",
  "error_code": "INVALID_REQUEST",
  "error_message": "The request is not valid. Check the body and headers and try again.",
  "display_message": "La request no es válida. Revisa el body y headers e intenta nuevamente. [detalles del error]",
  "caseid": ""
}

Errores Comunes

Código HTTP	Error Code	Error Type	Causa
400	INVALID_REQUEST	API_ERROR	Falta un campo obligatorio
400	RUT_NO_VALIDO	INVALID_ID	RUT no tiene formato válido
400	INVALID_REQUEST	API_ERROR	Código debe ser exactamente 9 dígitos
400	INVALID_REQUEST	API_ERROR	Finalidad debe ser 1 o 2
400	INVALID_REQUEST	API_ERROR	Medio debe ser 1, 2 o 3
400	INVALID_REQUEST	API_ERROR	Objetivo debe estar entre 01 y 07
400	INVALID_REQUEST	API_ERROR	El custom_id ya existe en el sistema
400	INVALID_REQUEST	API_ERROR	Email no tiene formato válido
400	INVALID_REQUEST	API_ERROR	Archivo supera 8MB
400	INVALID_REQUEST	API_ERROR	Tipo de archivo no permitido para el medio
400	INVALID_REQUEST	API_ERROR	Se intentó usar GET u otro método no permitido
400	INTERNAL_ERROR	INTERNAL_ERROR	Error de conexión a base de datos

Casos de Uso

Caso 1: Consentimiento Electrónico Simple

Solicitud de crédito online donde el usuario acepta consulta de información crediticia.

{
  "person_rut": "12345678-9",
  "person_email": "[email protected]",
  "codigo_institucion": "001234567",
  "finalidad": 2,
  "objetivo": "01",
  "medio": 1,
  "custom_id": "LOAN-REQUEST-2024-12345"
}

Caso 2: Consentimiento Verbal con Audio

Llamada telefónica donde se obtiene consentimiento verbal del cliente.

curl --location 'https://api.floid.app/cl/consent_manager/consent' \
--header 'Authorization: Bearer {{TOKEN}}' \
--form 'person_rut="12345678-9"' \
--form 'person_cellphone="+56912345678"' \
--form 'codigo_institucion="001234567"' \
--form 'finalidad="1"' \
--form 'objetivo="04"' \
--form 'medio="2"' \
--form 'rut_ejecutivo="11223344-5"' \
--form 'consent_file=@"/audio/grabacion_consentimiento.mp3"'

Caso 3: Consentimiento Escrito con Documento Firmado

Documento físico firmado en sucursal, escaneado y subido al sistema.

curl --location 'https://api.floid.app/cl/consent_manager/consent' \
--header 'Authorization: Bearer {{TOKEN}}' \
--form 'person_rut="12345678-9"' \
--form 'person_name="Juan Pérez"' \
--form 'codigo_institucion="001234567"' \
--form 'finalidad="2"' \
--form 'objetivo="02"' \
--form 'medio="3"' \
--form 'rut_ejecutivo="11223344-5"' \
--form 'custom_id="BRANCH-2024-11-20-001"' \
--form 'consent_file=@"/documents/consentimiento_firmado.pdf"'

Caso 4: Carga Masiva (Batch)

Procesamiento de consentimientos obtenidos en sucursal física.

{
  "person_rut": "12345678-9",
  "person_name": "Juan Pérez",
  "codigo_institucion": "001234567",
  "finalidad": 2,
  "objetivo": "02",
  "medio": 3,
  "rut_ejecutivo": "11223344-5",
  "origen_batch": true,
  "custom_id": "BATCH-2024-11-20-001"
}

Características del Sistema

Validaciones RDC30

RUT Chileno: Validación estricta de formato con dígito verificador (ej: 12345678-9)
Código Institución: Exactamente 9 dígitos numéricos
Finalidad: Solo valores 1 (riesgo comercial) o 2 (riesgo crediticio)
Medio: 1 (electrónico), 2 (verbal) o 3 (escrito)
Objetivo: Códigos del "01" al "07" según tipo de operación
Email: Validación de formato RFC compliant
Teléfono: 8-15 dígitos, opcionalmente con prefijo +

Vigencia de Consentimientos

Duración: 1 año desde fecha de otorgamiento (configurable)
Formato de Timestamps: YYYYMMDD HHMMSS (ej: 20251120 175258)
Expiración Automática: Sistema marca como EXPIRED al vencer
Timezone: Servidor local (Chile/Continental)

Trazabilidad y Auditoría

Registro Completo: Cada operación se registra en tabla de auditoría
Captura Automática: IP, User-Agent, timestamp de todas las operaciones
Historial Inmutable: Los registros de auditoría no pueden modificarse
Tipos de Acción: CREATED, UPDATED, REVOKED, EXPIRED
Origen Identificado: API, WEB, BATCH, ADMIN, SYSTEM

Almacenamiento de Archivos

Ubicación: Google Cloud Storage (GCS)
Estructura: consentimientos/{institucion}/{year}/{month}/{filename}.{ext}
Tipos Permitidos por Medio:
- Electrónico (1): JPG, PNG, PDF
- Verbal (2): MP3, WAV, M4A, OGG
- Escrito (3): PDF, DOCX, JPG, PNG
Tamaño Máximo: 8MB por archivo
URLs Firmadas: Válidas por 10 años para documentos legales
Validación MIME: Verificación de tipo real del archivo (no solo extensión)

Identificadores Únicos

Consent Token: UUID v4 generado automáticamente (ej: a9a628a1-b4ac-4ab2-b4d0-954f91239d60)
Custom ID: ID externo alfanumérico opcional (max 100 caracteres)
Código Interno: Generado automáticamente (max 20 caracteres, formato: C + timestamp + hash)
Unicidad: Tanto consent_token como custom_id son únicos a nivel de base de datos

Seguridad

Autenticación Obligatoria: Token Bearer + PHPSESSID en todas las requests
Solo POST: No se permiten métodos GET para evitar logging de datos sensibles en URLs
Prepared Statements: Todas las queries usan safe_query con parámetros vinculados
Validación de Entrada: Sanitización y validación estricta de todos los campos
Logs Detallados: Error logging con timestamps y contexto completo

Consideraciones de Implementación

Recomendaciones de Integración

Validar localmente: Verificar formato de RUT, email, teléfono antes de enviar
Usar custom_id: Facilita correlación con sus sistemas internos
Almacenar tokens: Guardar consent_token para consultas posteriores
Implementar retry: Usar backoff exponencial para errores de tipo INTERNAL_ERROR
Adjuntar evidencia: Subir PDF firmado, audio, o documento escaneado según medio
Capturar fingerprint: En aplicaciones web, enviar fingerprint del navegador en metadata_json

Flujo de Integración

Autenticación: Obtener token Bearer del sistema de autenticación de Floid
Crear Consentimiento: Enviar datos validados al endpoint /consent
Almacenar Tokens: Guardar consent_token y custom_id en sistema local
Usar Consentimiento: Utilizar el consent_token como evidencia de autorización

Soporte Técnico

Para soporte técnico o consultas sobre la integración, proporcionar:

consent_token o custom_id del consentimiento afectado
Timestamp de la operación
Request completo (sin datos sensibles)
Response recibida del servidor
Logs de errores de la aplicación cliente

Documentación actualizada: Noviembre 2025
Versión API: 1.0
Sistema: Gestión de Consentimientos RDC30
Normativa: CMF RDC30 - Chile