Crea plantillas

Crea plantillas

Una plantilla de disclosure define qué datos pides al usuario al momento de verificar su identidad, junto con qué documentos legales acompañan el flujo. Usa estas plantillas para estandarizar tus procesos antes de verificar la identidad de un usuario.

Qué es una plantilla de disclosure

Una plantilla de disclosure es un modelo reutilizable que define:

• Qué datos solicitar al usuario durante la verificación de identidad
• Para qué tipo de usuario aplica (cliente, empleado, prospecto)
• Qué documentos legales respaldan la solicitud (opcional)
• Por cuánto tiempo puedes usar los datos verificados

Las plantillas te ayudan a estandarizar tus procesos y mantener consistencia en tus reportes y evidencias.

Configuración básica

1. Define nombre y vigencia

Usa el campo name para reconocer la plantilla desde el Dashboard. Define la vigencia en duration usando una duración ISO 8601. Esto determina por cuánto tiempo puedes acceder a los datos del usuario después de que verifique su identidad.

{
  "name": "Validación estándar",
  "duration": "P3M"
}

2. Selecciona el sujeto de datos

El campo data_subject delimita para quién aplica el flujo (por ejemplo, customer, employee o prospect). Alinea esta selección con los perfiles que estás verificando para que tus reportes y evidencias sean consistentes.

3. Define los datos que necesitas

Los data_requirements definen los datos personales que el usuario debe entregar al momento de verificar su identidad. Estos datos se extraen automáticamente del documento de identidad (cédula, pasaporte, etc.).

Cada elemento acepta:

• key: identificador del dato en el flujo
• data_category: categoría según la taxonomía de datos
• data_uses: lista de usos permitidos para ese dato

Elige la llave correcta

Usa llaves descriptivas como name, last_name, date_of_birth o cl_carnet_rut. Estas claves se reconocen automáticamente por la API y también se usan para los matchers en POST /api/v1/disclosure_requests. Si necesitas una clave propia, defínela con claridad y especifica la categoría manualmente.

Match de datos y prevención de fraude

Las llaves que definas aquí deben coincidir con los matchers que uses al crear un disclosure request. Los matchers son fundamentales para la prevención de fraude en plataformas de comercio, ya que validan que la identidad verificada corresponde a los datos que el usuario proporcionó al registrarse.

Recomendación: Define al menos las llaves cl_carnet_rut, name, last_name y date_of_birth en tus plantillas para poder usar matchers completos. Aprende más sobre el match de datos para entender cómo funciona esta validación.

Define categorías de datos y usos

Especifica la categoría del dato personal siguiendo nuestra taxonomía de categorías de datos.

Las siguientes llaves (key) infieren la categoría del dato personal:

• name: Primer nombre (Name > First)
• last_name: Apellido (Name > Last)
• date_of_birth: Fecha de nacimiento (Demographic > Birth date)
• cl_carnet_rut: RUT (Government Id > National Identification Number)
• cl_carnet_doc_number: Número de documento (Government Id)
• cl_carnet_expiration_date: Fecha de expiración del documento (Government Id)
• cl_carnet_issue_date: Fecha de emisión del documento (Government Id)
• gender: Género (Demographic > Gender)
• nationality: Nacionalidad (Demographic)
• email: Correo electrónico (Contact > Email)
• phone_number: Teléfono (Contact > Phone number)

Esto significa que si usas alguna de estas llaves, no necesitas especificar la categoría del dato.

Si especificas una de estas llaves y además defines la categoría del dato, la categoría que definas tendrá prioridad sobre la predefinida.

Aplica las mismas buenas prácticas que seguimos en las plantillas de consentimiento:

• Usa subcategorías de la taxonomía cuando existan
• Solicita solo los datos necesarios para cumplir tu finalidad
• Alinea las finalidades (data_uses) con la cláusula legal que verá el usuario

¿Te ayudamos?

Si tu empresa no tiene una definición específica en sus políticas, contáctanos para ayudarte a determinarlas adecuadamente. Profundiza en estos conceptos revisando nuestra documentación sobre la taxonomía.

Ejemplo de requerimiento

{
  "key": "cl_carnet_rut",
  "data_category": "user.government_id.national_identification_number",
  "data_uses": ["essential.fraud_detection", "essential.service"]
}

Ejemplo completo de plantilla

