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

# Criar Sessão KYC

> Crie uma sessão de verificação e obtenha o token para iniciar o widget.

## Visão Geral

O fluxo KYC começa no seu servidor: você cria uma sessão e recebe um `session_token` de curta duração. Esse token é passado para o frontend que inicializa o widget — o usuário nunca tem acesso à sua API Key.

```
Seu servidor                Widget (frontend do usuário)
    │                               │
    │── POST /v1/verify/session ──► API Campeão Sec
    │◄── { session_token } ─────────│
    │                               │
    │── session_token ─────────────►│
    │                    CampeaoSec.init({ sessionToken })
    │                               │◄── captura doc + selfie
    │                               │◄── webhook enviado ao seu servidor
```

***

## Endpoint

```
POST https://api-kyc.campeaosec.com/v1/verify/session
```

***

## Request

### Headers

| Header          | Valor                                        |
| --------------- | -------------------------------------------- |
| `Authorization` | `Bearer sk_test_...` ou `Bearer sk_live_...` |
| `Content-Type`  | `application/json`                           |

### Body

| Campo                | Tipo      | Obrigatório | Descrição                                                                                 |
| -------------------- | --------- | ----------- | ----------------------------------------------------------------------------------------- |
| `country`            | string    | Não         | Código ISO do país do usuário (ex: `BR`, `US`, `PT`). Default: `WORLD`                    |
| `external_id`        | string    | Não         | Identificador do usuário no seu sistema. Retornado no webhook. Max 255 chars              |
| `webhook_url`        | string    | Não         | URL para receber a notificação desta verificação. Sobrescreve a URL configurada no portal |
| `ambiente`           | string    | Não         | `sandbox` ou `producao`. Default: `sandbox`                                               |
| `documentos_aceitos` | string\[] | Não         | Tipos de documento que o widget deve oferecer. Ver tabela abaixo                          |

### Tipos de documento (`documentos_aceitos`)

| Valor             | Documento                                   | Verso necessário |
| ----------------- | ------------------------------------------- | ---------------- |
| `passport`        | Passaporte                                  | Não              |
| `cin`             | CIN (Carteira de Identidade Nacional — BR)  | Não              |
| `cnh`             | CNH (Carteira Nacional de Habilitação — BR) | Não              |
| `rg`              | RG (Registro Geral — BR)                    | **Sim**          |
| `national_id`     | Documento de Identidade Nacional            | Não              |
| `drivers_license` | Carteira de Habilitação                     | Não              |

Se não enviado, o widget exibe todos os tipos compatíveis com o `country` informado.

***

## Response

```json theme={null}
{
  "session_token": "a3f8c2d1b4e9...",
  "expira_em": "2026-07-30T11:30:00Z"
}
```

| Campo           | Tipo   | Descrição                                                            |
| --------------- | ------ | -------------------------------------------------------------------- |
| `session_token` | string | Token de 64 caracteres para inicializar o widget                     |
| `expira_em`     | string | Data/hora de expiração (ISO 8601). A sessão expira em **30 minutos** |

<Warning>
  O `session_token` expira em 30 minutos. Gere-o imediatamente antes de inicializar o widget. Não armazene nem reutilize tokens.
</Warning>

***

## Exemplos

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-kyc.campeaosec.com/v1/verify/session \
    -H "Authorization: Bearer sk_test_sua_chave" \
    -H "Content-Type: application/json" \
    -d '{
      "country": "BR",
      "external_id": "user-456",
      "ambiente": "sandbox",
      "webhook_url": "https://investimentos.com.br/webhook/kyc",
      "documentos_aceitos": ["passport", "rg", "cin", "cnh"]
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api-kyc.campeaosec.com/v1/verify/session', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_sua_chave',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      country: 'BR',
      external_id: 'user-456',
      ambiente: 'sandbox',
      webhook_url: 'https://investimentos.com.br/webhook/kyc',
      documentos_aceitos: ['passport', 'rg', 'cin', 'cnh'],
    }),
  })
  const { session_token, expira_em } = await res.json()

  // Passe session_token para o frontend via sua API interna
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api-kyc.campeaosec.com/v1/verify/session',
      headers={
          'Authorization': 'Bearer sk_test_sua_chave',
          'Content-Type': 'application/json',
      },
      json={
          'country': 'BR',
          'external_id': 'user-456',
          'ambiente': 'sandbox',
          'webhook_url': 'https://investimentos.com.br/webhook/kyc',
          'documentos_aceitos': ['passport', 'rg', 'cin', 'cnh'],
      }
  )
  data = response.json()
  session_token = data['session_token']
  ```
</CodeGroup>

***

## Consultar Resultado (Fallback)

Se o webhook não chegar, você pode consultar o resultado diretamente:

```bash theme={null}
curl -X GET https://api-kyc.campeaosec.com/v1/verify/{verification_id} \
  -H "Authorization: Bearer sk_test_sua_chave"
```

O `verification_id` é retornado no payload do webhook. Para obtê-lo sem webhook, consulte o status da sessão via `GET /v1/verify/session/{session_token}/status` (acessível apenas com o session\_token, não com a API key).

***

## Erros

| Código | Detalhe                | Causa                                   |
| ------ | ---------------------- | --------------------------------------- |
| `401`  | `unauthorized`         | API Key inválida                        |
| `402`  | `insufficient_credits` | Saldo de créditos KYC zerado (produção) |
| `422`  | `invalid_country`      | Código de país inválido                 |
| `422`  | `invalid_ambiente`     | Deve ser `sandbox` ou `producao`        |