Skip to main content

​
Versão 2026-06-03

Versão inicial pública da API kycert.

​
Endpoints disponíveis

  • POST /api/v1/bureau/runs — criar run de bureau
  • GET /api/v1/bureau/runs — listar runs com filtros e paginação
  • GET /api/v1/bureau/runs/:id — obter status e resultado de um run
  • GET /api/v1/bureau/runs/:id/analysis — análise completa com todos os checks
  • GET /api/v1/bureau/runs/:id/detail — detalhe técnico por fonte (escopo detail:read)

​
Autenticação

  • Header x-api-key: sk_live_... (recomendado)
  • Header Authorization: Bearer sk_live_... (alternativo)
  • Escopos: runs:write, runs:read, detail:read

​
Webhooks

  • Evento run.completed — run finalizado com decisão
  • Evento run.failed — falha técnica no run
  • Verificação de assinatura HMAC-SHA256 via header kycert-signature
  • Política de retry: 7 tentativas em até 24h

​
Outros

  • Idempotency-Key no POST /runs — retry seguro nas próximas 24h
  • x-kycert-api-version — versionamento explícito
  • Sandbox com CPFs e CNPJs de teste
  • Paginação cursor-based no GET /runs

​
Política de breaking changes

Nos comprometemos com estabilidade. Antes de qualquer breaking change:
  1. Aviso mínimo de 90 dias — comunicado por e-mail e no dashboard
  2. Headers de deprecação — respostas incluirão Deprecation e Sunset quando um endpoint ou campo for depreciado
  3. E-mail de aviso — clientes com keys ativas na versão depreciada recebem notificação
  4. Versão antiga mantida por no mínimo 12 meses após o anúncio de depreciação

​
O que é considerado breaking change

  • Remover ou renomear um campo de response
  • Alterar o tipo de um campo existente
  • Remover um endpoint
  • Alterar o comportamento de um código de erro existente
  • Remover um valor de enum existente

​
O que não é breaking change

  • Adicionar novos campos opcionais ao request ou response
  • Adicionar novos endpoints
  • Adicionar novos valores de enum
  • Melhorar mensagens de erro
  • Mudanças de performance ou latência