Pular para o conteúdo principal

Documentação da API Lucent KYC

Bem-vindo à documentação completa da API do Lucent KYC. Esta plataforma oferece APIs robustas para consultas KYC (Know Your Customer) de CPF e CNPJ com avaliação de risco automatizada.

🎯 Visão Geral​

A API Lucent KYC permite que você:

  • Consulte dados de CPF e CNPJ via integração com múltiplos provedores de dados (BigDataCorp, Google, Serviços Lucent Minds)
  • Avalie riscos automaticamente usando regras configuráveis e IA
  • Gerencie perfis unificados com histórico completo de consultas
  • Monitore compliance com recertificação baseada em risco
  • Integre sistemas externos via REST API com autenticação por API Key

🔗 URLs Base​

AmbienteURL BaseDescrição
Desenvolvimentohttp://localhost:3000/apiServidor local
Produçãohttps://api.lucent-kyc.com/apiAmbiente produtivo

🔐 Autenticação​

A API suporta dois métodos de autenticação:

JWT Bearer Token (Web UI)​

Para usuários da interface web, use tokens JWT do Supabase:

Authorization: Bearer SEU_JWT_TOKEN

API Key (Integração Externa)​

Para integração de sistemas externos, use API keys:

x-api-key: SUA_API_KEY

→ Guia Completo de Autenticação

📚 Categorias da API​

1. Autenticação​

Guia detalhado sobre autenticação JWT e API Keys.

2. Consultas KYC (5 endpoints)​

Endpoints para consultar dados de CPF e CNPJ:

  • POST /kyc/cpf - Consultar CPF
  • POST /kyc/cnpj - Consultar CNPJ
  • POST /kyc/mock - Salvar consulta mock
  • POST /kyc/batch - Consultas em lote
  • GET /profiles/expired - Perfis expirados

3. Gestão de Perfis (12 endpoints)​

Gerenciamento completo de perfis unificados:

  • Listar e buscar perfis CPF/CNPJ
  • Histórico de consultas
  • Estatísticas e timeline de risco
  • Exportação de dados
  • Comentários e revisões

4. Avaliação de Risco (6 endpoints)​

Cálculo e análise de riscos:

  • Calcular/recalcular avaliações
  • Estatísticas de risco
  • Exportação de relatórios

5. Datasets (2 endpoints)​

Consultar datasets disponíveis para o tenant.

6. Configuração de Relatórios (1 endpoint)​

Obter configuração de branding para relatórios PDF.

7. API Keys (3 endpoints)​

Monitoramento de API keys e estatísticas de uso.

8. REST API v1 - Integração Externa (12 endpoints)​

Endpoints para integração externa via API Key.

9. Gestão de Usuários (4 endpoints)​

Administração de usuários da plataforma:

  • GET /admin/users - Listar usuários (tenant admin vê apenas sua organização)
  • POST /admin/users/invite - Convidar novo usuário por email
  • POST /admin/users/impersonate - Impersonar usuário (platform admin)
  • POST /admin/users/reset-password - Redefinir senha de usuário (platform admin)

10. API Analytics (5 endpoints)​

Monitoramento de uso de API Keys em tempo real:

  • GET /admin/api-analytics/summary - Resumo geral (total, taxa de sucesso, tempo médio)
  • GET /admin/api-analytics/trends - Tendências diárias
  • GET /admin/api-analytics/by-key - Métricas por API Key
  • GET /admin/api-analytics/by-endpoint - Métricas por endpoint
  • GET /admin/api-analytics/recent-calls - Chamadas recentes (paginado)

11. Gestão de Provedores (6 endpoints)​

Credenciais de provedores de dados gerenciadas no banco:

  • GET /platform/providers - Listar provedores
  • GET /platform/providers/:id - Detalhes do provedor
  • POST /platform/providers - Criar provedor
  • PUT /platform/providers/:id - Atualizar provedor
  • DELETE /platform/providers/:id - Remover provedor
  • POST /platform/providers/:id/test - Testar conectividade

🚀 Início Rápido​

Quer fazer sua primeira consulta em 5 minutos?

→ Guia de Início Rápido

📦 Postman Collection​

Disponibilizamos uma collection completa do Postman com todos os endpoints configurados:

Localização: postman/Lucent_KYC_Tenant_User.postman_collection.json no repositório

Como usar:

  1. Importe a collection no Postman
  2. Configure as variáveis de ambiente (BASE_URL, JWT_TOKEN)
  3. Faça sua primeira consulta

→ Guia de Setup do Postman

📖 Guias Complementares​

🔍 Recursos Adicionais​

⚠️ Notas Importantes​

Autorização de Datasets

Todos os endpoints de consulta validam automaticamente os datasets contra a tabela tenant_datasets. Apenas datasets habilitados para o tenant serão consultados.

Modo Mock

Use useMockData: true nos endpoints de consulta para testar sem consumir créditos dos provedores de dados.

Rate Limiting
  • JWT: 100 requisições por minuto por usuário
  • API Key: 100 requisições por minuto por chave
  • Consultas em lote (/kyc/batch) contam como 1 requisição

🔄 Versionamento​

Versão Atual: v1

A API segue semantic versioning. Mudanças breaking serão comunicadas com antecedência e terão suporte de migração.

📊 Status da API​

Monitore o status da API em tempo real:

curl https://api.lucent-kyc.com/api/health

Pronto para começar? Siga o Guia de Início Rápido ou explore as categorias da API acima.