Guia de Início Rápido

Faça sua primeira consulta KYC em 5 minutos! Este guia mostra como configurar e fazer sua primeira chamada à API Lucent KYC usando o Postman.

🎯 Objetivo

Ao final deste guia, você terá:

• ✅ Postman configurado com a collection completa
• ✅ Token JWT obtido e configurado
• ✅ Primeira consulta CPF realizada com sucesso
• ✅ Avaliação de risco visualizada

📋 Pré-requisitos

• Postman instalado
• Acesso ao Lucent KYC (usuário e senha)
• Usuário associado a um tenant válido

Passo 1: Importar a Postman Collection

1.1 Baixar a Collection

A collection está disponível no repositório do projeto:

Localização: postman/Lucent_KYC_Tenant_User.postman_collection.json

GitHub: lucent-kyc/postman

1.2 Importar no Postman

1. Abra o Postman
2. Clique em Import (canto superior esquerdo)
3. Selecione o arquivo Lucent_KYC_Tenant_User.postman_collection.json
4. Clique em Import

Você verá a collection "Lucent KYC - Tenant User APIs" na barra lateral.

Passo 2: Configurar Variáveis

2.1 Variáveis Disponíveis

A collection já vem com variáveis pré-configuradas:

Variável	Valor Padrão	Descrição
BASE_URL	http://localhost:3000/api	URL base da API
JWT_TOKEN	(vazio)	Token JWT para autenticação
API_KEY	(vazio)	API Key para endpoints v1
CPF_NUMBER	12345678901	CPF de exemplo
CNPJ_NUMBER	12345678000195	CNPJ de exemplo

2.2 Atualizar BASE_URL

Se estiver usando um ambiente diferente do local:

1. Clique na collection "Lucent KYC - Tenant User APIs"
2. Vá na aba Variables
3. Atualize BASE_URL:
   • Desenvolvimento: http://localhost:3000/api
   • Produção: https://api.lucent-kyc.com/api
4. Clique em Save

Passo 3: Obter Token JWT

3.1 Login via Interface Web (Mais Fácil)

1. Acesse a interface web do Lucent KYC
2. Faça login com seu usuário e senha
3. Abra o DevTools do navegador (F12)
4. Vá na aba Console
5. Digite e execute:

// Obter token JWT do Supabase
const session = JSON.parse(localStorage.getItem('sb-[SEU_PROJETO_ID]-auth-token'));
console.log('Token JWT:', session.access_token);

6. Copie o token que apareceu no console

3.2 Login via Supabase API (Alternativo)

Se preferir obter o token via API:

1. No Postman, crie uma nova requisição
2. Configure:
   • Método: POST
   • URL: https://[SEU_PROJETO].supabase.co/auth/v1/token?grant_type=password
   • Headers:
     • apikey: [SUA_SUPABASE_ANON_KEY]
     • Content-Type: application/json
   • Body (raw JSON):

{
  "email": "seu-email@exemplo.com",
  "password": "sua-senha"
}

3. Envie a requisição
4. Na resposta, copie o valor de access_token

3.3 Configurar Token no Postman

1. Volte para a collection "Lucent KYC - Tenant User APIs"
2. Vá na aba Variables
3. Cole o token copiado em JWT_TOKEN (coluna "Current Value")
4. Clique em Save

Token Expirado?

Tokens JWT expiram após 1 hora. Se receber erro 401, repita este passo para obter um novo token.

Passo 4: Fazer sua Primeira Consulta

4.1 Testar com Modo Mock (Recomendado)

Vamos começar com uma consulta mock para não consumir créditos:

1. Na collection, expanda "KYC Queries - Web UI"
2. Clique em "Query CPF"
3. Na aba Body, você verá:

{
  "cpf": "{{CPF_NUMBER}}",
  "datasets": "basic,processes,vehicles",
  "useMockData": false
}

4. Altere useMockData para true:

{
  "cpf": "{{CPF_NUMBER}}",
  "datasets": "basic,processes,vehicles",
  "useMockData": true
}

5. Clique em Send

4.2 Interpretar a Resposta

Se tudo deu certo, você receberá uma resposta com status 200 OK:

{
  "query": {
    "id": "uuid-da-consulta",
    "document_type": "cpf",
    "document_number": "12345678901",
    "status": "completed",
    "created_at": "2025-01-09T10:30:00Z"
  },
  "data": {
    "BasicData": {
      "Nome": "João da Silva",
      "CPF": "12345678901",
      "Situacao": "REGULAR"
    },
    // ... outros dados
  },
  "riskAssessment": {
    "overallScore": 25,
    "overallLevel": "low",
    "appliedRules": [
      {
        "ruleId": "cpf_status_check",
        "triggered": true,
        "weight": 10
      }
    ],
    "riskFactors": [
      {
        "description": "CPF regular na Receita Federal",
        "points": 0,
        "severity": "info"
      }
    ]
  },
  "llmEvaluation": {
    "summary": "Perfil de risco baixo. CPF regular sem restrições.",
    "recommendations": ["Aprovar para transações de baixo valor"]
  }
}

