Documentação para desenvolvedores da Certivant
Crie integrações com a API da Certivant — KYC, KYB, envio de documentos, sessões hospedadas e eventos de webhook.
Bem-vindo à documentação para desenvolvedores da Certivant. Esta é a referência técnica para integrar a plataforma de KYC e KYB da Certivant ao seu próprio produto.
Se você procura como usar a Certivant no navegador, consulte a documentação para organizações — este site pressupõe que você está escrevendo código que se comunica com a API REST.
O que você pode construir
- Executar uma verificação de identidade (KYC) a partir do seu próprio aplicativo — envie um solicitante, colete documentos por meio de uma sessão hospedada ou da sua própria interface e receba uma decisão de aprovar / rejeitar / encaminhar para revisão.
- Executar uma verificação empresarial (KYB) — envie dados da empresa, diretores e beneficiários finais e confira-os com registros oficiais e listas de sanções.
- Receber webhooks em tempo real quando uma solicitação mudar de estado, um documento for enviado ou uma verificação for concluída.
- Gerenciar solicitações pelo painel com sua própria automação — os mesmos endpoints alimentam a interface web da Certivant.
- Atribuir solicitações aos seus próprios clientes (modo parceiro) — execute verificações para muitos clientes finais dentro de uma única organização, marque cada solicitação com um nome de subcliente e um ID externo, e filtre ou direcione por eles na API e nos webhooks.
Em resumo
| URL base | https://app.certivant.com/api/v1/kyc |
| Autenticação | Authorization: Bearer ck_live_… ou ck_test_… (chave de API, por organização; chaves antigas kyk_… continuam funcionando) |
| Tipo de conteúdo | application/json (ou multipart/form-data para envio de documentos) |
| Limite de requisições | Baseado no plano — veja Limites de requisições |
| Assinatura do webhook | X-Certivant-Signature-V2: t=…,v1=… (HMAC-SHA256 sobre timestamp.body, tolerância de 300 s) — veja Verificação de assinatura |
| Referência interativa | Referência da API, ou abra diretamente /api/v1/docs — público, gerado a partir do esquema OpenAPI |
| Esquema OpenAPI | /api/v1/openapi.json — OpenAPI 3.1 público, sem necessidade de login |
Um único host, e não um subdomínio por cliente. No serviço hospedado, todas as organizações compartilham o mesmo host, app.certivant.com — não existe sua-org.certivant.com, então use app.certivant.com nos exemplos como está. (Implantações self-hosted usam o domínio configurado pelo operador; certivant.com é o site de marketing, não o aplicativo.) Na API, sua organização é identificada pela sua chave de API, nunca pela URL: o caminho base é /api/v1/kyc, sem slug da organização. O slug só aparece onde uma pessoa navega — o painel em /app/{org-slug} e os links de formulários e sessões hospedadas como /forms/{slug}. Um domínio personalizado white-label pode colocar esses links voltados para pessoas no seu próprio domínio, mas o host da API não muda.
A referência interativa e o esquema OpenAPI bruto são públicos: não é preciso login nem chave de API, e eles descrevem apenas os endpoints de integração (/api/v1). Veja Referência da API.
Primeiros passos
Referência
- Formulários — liste os formulários de KYC e KYB da organização para escolher qual usar em uma verificação.
- Solicitações de KYC — criar, listar, buscar, submeter, decidir e reenviar.
- Solicitações de KYB — verificação empresarial com diretores e UBOs.
- Documentos — enviar documentos de identidade e buscar URLs de download assinadas.
- Sessões hospedadas — gere uma URL de curta duração na qual o solicitante conclui o fluxo.
- Lista de bloqueio — adicione e remova e-mails, números de telefone, números de documentos e endereços IP bloqueados, ou bloqueie o rosto, o dispositivo e o IP por trás de uma verificação.
- Verificação de idade — estime, a partir de uma selfie, se a pessoa tem idade suficiente, com fallback para a data de nascimento do documento.
- Verificações reutilizadas — permita que um solicitante que já passou por uma verificação da Certivant em outro lugar a reutilize com você (pessoas físicas e empresas).
- Incorpore no seu site ou aplicativo — mostre uma verificação na sua própria página com uma única tag de script, ou em um WebView do React Native ou Flutter.
- Referência da API (OpenAPI) — o documento OpenAPI 3.1 público e a referência interativa.
- Verificação ao vivo — agende, acompanhe, reagende ou cancele uma sessão de verificação de identidade ao vivo conduzida por um anfitrião humano e receba a decisão por webhook.
- Live ID Validation — login biométrico: compare a selfie ao vivo de um usuário recorrente com o rosto verificado no KYC dele.
- Servidor MCP — conecte um assistente de IA à sua fila de verificações pelo Model Context Protocol.
- Webhooks — registre uma URL, verifique assinaturas e trate novas tentativas.
- Erros — códigos de erro, mapeamento de status HTTP e formato dos campos de validação.
- Limites de requisições — cotas, cabeçalhos, estratégia de novas tentativas.
- Esquemas — enums, valores de status, formatos de requisição e resposta que você verá com frequência.