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

# Guía para desarrolladores de VU ONE FREE

> Todo lo que necesita antes de integrar VU ONE FREE: URLs del tenant, qué flujo OAuth usar según su aplicación, convenciones de la API y cómo manejar el 402.

Esta guía reúne lo que conviene saber antes de escribir la primera línea de código contra **VU ONE**: dónde vive la API de su tenant, qué flujo de OAuth corresponde a cada tipo de aplicación y qué convenciones comparten todos los endpoints. Si prefiere probar primero, siga el [Inicio rápido](https://docs.vu-one.com/vu-one/inicio-rapido.md) y vuelva después.

> [!WARNING]
>
> **VU ONE FREE es una versión limitada, en vista previa.** Solo la usan las cuentas de Identity Link que VU seleccionó hasta la disponibilidad general. Algunas funciones son del plan pago y las funciones, los límites y esta documentación pueden cambiar. [Vea qué incluye](https://docs.vu-one.com/vu-one/plan-free.md).

## URLs de su tenant

Cada tenant tiene su propio host. Todas las URLs de esta documentación usan la variable `$TENANT_HOST`:

```bash theme={null}
export TENANT_HOST="wispy-waterfall-3912.prod.vu-one.com"
```

| Para | URL |
| - | - |
| API | `https://$TENANT_HOST/middleware/api/v1/...` |
| Token | `https://$TENANT_HOST/middleware/oauth2/token` |
| Discovery de OpenID Connect | `https://$TENANT_HOST/middleware/.well-known/openid-configuration` |
| Claves públicas (JWKS) | `https://$TENANT_HOST/middleware/oauth2/jwks` |
| SCIM 2.0 | `https://$TENANT_HOST/middleware/scim/v2` |
| Consola | `https://$TENANT_HOST/vuone/es/signin/governance` |

Lea los endpoints de OAuth desde el documento de discovery en lugar de escribirlos a mano.

## Qué flujo usar

| Su caso | Flujo | Guía |
| - | - | - |
| Sus usuarios ingresan a una aplicación web, móvil o de una sola página | Código de autorización con PKCE. Una aplicación de una sola página o móvil no puede guardar un secreto: registre un cliente con el método de autenticación **Ninguno**. | [Autenticación](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md) |
| Un backend o un proceso programado llama a la API sin usuario | `client_credentials` | [Autenticación](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md) |
| Mantener la sesión sin pedir el ingreso otra vez | `refresh_token` | [Autenticación](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md) |
| Su sistema crea y administra usuarios | API de identidades y cuentas | [Identidades y cuentas](https://docs.vu-one.com/vu-one/desarrolladores/cuentas.md) |
| Su aplicación envía un código por e-mail, un enlace mágico o pide TOTP | API de factores | [Factores](https://docs.vu-one.com/vu-one/desarrolladores/factores.md) |
| Su directorio corporativo sincroniza usuarios y grupos | SCIM 2.0 | [SCIM](https://docs.vu-one.com/vu-one/desarrolladores/scim.md) |

Los flujos de OAuth y las llamadas a `/api/v1` necesitan un cliente OAuth registrado en la consola. Vea [Clientes OAuth](https://docs.vu-one.com/vu-one/admin/clientes-oauth.md). SCIM usa un token propio que se crea en la consola. Vea [SCIM en la consola](https://docs.vu-one.com/vu-one/admin/scim.md).

## Convenciones de la API

> [accordion] Autenticación de las llamadas
>
> Todas las llamadas a `/api/v1` llevan `Authorization: Bearer $TOKEN`. El token define el alcance: el tenant completo o un negocio. Los encabezados `X-Business-Id`, `X-Channel-Id` y `X-Account-Scope` fijan el contexto de la llamada dentro de ese alcance. Vea [Autenticación](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md).

> [accordion] Paginación
>
> La mayoría de las listas usan el mismo sobre: `currentPage`, `pageSize`, `totalElements`, `totalPages` y `content`. La primera página es la `1`. En la mayoría de los endpoints, si no envía `pageSize`, la API devuelve 10 elementos. Algunos endpoints usan otro valor predeterminado. Envíe `pageSize` en cada llamada para obtener un resultado previsible.

> [accordion] Errores
>
> Un error llega en una de tres formas según la capa que responde: gateway, API de negocio u OAuth. En la API de negocio, decida con el campo `codeKey`, no con el texto de `message`. Vea [Errores](https://docs.vu-one.com/vu-one/desarrolladores/errores.md).

> [accordion] SDK
>
> Durante la vista previa, los SDK no se distribuyen públicamente. Integre con HTTP y cualquier biblioteca estándar de OAuth 2.0 y OpenID Connect.

## Prepare su código para el plan FREE

VU ONE FREE es una versión limitada. Cuando su código llama a una función del plan pago, la API responde `402` con el código `4020`. Cuando la función está oculta en FREE, responde `404`, en general sin cuerpo. Maneje los dos casos como estados esperados:

```javascript theme={null}
const res = await fetch(`https://${TENANT_HOST}/middleware/api/v1/...`, {
  headers: { Authorization: `Bearer ${token}` },
});

if (res.status === 402) {
  const body = await res.json();
  // body.code === 4020 y body.feature indica la función del plan pago.
  // No reintente: muestre un aviso o use una alternativa incluida en FREE.
}
```

Por ejemplo, si su flujo de ingreso usa un código por SMS, en FREE use el código por e-mail o TOTP. Vea qué incluye cada plan en [FREE y plan pago](https://docs.vu-one.com/vu-one/plan-free.md).

## Qué sigue

> [card] [Inicio rápido](https://docs.vu-one.com/vu-one/inicio-rapido.md)
>
> Su primer token y su primera llamada.

> [card] [Autenticación](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md)
>
> Código de autorización con PKCE, `client_credentials` y validación de tokens.

> [card] [Errores](https://docs.vu-one.com/vu-one/desarrolladores/errores.md)
>
> Formas de error, códigos y reintentos.

> [card] [Conceptos](https://docs.vu-one.com/vu-one/conceptos.md)
>
> Tenant, negocio, canal, identidad y cuenta.


## Related topics

- [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md)
- [Inicio rápido de VU ONE FREE](https://docs.vu-one.com/vu-one/inicio-rapido.md)
- [Crear su tenant de VU ONE FREE](https://docs.vu-one.com/vu-one/admin/crear-tenant.md)
- [Qué es VU ONE FREE](https://docs.vu-one.com/vu-one/introduccion.md)
- [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.