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

# Incorporar y Conectar a un Cliente

> Ejecuta el flujo feliz de la plataforma de extremo a extremo: registra a un cliente, conecta su cuenta con OAuth, verifica su identidad y opera en su nombre.

Este Quickstart es la historia de "Crear una plataforma" hecha ejecutable. Registrarás a un cliente de forma programática, realizarás el otorgamiento de OAuth para obtener un token con alcance a su cuenta, verificarás su identidad con el flujo de KYC en sandbox y demostrarás la conexión emitiendo una tarjeta virtual en su nombre, con la misma API que usas en tu propia cuenta.

<Info>
  **Requisitos previos**

  * Una **cuenta de Fluz con una aplicación de staging**: Pasos 1–2 de cualquier quickstart, o consulta [Prepara tus cuentas](/get-started/prepare-accounts) y [Credenciales de API](/get-started/api-credentials).
  * Una **app configurada con OAuth**: un `client_id`, `client_secret` y un `redirect_uri` registrado — consulta [Crear una App OAuth](/create-an-o-auth-app) y [Configurar App OAuth](/configure-o-auth-app).
  * Las solicitudes van al **sandbox** — sin dinero real ni PII real. Consulta [Entorno de Staging vs. Live](/concepts/environments).
</Info>

<Warning>
  **Registrar usuarios requiere permiso especial.** La mutación `registerUser` está restringida por aplicación (`AUTH-0022` si no está habilitada); contacta a tu account manager para habilitarla. ¿Aún sin acceso de registro? Omite el Paso 1 y ejecuta el flujo con cualquier usuario de staging existente.
</Warning>

## El flujo completo

