> ## 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 sessão do SDK: troque a chave por um client token
> Crie um client token JWT de curta duração chamando POST /sdk/session do seu servidor. Passe o token ao navegador para inicializar o SDK JS do Therius.
Antes de usar o SDK JS no navegador, o seu servidor precisa trocar a sua chave de API privada por um client token JWT de curta duração. Esse token é o que o navegador recebe — a sua chave privada bruta nunca sai do seu servidor. Cada token é limitado a uma única sessão de checkout e expira após 30 minutos.
## Crie uma sessão no seu servidor
Chame `POST /sdk/session` do seu backend com a sua chave de API privada no cabeçalho `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" }'
```
A resposta inclui o `clientToken` e o tempo de vida dele em segundos:
```json theme={"dark"}
{
"clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 1800
}
```
## Passe o token ao navegador
Entregue o `clientToken` ao seu front-end. As abordagens comuns incluem:
* **JSON inline** — insira-o no seu template HTML quando a página é renderizada no servidor.
* **Resposta de API** — devolva-o de um endpoint leve `/api/checkout-session` que a sua SPA chama ao carregar a página.
O navegador não precisa decodificar nem inspecionar o token — ele o passa diretamente para `new TheriusSDK({ clientToken })`.
## Parâmetros opcionais da requisição
| Parâmetro | Tipo | Descrição |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `country` | string | Código de país ISO de duas letras. Obrigatório para uma sessão de checkout completa com um `sessionId`. |
| `customerId` | string | Associa a sessão a um comprador recorrente. Habilita os recursos de cartão salvo. |
| `amount` | object | Pré-preenche o valor da sessão — útil para as folhas de pagamento de carteira. |
| `currency` | string | Código de moeda ISO de três letras pareado com `amount`. |
| `orderCode` | string | A sua referência de pedido interna, anexada à sessão para a conciliação. |
| `cardOnFile` | object | Declara que o checkout desta sessão inicia um mandato de credencial armazenada — veja [Assinaturas gerenciadas pelo lojista](#assinaturas-gerenciadas-pelo-lojista) abaixo. Exige `customerId`. |
## Assinaturas gerenciadas pelo lojista
Se você gerencia sua própria cobrança recorrente fora da API de Assinaturas do Therius — por exemplo, um checkout único que deve estabelecer um mandato de cartão em arquivo contra o qual você mesmo vai cobrar depois — envie `cardOnFile` ao criar a sessão, em vez de configurar algo no 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" }
}'
```
Quando `cardOnFile` está definido:
* O Checkout Widget pula completamente a caixa de seleção opcional "salvar meu cartão" e mostra em vez disso um aviso fixo ("Seu cartão será salvo para cobranças futuras") — não há nada para o comprador optar, já que você já declarou a intenção no lado do servidor.
* A cobrança resultante é tokenizada e marcada com os campos de credencial armazenada informados (`usage`/`initiatedBy`/`type`, veja [Credenciais Armazenadas](/pt/guides/stored-credentials)) incondicionalmente, **independentemente do que o navegador enviar** — o token de sessão assinado é a fonte da verdade, não o corpo da requisição.
* `customerId` é obrigatório — precisa existir um comprador ao qual atribuir o cartão salvo.
Se você omitir `cardOnFile`, a sessão se comporta exatamente como antes: o checkout segue o que a configuração "salvar meu cartão" (consentimento de vault) do Checkout Builder disser, e qualquer cartão salvo resultante é um cartão em arquivo simples, não um mandato recorrente.
Antes existia uma caixa de seleção separada "Inicia uma assinatura gerenciada pelo lojista" no Checkout Builder. Ela foi removida — agora isso é uma configuração por transação e controlada pelo servidor, em vez de um indicador estático por configuração de checkout, então um comprador nunca consegue ver (nem suprimir) o estado de consentimento errado para uma determinada sessão.
## Inicialize o SDK no navegador
Assim que o navegador tem o token, inicialize o SDK:
```javascript theme={"dark"}
import { TheriusSDK } from '@therius/sdk'
const sdk = new TheriusSDK({ clientToken })
```
O SDK valida o token de imediato. Se o token estiver ausente ou malformado, `TheriusSDK` lança uma exceção de forma síncrona.
## Tempo de vida do token
Os client tokens expiram após **30 minutos**. Crie um token novo para cada nova sessão de checkout — não faça cache nem reutilize tokens entre sessões ou carregamentos de página.
Nunca chame `POST /sdk/session` do navegador. Ela exige a sua chave de API privada (`prv_production_...`). Expor essa chave no lado do cliente permitiria que qualquer pessoa criasse sessões e fizesse cobranças contra a sua conta. Faça sempre essa chamada apenas do seu backend.
## Referência
Veja a [referência da API POST /sdk/session](/api-reference/sdk-session) para a referência completa de campos, incluindo os códigos de erro e as regras de validação.