Enlace de verificación del propietario

Descripción general

La mutación requestOwnerDocumentVerificationLink genera una URL compartible que un propietario de negocio puede usar para completar la verificación de identidad por documento. El enlace funciona por sí solo: el propietario no necesita credenciales de Fluz. Úsalo para propietarios cuyos getBusiness reportan verificationType: DOCUMENTS y status: PENDING_CIP. Esos son beneficiarios finales o personas de control enviadas con isUsPerson: false, lo cual los coloca en la ruta de documentos en lugar de la ruta de SSN.

Los propietarios en la ruta de SSN (verificationType: SSN) no necesitan usar esta mutación, y tampoco los propietarios invitados que aún no han aceptado — Fluz les envía un correo directo y ellos se verifican por su cuenta.

Alcances requeridos

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token, account type `BUSINESS`
Required Scopes	`REGISTER_BUSINESS`

Usa un token emitido para la cuenta de negocio que devolvió registerBusiness.

Requisitos previos

Todos estos deben cumplirse, o la llamada fallará:

Un token de cuenta de negocio con REGISTER_BUSINESS

Con alcance al negocio que es dueño del roster.

El caso está en estado enviado para revisión (submitted-for-screening)

El enlace solo puede generarse durante un estado específico después del envío. Los casos que aún se están creando, que ya están esperando resultados de screening, o que están en revisión manual serán rechazados — aunque getBusiness reporta todos esos como kybStatus: PENDING. Ver Tiempo.

businessOwnerId es el ID de usuario de negocio del propietario

Tomado de owners[].id en getBusiness, y perteneciente a este negocio. No se acepta un ID de usuario de Fluz, y los propietarios invitados que aún no han aceptado tienen id: null.

El propietario está en la ruta de documentos

verificationType: DOCUMENTS con status: PENDING_CIP.

Estructura básica de la mutación

mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) {
  requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) {
    success
    id
    verificationLink
  }
}

Parámetros

Parameter	Type	Required	Description
`businessOwnerId`	`UUID`	Yes	El ID de usuario de negocio del propietario, tal como se devuelve en `owners[].id` desde getBusiness. No es un ID de usuario de Fluz

Detalles de la respuesta

Field	Type	Description
`success`	`Boolean`	`true` cuando se generó un enlace
`id`	`UUID`	El `businessOwnerId` para el que se generó el enlace
`verificationLink`	`String`	URL de Plaid IDV compartible. Envíala directamente al propietario

Los fallos se devuelven como errores de GraphQL de nivel superior, no como success: false. Verifica el arreglo errors, no solo el payload de datos. Esto es lo opuesto a registerBusiness, que reporta fallos de validación dentro de su payload.

Tiempo

El requisito de estado en el prerrequisito 2 es la razón más común por la que esta llamada falla, y no es visible a través de kybStatus.

Llámalo temprano. Poco después de que registerBusiness devuelva respuesta, tan pronto como getBusiness muestre al propietario con verificationType: DOCUMENTS y status: PENDING_CIP.Si recibes ARG-0001 con business is not submitted for approval, el caso ya pasó — o aún no ha llegado — a esa ventana. No reintentes en un bucle. Sigue leyendo getBusiness, y contacta a tu account manager con el accountId si un propietario permanece en PENDING_CIP sin forma de enviarle un enlace.

Ejemplo cURL

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "mutation RequestOwnerDocumentVerificationLink($businessOwnerId: UUID!) { requestOwnerDocumentVerificationLink(businessOwnerId: $businessOwnerId) { success id verificationLink } }",
    "variables": { "businessOwnerId": "d4e5f6a7-b8c9-0123-def0-234567890123" }
  }'

Respuesta de ejemplo

Éxito

{
  "data": {
    "requestOwnerDocumentVerificationLink": {
      "success": true,
      "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
      "verificationLink": "https://verify.docs../..."
    }
  }
}

Error

{
  "errors": [
    {
      "message": "Invalid arguments received - business owner not found.",
      "extensions": {
        "code": "ARG-0001",
        "statusCode": 422
      }
    }
  ],
  "data": null
}

Códigos de error

Code	Name	Description	How to resolve
`AUTH-0002`	InvalidCredentials	Se usó autenticación básica; el tipo de cuenta del token no es `BUSINESS`; al token le falta `userId` o `accountId`; o no existe un negocio para ese `accountId`	Usa un token emitido para el `accountId` del negocio
`AUTH-0031`	InvalidScope	Al token le falta el scope `REGISTER_BUSINESS`	Agrega el scope y vuelve a emitir el token
`ARG-0002`	MissingArguments	No se proporcionó `businessOwnerId`	Pasa el ID de usuario de negocio del propietario
`ARG-0001`	InvalidArguments	`businessOwnerId` no coincide con un propietario de negocio en este negocio, o el caso no está en el estado de enviado para aprobación	Vuelve a leer getBusiness para obtener un ID actual, y ver Tiempo
`G-0001`	InternalError	El proveedor de verificación no devolvió un enlace, o la solicitud a este falló	Reintenta una vez. Si persiste, contacta soporte con el `accountId`

Notas

El enlace generado es de un solo propósito. Si el enlace del propietario expira o se pierde, llama a la mutación nuevamente para obtener uno nuevo en lugar de reutilizar el anterior.
Generar un enlace no cambia el status del propietario. Pasa a READY solo cuando el propietario realmente complete la verificación — sigue leyendo getBusiness.
No existe una variante masiva. Llama una vez por cada propietario que necesite un enlace.

Páginas relacionadas

Estado de KYB del negocio

Identifica qué propietarios necesitan un enlace y confirma cuando terminen.

Descripción general de KYB

Dónde se ubica este paso en el flujo de extremo a extremo.

Registrar un negocio

Cómo isUsPerson coloca a un propietario en la ruta de documentos.

​Descripción general

​Alcances requeridos

​Requisitos previos

​Estructura básica de la mutación

​Parámetros

​Detalles de la respuesta

​Tiempo

​Ejemplo cURL

​Respuesta de ejemplo

​Éxito

​Error

​Códigos de error

​Notas

​Páginas relacionadas

Estado de KYB del negocio

Descripción general de KYB

Registrar un negocio

Descripción general

Alcances requeridos

Requisitos previos

Estructura básica de la mutación

Parámetros

Detalles de la respuesta

Tiempo

Ejemplo cURL

Respuesta de ejemplo

Éxito

Error

Códigos de error

Notas

Páginas relacionadas