Desenvolvedor — chaves de API e API REST

O que ela faz

A API REST da Certivant permite que os seus próprios sistemas criem solicitações de verificação, enviem documentos e consultem o status — sem passar pelo painel. Dois casos de uso principais:

1. Incorporar a verificação ao seu próprio fluxo de cadastro. O seu formulário de cadastro envia os dados ao seu back-end, o back-end chama a Certivant e o solicitante recebe um link do fluxo hospedado da Certivant.
2. Sincronizar o status da verificação com o seu data warehouse ou CRM. Combine com webhooks para que os seus sistemas sejam atualizados a cada mudança de status.

A autenticação da API é feita por chaves de API emitidas no painel. A documentação completa dos endpoints fica em /app/{your-org}/kyc/developer — esta página cobre o gerenciamento de chaves e a visão geral conceitual.

Onde encontrar

KYC → Desenvolvedor na barra lateral esquerda. (As chaves de API ficavam nas configurações de KYC/B — agora elas têm uma página própria em Desenvolvedor.)

O Portal do Desenvolvedor é um hub único com um menu à esquerda:

• Visão geral e início rápido — a sua URL base, a autenticação e uma requisição pronta para copiar e colar em 8 linguagens (cURL, JavaScript, TypeScript, Python, PHP, Go, Java, C#). Os trechos já vêm preenchidos com o seu host real e um marcador no lugar da sua chave.
• Chaves de API — liste, crie e revogue as suas chaves.
• Referência de endpoints — todos os endpoints de integração (/v1) com método, caminho, escopos e parâmetros, além de um link para o API Playground interativo.
• Manipuladores de webhook — manipuladores prontos que verificam a assinatura, em 6 linguagens (veja também Webhooks).
• Limite de taxa — o limite efetivo por minuto da sua organização, exibido somente para leitura.
• Perguntas frequentes — as dúvidas mais comuns de quem faz a integração.

Emita uma chave de API

Use a chave

Envie-a no cabeçalho Authorization:

Authorization: Bearer ck_live_a3f...

As chaves criadas antes do formato ck_live_ / ck_test_ (que começam com kyk_) continuam funcionando sem alterações.

O caminho mais rápido para uma integração funcional:

curl https://api.certivant.com/api/v1/kyc/requests \
  -H "Authorization: Bearer $CV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INDIVIDUAL",
    "applicant": {
      "fullName": "Jane Doe",
      "email": "jane@example.com"
    }
  }'

Atribuição a parceiro / subtenant

Se você executa verificações em nome de muitos clientes finais a partir de uma única organização — o clássico modelo de parceiro / revendedor, por exemplo uma plataforma de assinatura eletrônica que verifica signatários de centenas de empresas — não é preciso ter uma organização por cliente. Marque cada solicitação com dois campos opcionais ao criá-la pela API:

• subTenantName — o nome de exibição do cliente final (por exemplo "Acme Corp").
• subTenantExternalId — o seu id interno desse cliente (por exemplo cust_8842).

Depois de marcadas, você pode:

• Filtrar o endpoint de listagem por subTenantExternalId (GET /api/v1/kyc/requests?subTenantExternalId=cust_8842).
• Direcionar webhooks — os dois campos são repetidos em cada envelope de evento, de modo que o seu manipulador sabe a qual cliente um resultado pertence sem precisar fazer uma consulta.
• Filtrar os painéis — Uso de KYC/B, Registro de auditoria, Monitoramento, Relatórios e Análises ganham um filtro de Subtenant assim que alguma solicitação tiver as marcações, e as listas de KYC/KYB podem exibir as colunas Subtenant e ID externo (ocultas por padrão — ative-as no menu de colunas).

Veja a referência da API para o formato exato da requisição: Solicitações de KYC → Criar uma solicitação.

Limites de taxa

O limite de requisições por minuto da sua API é definido pelo seu plano (valores típicos: 60/min no Launch, 300/min no Pro/Scale, 600/min no Enterprise). O teto exato da sua organização é exibido somente para leitura na página Desenvolvedor, e cada resposta da API o traz no cabeçalho X-RateLimit-Limit. Cada chave é medida de forma independente em relação a esse teto.

