> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Bootstrap de sesión del SDK: intercambia la clave por un client token
> Crea un client token JWT de corta duración llamando a POST /sdk/session desde tu servidor. Pasa el token al navegador para inicializar el SDK JS de Therius.
Antes de usar el SDK JS en el navegador, tu servidor debe intercambiar tu clave de API privada por un client token JWT de corta duración. Este token es lo que recibe el navegador — tu clave privada sin procesar nunca sale de tu servidor. Cada token está limitado a una sola sesión de checkout y expira después de 30 minutos.
## Crea una sesión en tu servidor
Llama a `POST /sdk/session` desde tu backend con tu clave de API privada en el encabezado `Authorization`.
```bash theme={"dark"}
curl -X POST https://api.therius.io/v1/sdk/session \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "customerId": "customer-42", "country": "US" }'
```
La respuesta incluye el `clientToken` y su vida útil en segundos:
```json theme={"dark"}
{
"clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 1800
}
```
## Pasa el token al navegador
Entrega el `clientToken` a tu front-end. Los enfoques comunes incluyen:
* **JSON inline** — insértalo en tu plantilla HTML cuando la página se renderiza en el servidor.
* **Respuesta de API** — devuélvelo desde un endpoint ligero `/api/checkout-session` que tu SPA llama al cargar la página.
El navegador no necesita decodificar ni inspeccionar el token — lo pasa directamente a `new TheriusSDK({ clientToken })`.
## Parámetros opcionales de la solicitud
| Parámetro | Tipo | Descripción |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country` | string | Código de país ISO de dos letras. Requerido para una sesión de checkout completa con un `sessionId`. |
| `customerId` | string | Asocia la sesión con un comprador recurrente. Habilita las funciones de tarjeta guardada. |
| `amount` | object | Precompleta el monto de la sesión — útil para las hojas de pago de wallet. |
| `currency` | string | Código de moneda ISO de tres letras emparejado con `amount`. |
| `orderCode` | string | Tu referencia de orden interna, adjuntada a la sesión para la conciliación. |
| `cardOnFile` | object | Declara que este checkout de la sesión inicia un mandato de credencial almacenada — ver [Suscripciones gestionadas por el comercio](#suscripciones-gestionadas-por-el-comercio) más abajo. Requiere `customerId`. |
## Suscripciones gestionadas por el comercio
Si gestionas tu propia facturación recurrente fuera de la API de Suscripciones de Therius — por ejemplo, un checkout único que debe establecer un mandato de tarjeta en archivo contra el que cobrarás tú mismo más adelante — pasa `cardOnFile` al crear la sesión, en lugar de configurar algo en el Checkout Builder:
```bash theme={"dark"}
curl -X POST https://api.therius.io/v1/sdk/session \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"customerId": "customer-42",
"country": "US",
"cardOnFile": { "type": "recurring" }
}'
```
Cuando `cardOnFile` está configurado:
* El Checkout Widget omite por completo la casilla opcional "guardar mi tarjeta" y muestra en su lugar un aviso fijo ("Tu tarjeta se guardará para cargos futuros") — no hay nada que el comprador deba aceptar, ya que declaraste la intención del lado del servidor.
* El cargo resultante se tokeniza y se etiqueta con los campos de credencial almacenada indicados (`usage`/`initiatedBy`/`type`, ver [Credenciales almacenadas](/es/guides/stored-credentials)) de forma incondicional, **sin importar lo que envíe el navegador** — el token de sesión firmado es la fuente de verdad, no el cuerpo de la solicitud.
* `customerId` es obligatorio — debe existir un comprador al que atribuir la tarjeta guardada.
Si omites `cardOnFile`, la sesión se comporta exactamente como antes: el checkout sigue lo que indique la configuración "guardar mi tarjeta" (consentimiento de vault) del Checkout Builder, y cualquier tarjeta guardada resultante es una tarjeta en archivo simple, no un mandato recurrente.
Antes existía una casilla separada "Inicia una suscripción gestionada por el comercio" en el Checkout Builder. Se eliminó — ahora es una configuración por transacción y controlada por el servidor, en lugar de un indicador estático por configuración de checkout, así que un comprador nunca puede ver (ni suprimir) el estado de consentimiento incorrecto para una sesión determinada.
## Inicializa el SDK en el navegador
Una vez que el navegador tiene el token, inicializa el SDK:
```javascript theme={"dark"}
import { TheriusSDK } from '@therius/sdk'
const sdk = new TheriusSDK({ clientToken })
```
El SDK valida el token de inmediato. Si el token falta o está mal formado, `TheriusSDK` lanza una excepción de forma síncrona.
## Vida útil del token
Los client tokens expiran después de **30 minutos**. Crea un token fresco para cada nueva sesión de checkout — no caches ni reutilices tokens entre sesiones o cargas de página.
Nunca llames a `POST /sdk/session` desde el navegador. Requiere tu clave de API privada (`prv_production_...`). Exponer esa clave del lado del cliente permitiría a cualquiera crear sesiones y hacer cobros contra tu cuenta. Haz siempre esta llamada solo desde tu backend.
## Referencia
Ver la [referencia de la API POST /sdk/session](/api-reference/sdk-session) para la referencia completa de campos, incluidos los códigos de error y las reglas de validación.