<Steps>
  <Step title="Registrar al cliente" icon="user-plus">
    Aprovisiona un usuario completo — cuenta, saldos y capacidad de referidos — con `registerUser`, autenticado con el token de **tu aplicación**.

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation RegisterUser(
            $firstName: String!
            $lastName: String!
            $phoneNumber: String!
            $regionCode: String!
            $emailAddress: String!
            $dateOfBirth: String!
          ) {
            registerUser(
              firstName: $firstName
              lastName: $lastName
              phoneNumber: $phoneNumber
              regionCode: $regionCode
              emailAddress: $emailAddress
              dateOfBirth: $dateOfBirth
            ) {
              success
              error { code message }
            }
          }
      ```

      ```json Variables theme={null}
          {
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "5551234567",
            "regionCode": "US",
            "emailAddress": "jane.doe@example.com",
            "dateOfBirth": "1990-05-15"
          }
      ```
    </CodeGroup>

    <Warning>
      Esta mutación devuelve errores **en los datos de la respuesta**, no como errores de GraphQL — siempre verifica `success` y maneja el objeto `error`. Fallas comunes: `AUTH-0026` / `AUTH-0027` (teléfono o email ya en uso), `AUTH-0004` (teléfono inválido). Lista completa: [Registro de usuarios](/user-registration).
    </Warning>
  </Step>

  <Step title="Enviar al cliente por el otorgamiento de OAuth" icon="plug">
    El cliente autoriza tu app visitando la página alojada del otorgamiento. Crea la URL con tu configuración de OAuth y los alcances que tu integración necesita:

    ```text Authorization URL theme={null}
        https://uni.staging.fluzapp.com/authorize
          ?response_type=code
          &client_id=<YOUR_OAUTH_CLIENT_ID>
          &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
          &scopes=CREATE_VIRTUALCARD%20REVEAL_VIRTUALCARD
          &state=<OPTIONAL_OPAQUE_VALUE>
    ```

    * `scopes` está **delimitado por espacios** (codificados en URL como `%20`) y debe ser un subconjunto de los scopes habilitados en tu app — los scopes desconocidos se ignoran silenciosamente.
    * `state` se devuelve sin modificar — úsalo para correlacionar el redirect con tu sesión.

    El cliente ve la pantalla de permisos de Fluz, aprueba y es redirigido a tu `redirect_uri` con `?code=...&state=...`. Ese `code` es de un solo uso — captúralo del lado del servidor.

    Referencia completa de parámetros: [Flujo de Otorgamiento OAuth de Cara al Cliente](/client-facing-o-auth-grant-flow).
  </Step>

  <Step title="Intercambiar el código por el token del cliente" icon="key">
    Cambia el código de autorización por el `accessToken` con alcance al cliente (más un `refreshToken`). Esta llamada se autentica con **Basic auth**: base64 de `client_id:client_secret`.

    <CodeGroup>
      ```bash Exchange (cURL) theme={null}
          curl -X GET "https://uni.staging.fluzapp.com/token/exchange?code=<AUTH_CODE>&redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>" \
            -H "Authorization: Basic <base64 of CLIENT_ID:CLIENT_SECRET>"
      ```

      ```json Response (truncated) theme={null}
          {
            "accessToken": "eyJhbGciOi...",
            "accessTokenExpiresAt": "2026-07-13T21:05:30.673Z",
            "refreshToken": "8ec16c25951616150b0332a4a6d66547",
            "refreshTokenExpiresAt": "2026-08-13T20:55:30.738Z",
            "scope": ["CREATE_VIRTUALCARD", "REVEAL_VIRTUALCARD"],
            "user": { "id": "5070d5a1-d71a-4190-91b0-f116eec51771" }
          }
      ```
    </CodeGroup>

    El `redirect_uri` debe coincidir con el paso de otorgamiento **exactamente**. Almacena el `refreshToken` y rótalo antes de `accessTokenExpiresAt` — consulta [Actualizar un Access Token de OAuth](/refresh-o-auth-access-token).

    <Tip>
      ¿Incorporando muchos clientes? Anexa tu propio identificador como `external_id` en la URL de autorización para vincular cuentas de Fluz con registros en tu sistema — consulta [Administrar IDs de Referencia Externos](/managing-external-reference-ids).
    </Tip>
  </Step>

  <Step title="Verificar la identidad del cliente (KYC)" icon="id-card">
    El movimiento de dinero requiere una identidad verificada. Llama a `verifyUserInformation` **con el token del cliente** — el token determina quién es verificado. En staging, esta identidad de prueba siempre devuelve `APPROVED`:

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation VerifyUserInformation($input: VerifyUserInformationInput!) {
            verifyUserInformation(input: $input) {
              status
              message
            }
          }
      ```

      ```json Variables (approved test identity) theme={null}
          {
            "input": {
              "firstName": "John",
              "lastName": "Smith",
              "streetLine1": "222333 Peachtree Place",
              "streetLine2": "",
              "city": "Atlanta",
              "state": "GA",
              "postalCode": "30318",
              "country": "United States",
              "dateOfBirth": "02/28/1975",
              "ssnLast4": "3333"
            }
          }
      ```
    </CodeGroup>

    <Warning>
      **Límite de tres intentos:** un usuario puede ser enviado como máximo 3 veces antes de devolver `ERROR` — no quemes intentos en un usuario que necesitas. Resultados completos en sandbox: [Probar Flujos de KYC](/test-kyc-flows).
    </Warning>
  </Step>

  <Step title="Operar en su cuenta — demuéstralo" icon="credit-card">
    Este es el resultado: ejecuta cualquier operación de Fluz con el **token del cliente** y se ejecuta contra **su** cuenta. `createVirtualCard` es `createVirtualCard` — no hay una API de plataforma separada.

    ```graphql theme={null}
        mutation {
          createVirtualCard(
            input: {
              idempotencyKey: "1b7de2f8-c0a9-4532-9881-3ab5857bbe15"
              offerId: "ed669305-5e43-40a0-9a25-7a15ed174628"
              spendLimit: 50.00
              lockCardNextUse: true
              cardNickname: "First card on a connected account"
            }
          ) {
            virtualCardId
            virtualCardLast4
            status
          }
        }
    ```

    Una tarjeta `ACTIVE` de vuelta significa que el ciclo está cerrado: registrado → conectado → verificado → operando. El cliente se vuelve visible en tus sistemas a través del token; nunca obtuvo acceso a *tu* cuenta, y tú conservas solo los scopes que él concedió.
  </Step>
</Steps>

## Listo 🎉

Has incorporado y conectado a un cliente de extremo a extremo. A partir de aquí:

<CardGroup cols={2}>
  <Card title="Crear una plataforma" icon="layout-grid" href="/build-a-platform">
    La arquitectura completa de la plataforma: rutas de token, capacidades y patrones.
  </Card>

  <Card title="Aprobaciones y solicitudes" icon="check-check" href="/features/approvals-and-requests">
    Permite que los usuarios conectados soliciten acciones que los propietarios aprueban.
  </Card>

  <Card title="IDs de referencia externos" icon="link" href="/managing-external-reference-ids">
    Identifica a los clientes por tus propios IDs en lugar de los IDs de cuenta de Fluz.
  </Card>

  <Card title="Registro de empresas y KYB" icon="building-2" href="/business-registration">
    Incorpora empresas, no solo individuos.
  </Card>
</CardGroup>

<Note>
  **¿Quieres saber más?** Contáctanos en [support@fluz.app](mailto:support@fluz.app) para hablar con nuestros expertos o solicitar una demo.
</Note>