> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Enlace de verificación del propietario

> Genera un enlace compartible de verificación de identidad para un propietario de negocio que debe verificar por documento.

## 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](/business-status) 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.

<Note>
  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.
</Note>

## 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á:

<Steps>
  <Step title="Un token de cuenta de negocio con REGISTER_BUSINESS">
    Con alcance al negocio que es dueño del roster.
  </Step>

  <Step title="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](/business-status) reporta todos esos como `kybStatus: PENDING`. Ver [Tiempo](#timing).
  </Step>

  <Step title="businessOwnerId es el ID de usuario de negocio del propietario">
    Tomado de `owners[].id` en [getBusiness](/business-status), 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`.
  </Step>

  <Step title="El propietario está en la ruta de documentos">
    `verificationType: DOCUMENTS` con `status: PENDING_CIP`.
  </Step>
</Steps>

## Estructura básica de la mutación

```graphql theme={null}
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](/business-status). 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 |

<Note>
  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](/business-registration), que reporta fallos de validación dentro de su payload.
</Note>

## 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`.

<Warning>
  **Llámalo temprano.** Poco después de que `registerBusiness` devuelva respuesta, tan pronto como [getBusiness](/business-status) 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.
</Warning>

## Ejemplo cURL

```bash theme={null}
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

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

### Error

```json theme={null}
{
  "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](/business-status) para obtener un ID actual, y ver [Tiempo](#timing) |
| `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](/business-status).
* No existe una variante masiva. Llama una vez por cada propietario que necesite un enlace.

## Páginas relacionadas

<CardGroup cols={2}>
  <Card title="Estado de KYB del negocio" href="/business-status">
    Identifica qué propietarios necesitan un enlace y confirma cuando terminen.
  </Card>

  <Card title="Descripción general de KYB" href="/kyb-overview">
    Dónde se ubica este paso en el flujo de extremo a extremo.
  </Card>

  <Card title="Registrar un negocio" href="/business-registration">
    Cómo `isUsPerson` coloca a un propietario en la ruta de documentos.
  </Card>
</CardGroup>