Criar Sessão KYC - Campeão Sec

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

{
  "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

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

Exemplos

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"]
  }'

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

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']

Consultar Resultado (Fallback)

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

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`

​Visão Geral

​Endpoint

​Request

​Headers

​Body

​Tipos de documento (documentos_aceitos)

​Response

​Exemplos

​Consultar Resultado (Fallback)

​Erros

Visão Geral

Endpoint

Request

Headers

Body

Tipos de documento (`documentos_aceitos`)

Response

Exemplos

Consultar Resultado (Fallback)

Erros