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 (prod): https://api.floid.app/cl/consent_manager/create_consent
• URL sandbox: https://sandbox.floid.app/cl/consent_manager/create_consent
• Versión API: 3.1.0 (RDC30 Compliance)

Headers requeridos

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

Para subir el archivo de evidencia directamente (en lugar de pasar evidence.url), enviá la request como Content-Type: multipart/form-data con el archivo en el campo consent_file. Sólo aplica si tu institución está configurada en modo FLOID_STORAGE.

Parámetros de entrada

Campos obligatorios (todos los consentimientos)

id_cliente es derivado del Bearer token. Si lo enviás en el body, el servidor lo ignora. No lo incluyas.

Evidencia (siempre requerida)

¹ EXTERNAL_URL_ONLY (configurado por institución): hash obligatorio.
¹ FLOID_STORAGE (configurado por institución): Floid descarga el archivo, calcula el hash y lo guarda en GCS. Hash opcional.

Campos condicionales — Persona Natural

Si tipo_persona = "NATURAL":

Campos condicionales — Persona Jurídica

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

Campos opcionales

Sandbox. Para crear consentimientos de prueba, usá https://sandbox.floid.app/... con tus credenciales de sandbox. La respuesta incluirá data.sandbox_mode: true. La flag sandbox: true en el body sigue funcionando por compatibilidad pero ya no es la forma recomendada — usá el host.

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 '{
    "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 '{
    "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) — Persona Natural

{
  "code": "200",
  "msg": "OK",
  "caseid": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "consent_id": 12345,
    "consent_token": "550e8400-e29b-41d4-a716-446655440000",
    "custom_id": null,
    "codigo_interno_consentimiento": "BCH-NAT-001",
    "codigo_encriptado_consentimiento": "A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890A1B2C3D4E5F67890",
    "tipo_persona": "NATURAL",
    "timestamp_otorgamiento": "20260512 143022",
    "timestamp_expiracion": "20270512 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"
    }
  }
}

Respuesta exitosa (200) — Persona Jurídica

{
  "code": "200",
  "msg": "OK",
  "caseid": "660f9511-f5bd-5bc3-c5e1-065g02340e71",
  "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": { /* mismo bloque que enviaste */ },
    "timestamp_otorgamiento": "20260512 143022",
    "timestamp_expiracion": "20270512 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"
    }
  }
}

Campos importantes en la respuesta

Posibles errores

Todos los errores siguen el envelope estándar:

{
  "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: tipo_persona",
  "caseid": ""
}

Tip para detectar duplicados: parseá el display_message ("Duplicate codigo_interno_consentimiento"); el error_code siempre es INVALID_REQUEST.

Tablas de referencia

Códigos de objetivo

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

Códigos de finalidad

Códigos de medio

Reglas de validación

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 y todos los 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_cellphone: 8–15 dígitos, opcionalmente con prefijo +.
• objetivo: siempre 2 dígitos con cero a la izquierda ("01"–"07").
• evidence.hash: exactamente 64 caracteres hexadecimales (0-9, A-F/a-f).

Reglas de negocio

• Unicidad: codigo_interno_consentimiento único por institución.
• Consistencia RUT (JURIDICA): person_rut debe ser igual a persona_juridica.rut_empresa.
• Representantes legales (JURIDICA): mínimo 1.
• Otorgante (JURIDICA): el rut del otorgante debe existir en representantes_legales o apoderados.
• Contacto (NATURAL): person_email requerido. person_cellphone opcional.
• Hash de evidencia: obligatorio para EXTERNAL_URL_ONLY, opcional para FLOID_STORAGE.

Validaciones de evidencia

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

Modos de almacenamiento de evidencia

Configurado 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 sólo guarda la URL y el hash.
• evidence.hash es obligatorio.

Cambios desde v2.1

1. codigo_interno_consentimiento ahora es estrictamente obligatorio (antes se auto-generaba desde custom_id).
2. tipo_persona es ahora obligatorio (campo nuevo).
3. rut_ejecutivo es ahora opcional (antes obligatorio).
4. person_email ya no es obligatorio para JURIDICA.
5. Nuevo objeto persona_juridica para empresas.
6. Nuevo objeto evidence para gestión de evidencias.

Cambios desde v3.0

7. Sandbox host-aware: el dominio determina el ambiente (ver Notas Importantes).
8. Operaciones de listado/exportación ahora reportan sandbox_mode en la respuesta.

Versionamiento

• v2.1: hasta enero 2026.
• v3.0: febrero 2026 — RDC30 Compliance.
• v3.1: mayo 2026 — sandbox host-aware, JSON envelope para exports/reportes con archivo.
• Fecha efectiva obligatoria CMF: 1 de abril de 2026.

Última actualización: 12 de mayo de 2026.