Aquí tienes un ejemplo completo de cómo se vería la solicitud para crear una plantilla de disclosure:

POST /api/v1/disclosure_templates

{
  "name": "Verificación de identidad para clientes",
  "duration": "P6M",
  "data_subject": "customer",
  "privacy_document_ids": ["doc_privacy_123", "doc_terms_456"],
  "data_requirements": [
    {
      "key": "name",
      "data_category": "user.name.first",
      "data_uses": ["essential.fraud_detection", "essential.service"]
    },
    {
      "key": "last_name",
      "data_category": "user.name.last",
      "data_uses": ["essential.fraud_detection", "essential.service"]
    },
    {
      "key": "cl_carnet_rut",
      "data_category": "user.government_id.national_identification_number",
      "data_uses": ["essential.fraud_detection", "essential.service"]
    },
    {
      "key": "date_of_birth",
      "data_category": "user.demographic.birth_date",
      "data_uses": ["essential.fraud_detection", "essential.service"]
    }
  ]
}

Si necesitas el detalle completo de parámetros y respuestas, consulta Crear un template de divulgación.

Configuración avanzada

Configura niveles de validación

Puedes configurar qué verificaciones de identidad se requieren para cada plantilla de disclosure usando los campos de validación:

• liveness_check: Requiere prueba de vida (detección de persona real)
• id_scan_check: Requiere escaneo del documento de identidad
• government_check: Requiere verificación con bases de datos gubernamentales

Estos campos sobrescriben la configuración por defecto de tu empresa, permitiéndote tener diferentes niveles de validación para diferentes tipos de disclosure.

Ejemplo con validación biométrica completa

{
  "name": "Validación alta seguridad",
  "liveness_check": true,
  "id_scan_check": true,
  "government_check": false,
  "data_requirements": [...]
}

Ejemplo con validación básica de documento

{
  "name": "Validación básica",
  "liveness_check": false,
  "id_scan_check": true,
  "government_check": false,
  "data_requirements": [...]
}

Prioridad de configuración

Si defines estos campos en la plantilla, tienen prioridad sobre la configuración general de tu empresa. Si no los defines, se usarán los valores configurados a nivel de empresa en disclosure.liveness_check, disclosure.id_scan_check y disclosure.government_check.

Aprende más sobre los niveles de validación y sus casos de uso en la guía de niveles de validación.

Ajusta la tolerancia de estimación de edad

Durante la validación, Soyio compara tres grupos de edad: el calculado desde la fecha de nacimiento del documento, el estimado por FaceTec desde la foto del documento y el estimado desde la cara viva. Los grupos disponibles son over_18, over_21, over_25 y over_30.

Usa max_age_group_distance al crear o actualizar una plantilla para definir la distancia máxima permitida entre el grupo menor y el mayor:

Valor	Comportamiento
0	Exige que los tres resultados pertenezcan al mismo grupo
1	Permite grupos adyacentes. Es el valor por defecto y tolera variaciones normales de estimación
2	Permite hasta dos grupos de diferencia
3	Desactiva esta comparación: acepta cualquier combinación entre los cuatro grupos adultos

Ejemplo con coincidencia exacta

{
  "max_age_group_distance": 0
}

Calibra antes de endurecer

El valor 0 puede aumentar falsos positivos porque las estimaciones de la foto del documento y de la cara viva pueden caer en grupos adyacentes para una misma persona. Prueba el ajuste con datos representativos antes de usarlo.

Una diferencia mayor al valor configurado se registra como la señal age_incompatible. La primera señal exige una nueva captura. Si otro intento del mismo disclosure vuelve a ser incompatible, la validación falla. El valor se copia al crear cada validation_attempt; actualizar la plantilla no cambia intentos ya creados.

La comparación queda inconclusa si alguno de los tres grupos no está disponible. max_age_group_distance no reemplaza reglas de edad mínima o máxima definidas para tu proceso.

Aplica controles automáticos de riesgo

Soyio aplica estos controles dentro de tu compañía y entre todas tus plantillas:

• Una primera captura con medios inesperados exige un reintento. Una segunda señal en el mismo disclosure rechaza la validación
• El sexto disclosure creado en una hora para la misma referencia rechaza la validación
• El cuarto disclosure que reutiliza el mismo documento en 24 horas rechaza la validación
• Un documento asociado durante las últimas 24 horas a otra referencia rechaza la validación