Principais Campos:

• query.id: ID único da consulta (salvo automaticamente em QUERY_ID)
• riskAssessment.overallLevel: Nível de risco (very_low, low, moderate, high, rejected)
• riskAssessment.overallScore: Pontuação de risco (0-100)
• riskAssessment.appliedRules: Regras que foram acionadas
• llmEvaluation: Análise gerada por IA (se habilitado)

4.3 Consulta Real (Consume Créditos)

Quando estiver pronto para fazer uma consulta real:

1. Volte ao endpoint "Query CPF"
2. Altere useMockData para false:

{
  "cpf": "12345678901",  // Use um CPF real válido
  "datasets": "basic,processes",
  "useMockData": false
}

3. Clique em Send

Consumo de Créditos

Consultas reais consomem créditos dos provedores de dados conforme os datasets solicitados. Use mock mode para testes.

Passo 5: Explorar Outros Endpoints

Agora que você fez sua primeira consulta, explore outros endpoints:

Consultar CNPJ

1. Expanda "KYC Queries - Web UI"
2. Clique em "Query CNPJ"
3. Envie a requisição (já configurada com variáveis)

Ver Perfis Unificados

1. Expanda "Profile Management"
2. Clique em "List CPF Profiles"
3. Envie para ver todos os perfis CPF do seu tenant

Ver Histórico de Riscos

1. Expanda "Risk Assessment"
2. Clique em "List Risk Assessments"
3. Adicione filtro ?riskLevel=high na URL para ver apenas alto risco

📊 Variáveis Automáticas

A collection salva automaticamente IDs importantes:

Após consultar CPF/CNPJ:

• QUERY_ID é atualizado automaticamente
• Use em outros endpoints que precisam de {{QUERY_ID}}

Exemplo: Ver detalhes de risco da última consulta:

1. Vá em Risk Assessment > Get Risk Assessment Details
2. A URL já usa {{QUERY_ID}} automaticamente
3. Envie para ver detalhes completos

🚨 Troubleshooting

Erro 401 - Unauthorized

Causa: Token JWT inválido ou expirado

Solução:

1. Obtenha um novo token (Passo 3)
2. Atualize a variável JWT_TOKEN
3. Tente novamente

Erro 403 - Forbidden

Causa: Usuário sem acesso a tenant ou dataset não autorizado

Solução:

1. Verifique se seu usuário está associado a um tenant
2. Confirme que os datasets solicitados estão habilitados para o tenant
3. Contate o administrador se necessário

Erro 422 - Validation Error

Causa: Formato de CPF/CNPJ inválido ou parâmetros incorretos

Solução:

1. Verifique o formato do documento (11 dígitos para CPF, 14 para CNPJ)
2. Confirme que todos os campos obrigatórios estão presentes
3. Veja a mensagem de erro detalhada na resposta

🎓 Próximos Passos

Agora que você já sabe o básico, explore:

1. Entenda a Autenticação Completa

→ Guia de Autenticação - JWT, API Keys, Postman setup detalhado

2. Aprenda sobre Tratamento de Erros

→ Tratamento de Erros - Todos os códigos de erro e como lidar com eles

3. Integre em Seu Sistema

→ Documentação da API - Referência completa de todos os endpoints

4. Siga Melhores Práticas

→ Melhores Práticas - Segurança, performance, rate limiting

5. Use REST API v1 para Integração Externa

→ REST API v1 - Endpoints com autenticação por API Key

💡 Dicas Rápidas

✨ Organize seus testes:

• Crie Environments no Postman para dev/staging/prod
• Use Collections separadas para diferentes fluxos

🔄 Automatize workflows:

• Configure Tests nas requisições para validação automática
• Use Collection Runner para executar múltiplas requisições

📝 Documente sua integração:

• Use Examples no Postman para documentar casos de uso
• Compartilhe a collection com sua equipe

🚀 Performance:

• Use o endpoint /kyc/batch para múltiplas consultas
• Cache perfis para evitar consultas repetidas

---

Parabéns! 🎉 Você completou o guia de início rápido. Agora você está pronto para integrar o Lucent KYC em seus sistemas.

Precisa de ajuda? Entre em contato: suporte@lucentminds.com