> ## 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.
# Estado KYB de negocio
> Lee el estado KYB de la cuenta de negocio y el progreso de verificación de identidad de cada dueño con la query getBusiness.
## Descripción general
La query **getBusiness** devuelve el estado KYB actual de una cuenta de negocio, junto con una instantánea de la lista de propietarios y en qué etapa está cada dueño en la verificación de identidad.
Así es como respondes dos preguntas distintas después de [registrar un negocio](/business-registration):
* **¿Ya fue aprobado el negocio?** Lee `kybStatus`.
* **¿Qué lo está demorando?** Lee `owners` — un dueño aún en `PENDING_CIP` o `PENDING_INVITE` suele ser la respuesta.
También puedes recibir cambios de estado suscribiéndote al webhook `KYB_STATUS_UPDATE`, lo que evita lecturas programadas. El webhook solo lleva el estado del negocio, así que llama esta query cuando necesites la lista de dueños. Ver [Seguimiento de una solicitud](/kyb-overview#tracking-an-application).
## Alcances requeridos
| Propiedad | Valor |
| ----------------- | --------------------------------------------- |
| Endpoint | GraphQL API |
| Autenticación | OAuth Bearer Token, tipo de cuenta `BUSINESS` |
| Scopes requeridos | `REGISTER_BUSINESS` |
La query no recibe argumentos — siempre resuelve el negocio vinculado al `accountId` del token que llama. Usa un token emitido para la cuenta de negocio que devolvió `registerBusiness`; el token de consumidor con el que te registraste no funcionará.
Cuando Fluz crea el otorgamiento OAuth del negocio durante el registro, `REGISTER_BUSINESS` se incluye forzosamente en los scopes de ese otorgamiento, por lo que un token emitido para la nueva cuenta de negocio siempre puede llamar esta query.
## Estructura básica de la query
```graphql theme={null}
query GetBusiness {
getBusiness {
accountId
kybStatus
owners {
id
name
verificationType
status
}
}
}
```
## Detalles de la respuesta
| Campo | Tipo | Descripción |
| ----------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| `accountId` | `UUID` | La cuenta de negocio que describe esta respuesta |
| `kybStatus` | `ExternalKybStatus` | `PENDING`, `APPROVED` o `DECLINED` |
| `owners` | `[BusinessOwnerStatus]` | Instantánea actual del roster, incluyendo dueños agregados o actualizados después del registro |
### BusinessOwnerStatus
| Campo | Tipo | Descripción |
| ------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `UUID` | El ID de identidad del dueño, o `null` para dueños invitados que aún no han aceptado. Ver [Qué IDs se pueden usar](#which-ids-can-be-used) |
| `name` | `String` | Nombre para mostrar derivado del registro de identidad vinculado |
| `verificationType` | `BusinessOwnerVerificationType` | Qué verificación de identidad se *espera* para este dueño |
| `status` | `ExternalBusinessOwnerStatus` | El progreso de verificación actual del dueño |
### ExternalKybStatus (enum)
| Valor | Qué significa | Qué debe hacer tu app |
| ---------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `PENDING` | El caso está en revisión, en espera de resultados de screening o a la espera de que un dueño se verifique | Seguir rastreando. No fondear la cuenta ni emitir tarjetas |
| `APPROVED` | KYB aprobado | Aprovisiona cuentas de gasto y emite tarjetas |
| `DECLINED` | KYB no aprobado | Muestra un mensaje neutral y dirige al usuario a soporte. No reintentes automáticamente |
`registerBusiness` devuelve `SUBMITTED`, que no es un valor de este enum — ese mismo momento aquí se lee como `PENDING`.
`PENDING` agrupa varios estados internos en un solo valor. Eso importa en un caso: [requestOwnerDocumentVerificationLink](/owner-verification-link) solo funciona mientras el caso está en un estado interno específico, y `kybStatus` no puede decirte en cuál estás.
### BusinessOwnerVerificationType (enum)
| Valor | Cuándo lo ves |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `SSN` | El dueño se verifica vía SSN (CIP) — fue enviado con `isUsPerson: true` |
| `DOCUMENTS` | El dueño se verifica cargando documentos de identidad — fue enviado con `isUsPerson: false` |
| `NOT_REQUIRED` | No se espera verificación adicional: un dueño provisto que posee menos del 25% y no es la persona de control |
### ExternalBusinessOwnerStatus (enum)
| Valor | Qué significa | Qué debe hacer tu app |
| ---------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `PENDING_INVITE` | El dueño tiene una invitación pendiente y aún no la ha aceptado | Nada. Fluz les envía un email; no hay API para reenviar o aceptar |
| `PENDING_CIP` | El dueño aún necesita la verificación de identidad esperada | Para dueños `DOCUMENTS`, [envíales un enlace de verificación](/owner-verification-link) |
| `READY` | El requisito de verificación del dueño está satisfecho | Nada |
| `FAILED` | Presente en el esquema para compatibilidad futura; actualmente no se devuelve | — |
## 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 " \
-d '{
"query": "query GetBusiness { getBusiness { accountId kybStatus owners { id name verificationType status } } }"
}'
```
## Respuesta de ejemplo
```json theme={null}
{
"data": {
"getBusiness": {
"accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"kybStatus": "PENDING",
"owners": [
{
"id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
"name": "John Doe",
"verificationType": "SSN",
"status": "READY"
},
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123",
"name": "Jane Smith",
"verificationType": "DOCUMENTS",
"status": "PENDING_CIP"
},
{
"id": null,
"name": "Carol Investor",
"verificationType": "SSN",
"status": "PENDING_INVITE"
}
]
}
}
}
```
Jane necesita un [enlace de verificación](/owner-verification-link). Carol fue invitada y Fluz le enviará un email. El negocio no puede ser aprobado hasta que ambas lleguen a `READY`.
## Códigos de error
Esta query devuelve todos los fallos en el arreglo superior `errors` — no hay un payload `success: false`.
| Código | Nombre | Descripción | Cómo resolver |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `AUTH-0002` | InvalidCredentials | Se usó basic auth; 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` de negocio que devolvió `registerBusiness` |
| `AUTH-0031` | InvalidScope | Al token le falta el scope `REGISTER_BUSINESS` | Agrega el scope y vuelve a emitir el token |
| `G-0001` | InternalError | Error interno | Reintenta una vez. Si persiste, contacta soporte con el `accountId` |
## Mejores prácticas
* **Prefiere el webhook y lee para conciliación.** Suscríbete a `KYB_STATUS_UPDATE` para menor latencia, y lee esta query cuando el usuario regrese a tu pantalla de onboarding o en una programación en segundo plano de baja frecuencia — por hora, no por carga de página.
* **Espera ambas señales antes de salir a producción.** `kybStatus: APPROVED` y cada dueño en `READY`.
* **No trates una solicitud de enlace como progreso.** El `status` de un dueño cambia cuando realmente completa la verificación, no cuando generas su enlace.
## Páginas relacionadas
El ciclo de vida del estado y cómo rastrear un caso hasta la decisión.
Genera un enlace para dueños reportados como `DOCUMENTS` y `PENDING_CIP`.
La mutación que crea la cuenta que lee esta query.