Sessões hospedadas

Uma sessão hospedada é a forma mais simples de coletar documentos. Você cria a solicitação no lado do servidor, depois pede à Certivant uma URL de sessão e a entrega ao solicitante. A Certivant cuida do envio de documentos, da captura pela câmera, da prova de vida, do feedback de OCR e das novas tentativas — você só precisa aguardar o webhook.

Quando usar uma sessão

A maioria das integrações usa sessões. O envio de documentos por API é uma rota de escape para casos especiais.

Gerar uma URL de sessão

POST /api/v1/kyc/requests/:id/session-url    Escopo: kyc:write

A solicitação deve estar no estado PENDING_UPLOAD.

Corpo da requisição

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Resposta

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

A URL contém um token assinado de uso único. Depois que ele expira (ou depois que o solicitante envia), é invalidado. Gere uma nova se o solicitante precisar de outra tentativa.

O fluxo do solicitante

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

O solicitante não precisa de conta para usar a URL de sessão — a Certivant não lhe emite um login. Ele clica, conclui o fluxo e sai. Todo o estado fica na solicitação, e não em um registro de usuário.

Personalização e marca branca

A interface hospedada usa as configurações de marca branca da sua organização — logotipo, cor da marca, e-mail de suporte e domínio personalizado, se você tiver configurado um. Configure isso uma vez em Configurações → Marca branca no painel; todas as sessões herdam essas configurações.

Domínios personalizados

Por padrão, as sessões e os formulários hospedados ficam no host compartilhado da Certivant (app.certivant.com/s/…). Se você quiser que fiquem no seu próprio domínio (verify.yourcompany.com, por exemplo), configure um domínio personalizado em Configurações → Marca branca → Domínio personalizado. Isso altera apenas os links voltados ao solicitante — o host da API e o caminho base /api/v1/kyc continuam iguais, e sua organização continua sendo identificada pela sua chave de API.

Celular ou computador

A sessão é responsiva e funciona em celulares, tablets e computadores. A captura de documentos usa a câmera do dispositivo no celular; no computador, a Certivant pede ao solicitante que mude para o celular por meio de um QR code, para que a prova de vida e a digitalização do documento usem a câmera de melhor qualidade. Isso é automático — sua integração não precisa detectar nada.

O que acontece após o envio

Quando o solicitante clica em Enviar na página hospedada:

1. A Certivant chama POST /requests/:id/submit internamente, em nome do solicitante.
2. A solicitação passa para PROCESSING.
3. O primeiro webhook é disparado: kyc.request.processing.
4. O processamento termina (normalmente em alguns segundos). Um segundo webhook é disparado: kyc.request.approved, kyc.request.rejected ou kyc.request.escalated.
5. Se você informou redirectUrl, o solicitante é enviado para lá. Caso contrário, ele vê uma página de agradecimento.

O seu backend deve aguardar o webhook — não consulte o endpoint da solicitação para detectar a conclusão. Veja Webhooks.

Reutilizando uma URL de sessão após a rejeição

Se a solicitação for rejeitada e você chamar POST /requests/:id/resubmit, a URL de sessão existente não é reativada. Gere uma nova:

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Depois, envie a nova URL por e-mail ao solicitante. Dica: use o mesmo externalRef para que a linha do seu banco de dados continue correlacionada.

Formulários como alternativa

Se você precisar coletar dados estruturados (não apenas documentos) — respostas a questionários de conformidade, detalhes sobre a origem dos recursos, campos adicionais de KYB —, use Formulários em vez da sessão (ou além dela). Os formulários ficam no painel, em KYC → Formulários, e cada um tem uma URL pública de envio: https://app.certivant.com/forms/:slug.

Os formulários criam automaticamente uma solicitação KYC no envio, anexam as respostas do formulário como metadados e disparam os mesmos webhooks. Veja a documentação para organizações em Formulários para a configuração. Os desenvolvedores normalmente não interagem com formulários pela API — o construtor de formulários do painel é a interface prevista.

Erros

• 400 BAD_REQUEST — a solicitação não está em PENDING_UPLOAD. Você só pode gerar URLs de sessão para solicitações que aguardam documentos.
• 400 VALIDATION_ERROR — expiresInHours fora do intervalo de 1–168, ou redirectUrl não é uma URL válida.

Notas de segurança

• A URL de sessão contém um token assinado — qualquer pessoa com a URL pode concluir a verificação. Trate-a como um link de redefinição de senha: envie-a diretamente ao solicitante por um canal ao qual só ele tenha acesso.
• Use expiresInHours curto (24 ou 48) em fluxos de alto risco. Use uma validade mais longa somente quando for esperado que o solicitante tenha tempo para reunir os documentos.
• Depois que uma sessão expira sem uso, a solicitação de origem permanece em PENDING_UPLOAD. Gere uma nova URL ou entre em contato com o solicitante para reenviá-la.