Verificar por Documentos

Solicitar un URL de IDV es el método de API de mayor garantía y el recurso cuando pasarnos 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 revisa 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 se está verificando, 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 dice a Fluz a qué cliente pertenece la verificación.

Fluz devuelve un enlace de verificación

La respuesta contiene verificationUrl y verificationId. Guarda el verificationId: es cómo concilias 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 frente y dorso de una identificación gubernamental (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 revisa 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 o lo expongas en cualquier lugar donde el cliente previsto no sea el único lector: concede acceso a una sesión de envío de identidad.

Solicitud

Campo	Tipo	Obligatorio	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 completar previamente 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	Nombre legal del cliente.
`lastName`	String	No	Apellido legal del cliente.
`streetLine1`	String	No	Dirección residencial.
`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	Correo electrónico del cliente.
`phoneNumber`	String	No	Número de teléfono del cliente en formato E.164.

Debes capturar y registrar el consentimiento del cliente antes de establecer gaveConsent: true. Todo lo que envíes se usa para completar previamente 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 el nombre de campos frente 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, por webhook.

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 completa previamente la información conocida para que el cliente la revise y luego le pide:

Capturar el frente y el dorso de una identificación con foto emitida por el gobierno compatible.
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 examinan antes de devolver una decisión.

Recibir el resultado

Dado que el cliente puede completar la verificación mucho después de que emitas el enlace, el resultado llega a tu endpoint de webhook. Asocia 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 están limitadas por cliente. Una vez alcanzado el límite, solicitudes posteriores devuelven ERROR con Exceeded document verification limit.

Pruebas

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

​Cómo funciona

​Solicitud

​Ejemplo

​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