Verificar por Documentos

Solicitar una URL de IDV es el método de API de mayor seguridad, y el recurso alterno cuando enviarnos la información del SSN no produce una aprobación. En lugar de recopilar tú mismo los documentos de identidad, solicitas a Fluz un enlace de verificación alojado y se lo entregas a tu cliente. Fluz recopila y examina los documentos directamente.

Requisitos previos

El alcance VERIFY_KYC habilitado en tu aplicación por Fluz. Consulta Alcance requerido.
Un token de acceso de usuario generado para el cliente que está siendo verificado, incluyendo VERIFY_KYC en sus alcances.
Un endpoint de webhook registrado. Esto es obligatorio para la verificación por documentos: el resultado no está disponible en la respuesta de la API. Consulta Verificar clientes.

Cómo funciona

Identificas al cliente y solicitas un enlace

Llama a requestDocumentVerificationLink usando un token de acceso de usuario generado para ese cliente. El token es lo que le indica a Fluz a qué cliente pertenece la verificación.

Fluz devuelve un enlace de verificación

La respuesta contiene un verificationUrl y un verificationId. Guarda el verificationId; es cómo conciliarás el webhook eventual con esta solicitud.

Entregas el enlace a tu cliente

Envíalo como mejor se adapte a tu producto: correo electrónico, SMS, notificación push o una redirección dentro de la app. El cliente puede completar la verificación en cualquier momento.

Tu cliente sube sus documentos

En la página alojada, el cliente captura el anverso y reverso de una identificación con foto emitida por el gobierno (licencia de conducir, pasaporte, identificación estatal o identificación militar) y toma una selfie para una coincidencia biométrica.

Fluz te notifica el resultado

Cuando el cliente termina, Fluz evalúa el envío y envía un resultado APPROVED o DECLINED a tu endpoint de webhook.

El enlace de verificación es único para un cliente y un intento de verificación. Nunca reutilices un enlace entre clientes, lo registres en un sistema compartido ni lo expongas en ningún lugar donde el cliente previsto no sea el único lector: otorga acceso a una sesión de envío de identidad.

Solicitud

Campo	Tipo	Requerido	Descripción
`gaveConsent`	Boolean	Sí	Si el cliente consintió la verificación de identidad. Debe ser `true`, o la solicitud será rechazada.
`prefillData`	Boolean	Sí	Si se debe precargar el formulario de verificación con la información de identidad que Fluz ya posee. Cuando es `true`, no necesitas enviar los campos de abajo.
`firstName`	String	No	El primer nombre legal del cliente.
`lastName`	String	No	El apellido legal del cliente.
`streetLine1`	String	No	Dirección residencial (calle).
`streetLine2`	String	No	Apartamento, suite o unidad.
`city`	String	No	Ciudad.
`region`	String	No	Estado o región.
`postalCode`	String	No	Código ZIP o postal.
`country`	String	No	País, en formato ISO 3166-1 alpha-2.
`dateOfBirth`	String	No	Fecha de nacimiento, con formato `YYYY-MM-DD`.
`emailAddress`	String	No	El correo electrónico del cliente.
`phoneNumber`	String	No	El número de teléfono del cliente en formato E.164.

Debes capturar y registrar el consentimiento del cliente antes de establecer gaveConsent: true. Cualquier dato que envíes se usa para precargar el formulario: el cliente puede revisarlo y corregirlo antes de enviar, así que trata estos campos como una conveniencia, no como los valores que serán verificados.

Observa la diferencia en los nombres de campos con respecto a la verificación por SSN: esta mutación usa region donde la otra usa state, y espera dateOfBirth como YYYY-MM-DD en lugar de MM/DD/YYYY.

Ejemplo

import { GraphQLClient, gql } from 'graphql-request';

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const REQUEST_DOC_VERIFICATION = gql`
  mutation RequestDocumentVerificationLink($input: RequestDocumentVerificationLinkInput!) {
    requestDocumentVerificationLink(input: $input) {
      userId
      verificationType
      verificationId
      verificationUrl
      status
      message
    }
  }
`;

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

const response = await client.request(REQUEST_DOC_VERIFICATION, {
  input: {
    gaveConsent: true,
    prefillData: true,
  },
});

console.log(response);

Response

{
  "data": {
    "requestDocumentVerificationLink": {
      "userId": "eb910e93-5e39-4f53-99b9-0b033dd8e54b",
      "verificationType": "DOCUMENT_VERIFICATION",
      "verificationId": "idv_9MpDJC8aotDaxw",
      "verificationUrl": "https://verify.fluz.app/idv/idv_9MpDJC8aotDaxw?key=27f09ec042881c2c56945680c53108a4",
      "status": "OK",
      "message": "Verification link request successful"
    }
  }
}

El status en esta respuesta (OK) solo confirma que se emitió el enlace; no es la decisión de verificación. La decisión llega después, vía webhook.

Abrir la receta

Una versión lista para copiar y ejecutar de este ejemplo, lista para adaptar a tu integración.

Campos de la respuesta

Campo	Tipo	Descripción
`userId`	UUID	El cliente de Fluz al que pertenece la verificación.
`verificationType`	String	Siempre `DOCUMENT_VERIFICATION`.
`verificationId`	String	Identificador para este intento de verificación. Guárdalo para conciliar el webhook.
`verificationUrl`	String	El enlace alojado para entregar a tu cliente.
`status`	String	`OK` cuando el enlace se emitió correctamente.
`message`	String	Detalle legible para humanos.

Lo que ve el cliente

El flujo alojado precarga la información conocida para que el cliente la revise, luego le pide:

Capturar el anverso y reverso de una identificación con foto válida emitida por el gobierno.
Tomar una selfie, que se compara biométricamente con la foto de la identificación.

La autenticidad del documento, la manipulación y la coincidencia biométrica se analizan antes de devolver una decisión.

Recibir el resultado

Debido a que el cliente puede completar la verificación mucho después de que emitas el enlace, el resultado llega a tu endpoint de webhook. Hace coincidir el evento entrante con tu verificationId almacenado y luego actúa según el resultado:

APPROVED: el cliente está verificado. Desbloquea la funcionalidad correspondiente.
DECLINED: el cliente no está verificado. La verificación por documentos es el paso final en la ruta de escalamiento; un rechazo aquí generalmente requiere revisión manual en lugar de otro intento automatizado.

Las solicitudes de verificación por documentos tienen un límite por cliente. Una vez alcanzado el límite, las solicitudes posteriores devuelven ERROR con Exceeded document verification limit.

Pruebas

En staging puedes completar el flujo completo de documentos usando licencias de conducir de ejemplo e identidades de prueba. La autenticidad del documento y otras funciones de seguridad no se aplican en staging, y puedes reutilizar la imagen frontal para la captura del reverso. Consulta Probar flujos KYC.

​Cómo funciona

​Solicitud

​Ejemplo

Abrir la receta

​Campos de la respuesta

​Lo que ve el cliente

​Recibir el resultado

​Pruebas

Cómo funciona

Solicitud

Ejemplo

Campos de la respuesta

Lo que ve el cliente

Recibir el resultado

Pruebas