Estado KYB de negocio

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:

¿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.

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

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

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": "query GetBusiness { getBusiness { accountId kybStatus owners { id name verificationType status } } }"
  }'

Respuesta de ejemplo

{
  "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. 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

Resumen de KYB

El ciclo de vida del estado y cómo rastrear un caso hasta la decisión.

Enlace de verificación del dueño

Genera un enlace para dueños reportados como DOCUMENTS y PENDING_CIP.

Registrar un negocio

La mutación que crea la cuenta que lee esta query.

​Descripción general

​Alcances requeridos

​Estructura básica de la query

​Detalles de la respuesta

​BusinessOwnerStatus

​ExternalKybStatus (enum)

​BusinessOwnerVerificationType (enum)

​ExternalBusinessOwnerStatus (enum)

​Ejemplo cURL

​Respuesta de ejemplo

​Códigos de error

​Mejores prácticas

​Páginas relacionadas

Resumen de KYB

Enlace de verificación del dueño

Registrar un negocio

Descripción general

Alcances requeridos

Estructura básica de la query

Detalles de la respuesta

BusinessOwnerStatus

ExternalKybStatus (enum)

BusinessOwnerVerificationType (enum)

ExternalBusinessOwnerStatus (enum)

Ejemplo cURL

Respuesta de ejemplo

Códigos de error

Mejores prácticas

Páginas relacionadas