Quando você o excede, as requisições retornam HTTP 429 Too Many Requests com X-RateLimit-Reset (segundos até a janela ser reiniciada). Aguarde e tente novamente.

Precisa de um teto maior? O seu superadministrador o define — ele pode aumentar o limite do seu cliente até o teto do plano em Admin → Clientes → (sua organização) → Editar organização (um teto maior exige migrar para um plano superior). O limite é controlado pelo operador: os tenants podem visualizá-lo, mas não alterá-lo. Veja a referência para desenvolvedores para conhecer toda a mecânica: Limites de taxa.

Boas práticas de segurança

• Guarde as chaves em variáveis de ambiente ou em um gerenciador de segredos. Nunca as envie ao git nem as compartilhe em chats. Chaves enviadas a repositórios públicos costumam ser coletadas por robôs em poucos minutos.
• Uma chave por ambiente. Não compartilhe uma chave ck_live_... entre homologação e produção — a rotação de uma não deve afetar a outra.
• Use chaves com escopo restrito. Uma chave somente leitura para o monitoramento e uma chave de escrita para o serviço de cadastro é mais seguro do que uma única chave onipotente em todos os lugares.
• Prenda as chaves aos seus servidores. Adicione a lista de IPs permitidos para chaves usadas apenas a partir de endereços fixos.
• Rotacione a cada trimestre. Use Rotacionar (abaixo): a chave antiga continua funcionando durante a sobreposição que você escolher, e assim você implanta a nova sem tempo de inatividade. O registro de auditoria registra a troca.
• Fique atento a usos não autorizados. A lista de chaves mostra quando e a partir de qual endereço cada chave foi usada pela última vez, e o registro de auditoria registra a criação, as edições, a rotação e a revogação das chaves. Investigue qualquer endereço que você não reconheça.

Rotacione uma chave

Desenvolvedor → Chaves de API → Rotacionar cria uma substituta com o mesmo rótulo, as mesmas permissões, restrições, lista de IPs permitidos e expiração, e exibe a nova chave uma única vez.

• Sobreposição (0 a 168 horas, padrão 24). A chave antiga continua funcionando durante esse período e depois retorna 401 api_key_rotated. Defina 0 para revogar a chave antiga imediatamente.
• A lista marca a chave antiga como "Rotacionada — a chave antiga funciona até …" e a nova como "Substitui uma chave rotacionada". Uma chave que já foi rotacionada não pode ser rotacionada novamente; rotacione a substituta dela.
• Você também pode editar ou revogar a chave antiga durante a sobreposição, se precisar cortá-la antes.

Revogue uma chave

Quando uma chave for comprometida, vazada ou não for mais necessária:

• Desenvolvedor → Chaves de API → menu de três pontos → Revogar.
• Entra em vigor imediatamente. Qualquer requisição em andamento que use a chave recebe 401 na próxima chamada.
• Não pode ser desfeito — não existe um botão para "desfazer a revogação". Emita uma nova chave se mudar de ideia.

A revogação é registrada no registro de auditoria, junto com o usuário que a realizou.

Live vs. test

Toda chave é:

• Test (ck_test_...) — destinada a desenvolvimento e CI.
• Live (ck_live_...) — destinada à produção.

O ambiente marca o uso: cada resposta traz X-Certivant-Environment: test ou live, e o painel exibe o selo ao lado da chave, para que você distinga nos seus logs o tráfego de teste do tráfego de produção.

Solução de problemas

401 Unauthorized

O error.reason no corpo da resposta informa o motivo:

403 Forbidden

error.reason:

429 Too Many Requests

Você está sendo limitado por taxa. Consulte o cabeçalho Retry-After (em segundos) e aguarde de acordo. Para um volume sustentado, peça um limite maior.

"Perdi o valor da chave"

As chaves são exibidas uma única vez. Não há recuperação. Revogue a chave antiga e emita uma nova — a sua equipe terá de atualizar o novo valor em todos os lugares onde o antigo foi implantado.

Veja também

• Webhooks — combine com a API para uma integração completa.
• Lista e detalhe de KYC — a visão, no painel, das solicitações criadas pela API.
• Registro de auditoria — toda chamada de API aparece aqui.