Un reintento técnico aislado, un disclosure otorgado previamente o un cambio de plantilla quedan como evidencia, pero ninguno rechaza por sí solo. Los límites de reintento se mantienen aunque el disclosure cree un nuevo validation_attempt.

Ajusta qué tan estrictos son los controles

Usa validation_risk_level para elegir con qué rigor se aplican estos controles:

Nivel	Comportamiento
monitor	Evalúa y registra todas las señales sin rechazar ninguna validación
permissive	Tolera siete disclosures por referencia en una hora y cinco usos del documento en 24 horas; el uso entre referencias distintas solo se registra
standard	Comportamiento por defecto: un reintento por señal, cinco disclosures por referencia y tres usos del documento
strict	Rechaza a la primera señal, sin reintento, y reduce ambos umbrales de velocidad a dos disclosures
custom	Aplica los valores de la política personalizada de tu compañía

El nivel se define en la configuración de validación de tu compañía y se puede sobrescribir por plantilla. Con null en la plantilla se hereda el nivel de la compañía; con null en la compañía se usa standard.

Define una política personalizada

Cuando los cuatro niveles no calzan con tu operación, define una política personalizada con custom_risk_policy en la configuración de validación de la compañía. Se define una sola vez y luego cualquier plantilla —o la configuración global— puede seleccionarla con el nivel custom.

Campo	Rango	Valor si es null
retry_budget	0 a 2	1
user_reference_velocity_request_threshold	1 a 9	velocity_request_threshold si está definido; de lo contrario, 5
velocity_request_threshold	1 a 9	3, para el mismo documento
user_reference_velocity_window_hours	1 a 168	1
velocity_window_hours	1 a 168	24
document_reference_mismatch_action	reject, flag, allow	reject

Ejemplo: dos reintentos y velocidad por referencia más laxa

{
  "validation_risk_level": "custom",
  "custom_risk_policy": {
    "retry_budget": 2,
    "user_reference_velocity_request_threshold": 7
  }
}

Consideraciones al calibrar:

• custom siempre bloquea. Si buscas dejar de rechazar validaciones, usa monitor, no una política personalizada.
• retry_budget llega hasta 2 a propósito: cada reintento adicional es un intento extra para quien busque vulnerar el control.
• Ambos umbrales de velocidad llegan hasta 9 porque cada control solo revisa las 10 solicitudes más recientes; un umbral mayor nunca se alcanzaría.
• user_reference_velocity_request_threshold controla la misma referencia. velocity_request_threshold conserva el control del mismo documento.
• user_reference_velocity_window_hours controla solicitudes con la misma referencia. velocity_window_hours controla reutilización del documento y mismatch de referencia.
• Ampliar cualquiera de las ventanas no aumenta el límite de 10 solicitudes revisadas: solo extiende el periodo considerado.

Ejemplo: una plantilla más estricta que el resto

{
  "validation_risk_level": "strict"
}

monitor desactiva el bloqueo

En monitor las señales siguen registrándose en la evidencia de cada validation_attempt, pero ninguna validación se rechaza automáticamente. Úsalo para medir el impacto antes de endurecer los controles, no como configuración permanente.

El nivel aplicado se copia al crear cada validation_attempt; cambiarlo no afecta intentos ya creados.

Conecta tus documentos de privacidad

Asocia políticas y avisos usando privacy_document_ids. Los documentos deben estar configurados previamente en tu perfil de compañía. Incluye todas las versiones relevantes para que la evidencia del disclosure quede vinculada al marco legal correcto.

Crea y usa tu plantilla

Crear la plantilla

Usa el endpoint POST /api/v1/disclosure_templates para crear tu plantilla con la configuración que definiste.

Usar la plantilla

Cuando la plantilla esté lista, referencia su id para iniciar un proceso de verificación de identidad con POST /api/v1/disclosure_requests. Si defines matchers, asegúrate de que coincidan con las llaves configuradas en los data_requirements para evitar errores de validación.

Gestiona la plantilla

Recuerda actualizar la plantilla con PATCH /api/v1/disclosure_templates/{id} cuando cambien los datos solicitados o las finalidades.

Solo puedes eliminar una plantilla si no tiene disclosures asociados. Revisa Eliminar un template de divulgación para más información.