Consultas KYC - Web UI

Endpoints para consultar dados de CPF e CNPJ via provedores de dados (BigDataCorp, Google, Serviços Lucent Minds) com avaliação de risco automatizada.

Visão Geral

Estes endpoints são utilizados pela interface web e permitem:

📋 Consultas individuais de CPF e CNPJ
🧪 Modo mock para testes sem consumir créditos
🔄 Processamento em lote com controle de concorrência
⏰ Identificação de perfis expirados para recertificação

Autenticação: JWT Bearer token

Base URL: /api/kyc

Endpoints

POST /kyc/cpf

Consulta dados de CPF via provedores de dados com avaliação de risco automática.

Autenticação: Authorization: Bearer {JWT_TOKEN}

Parâmetros de Requisição:

Parâmetro	Tipo	Obrigatório	Descrição
cpf	string	✅ Sim	CPF (11 dígitos, com ou sem formatação)
datasets	string	✅ Sim	Lista de datasets separados por vírgula (ex: "basic,processes,vehicles")
useMockData	boolean	❌ Não	`true` para usar dados mock (testes sem API externa)

Exemplo de Requisição:

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

Exemplo de Resposta:

{
  "query": {
    "id": "uuid-da-consulta",
    "document_type": "cpf",
    "document_number": "12345678901",
    "datasets": "basic,processes,vehicles",
    "created_at": "2025-01-09T10:30:00Z",
    "status": "completed"
  },
  "data": {
    "BasicData": {
      "Nome": "João da Silva",
      "CPF": "12345678901",
      "Situacao": "REGULAR"
    },
    "Processes": [...],
    "Vehicles": [...]
  },
  "riskAssessment": {
    "overallScore": 25,
    "overallLevel": "low",
    "appliedRules": [
      {
        "ruleId": "cpf_status_check",
        "category": "document_validation",
        "weight": 10,
        "triggered": true
      }
    ],
    "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"]
  }
}

Efeitos Colaterais:

✅ Cria registro de query no banco de dados
✅ Incrementa contadores de uso de datasets
✅ Atualiza ou cria perfil unificado de CPF (unified_cpf_profiles)
✅ Calcula avaliação de risco
✅ Executa avaliação LLM (se habilitado no tenant)
✅ Define próxima data de revisão baseada no nível de risco

Códigos de Erro:

Código	Erro	Descrição
401	Unauthorized	Token JWT inválido, expirado ou ausente
403	Forbidden	Usuário sem acesso a tenant ou dataset não autorizado
422	Unprocessable Entity	Formato de CPF inválido ou parâmetros incorretos
500	Internal Server Error	Falha na API do provedor de dados ou erro interno

Modo Mock para Testes

Configure useMockData: true para testar o fluxo completo sem consumir créditos dos provedores de dados. Todos os side effects (perfil, risco, etc) funcionam normalmente com dados simulados.

Autorização de Datasets

Apenas datasets habilitados na tabela tenant_datasets serão consultados. Datasets não autorizados são automaticamente filtrados. Se todos os datasets solicitados forem não autorizados e basic_data estiver disponível, ele será usado como fallback.

Exemplos de Integração:

cURL:

curl -X POST https://api.lucent-kyc.com/api/kyc/cpf \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "12345678901",
    "datasets": "basic,processes,vehicles",
    "useMockData": false
  }'

JavaScript/TypeScript:

const queryCPF = async (cpf: string, datasets: string, token: string) => {
  const response = await fetch('https://api.lucent-kyc.com/api/kyc/cpf', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cpf,
      datasets,
      useMockData: false
    })
  });

  if (!response.ok) {
    throw new Error(`Erro ${response.status}: ${await response.text()}`);
  }

  return response.json();
};

// Uso
const result = await queryCPF('12345678901', 'basic,processes', jwtToken);
console.log('Nível de risco:', result.riskAssessment.overallLevel);

POST /kyc/cnpj

Consulta dados de CNPJ via provedores de dados com avaliação de risco automática.

Autenticação: Authorization: Bearer {JWT_TOKEN}

Parâmetros de Requisição:

Parâmetro	Tipo	Obrigatório	Descrição
cnpj	string	✅ Sim	CNPJ (14 dígitos, com ou sem formatação)
datasets	string	✅ Sim	Lista de datasets separados por vírgula (ex: "basic,partners,processes")
useMockData	boolean	❌ Não	`true` para usar dados mock

Exemplo de Requisição:

{
  "cnpj": "12345678000195",
  "datasets": "basic,partners,processes",
  "useMockData": false
}

Exemplo de Resposta: Similar ao endpoint de CPF, com dados específicos de empresa.

Efeitos Colaterais:

✅ Cria registro de query no banco
✅ Atualiza perfil unificado de CNPJ (unified_cnpj_profiles)
✅ Calcula avaliação de risco empresarial
✅ Define próxima revisão baseada em risco

cURL:

curl -X POST https://api.lucent-kyc.com/api/kyc/cnpj \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12345678000195",
    "datasets": "basic,partners,processes"
  }'

JavaScript/TypeScript:

const queryCNPJ = async (cnpj: string, datasets: string, token: string) => {
  const response = await fetch('https://api.lucent-kyc.com/api/kyc/cnpj', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ cnpj, datasets })
  });

  return response.json();
};

POST /kyc/mock

Salva consulta mock para testes sem fazer chamadas externas aos provedores de dados.

Caso de Uso: Ambientes de teste, desenvolvimento, demonstrações.

Autenticação: Authorization: Bearer {JWT_TOKEN}

Parâmetros de Requisição:

Parâmetro	Tipo	Obrigatório	Descrição
documentType	string	✅ Sim	"cpf" ou "cnpj"
documentNumber	string	✅ Sim	Número do documento
datasets	string	✅ Sim	Lista de datasets separados por vírgula
mockData	object	✅ Sim	Dados mock estruturados por dataset

Exemplo de Requisição:

{
  "documentType": "cpf",
  "documentNumber": "12345678901",
  "datasets": "basic,processes",
  "mockData": {
    "basic": {
      "Nome": "João da Silva Mock",
      "CPF": "12345678901",
      "Situacao": "REGULAR"
    },
    "processes": [
      {
        "tipo": "civil",
        "status": "ativo"
      }
    ]
  }
}

Efeitos Colaterais:

✅ Cria registro de query (mesmos fields que consulta real)
✅ Calcula avaliação de risco com dados mock
✅ Atualiza perfil unificado
❌ Não consome créditos dos provedores de dados
❌ Não faz chamadas externas

Ideal para CI/CD

Use este endpoint em testes automatizados para validar o fluxo completo sem dependências externas.

cURL:

curl -X POST https://api.lucent-kyc.com/api/kyc/mock \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "cpf",
    "documentNumber": "12345678901",
    "datasets": "basic",
    "mockData": {
      "basic": {
        "Nome": "Teste Mock",
        "CPF": "12345678901",
        "Situacao": "REGULAR"
      }
    }
  }'

POST /kyc/batch

Processa múltiplas consultas KYC em paralelo com controle de concorrência.

Autenticação: Authorization: Bearer {JWT_TOKEN}

Parâmetros de Requisição:

Parâmetro	Tipo	Obrigatório	Descrição
queries	array	✅ Sim	Array de objetos de consulta
queries[].type	string	✅ Sim	"cpf" ou "cnpj"
queries[].document	string	✅ Sim	Número do documento
queries[].datasets	string	✅ Sim	Datasets para esta consulta
useMockData	boolean	❌ Não	`true` para usar mock em todas as consultas
concurrency	number	❌ Não	Máximo de consultas paralelas (padrão: 5, máx: 10)

Exemplo de Requisição:

{
  "queries": [
    {
      "type": "cpf",
      "document": "12345678901",
      "datasets": "basic,processes"
    },
    {
      "type": "cnpj",
      "document": "12345678000195",
      "datasets": "basic,partners"
    },
    {
      "type": "cpf",
      "document": "98765432100",
      "datasets": "basic,vehicles"
    }
  ],
  "useMockData": false,
  "concurrency": 3
}

Exemplo de Resposta:

{
  "results": [
    {
      "index": 0,
      "status": "success",
      "query": { "id": "uuid-1", ...  },
      "data": { ... },
      "riskAssessment": { ... }
    },
    {
      "index": 1,
      "status": "success",
      "query": { "id": "uuid-2", ... },
      "data": { ... },
      "riskAssessment": { ... }
    },
    {
      "index": 2,
      "status": "error",
      "error": "Invalid CPF format",
      "details": { ... }
    }
  ],
  "summary": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "duration_ms": 1250
  }
}

Características:

⚡ Processamento paralelo com controle de concorrência
🔄 Falhas individuais não interrompem o lote
📊 Cada resultado indexado pelo array original
⏱️ Timeout por consulta: 30 segundos

Rate Limiting

Consultas em lote contam como 1 requisição para rate limiting, não n requisições. Ideal para processamento bulk.

cURL:

curl -X POST https://api.lucent-kyc.com/api/kyc/batch \
  -H "Authorization: Bearer SEU_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"type": "cpf", "document": "12345678901", "datasets": "basic"},
      {"type": "cnpj", "document": "12345678000195", "datasets": "basic,partners"}
    ],
    "concurrency": 2
  }'

JavaScript/TypeScript:

const batchQuery = async (queries: Array<any>, token: string) => {
  const response = await fetch('https://api.lucent-kyc.com/api/kyc/batch', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      queries,
      concurrency: 5
    })
  });

  const result = await response.json();

  // Processar resultados
  result.results.forEach((item, index) => {
    if (item.status === 'success') {
      console.log(`✅ Consulta ${index}: ${item.riskAssessment.overallLevel}`);
    } else {
      console.error(`❌ Consulta ${index}: ${item.error}`);
    }
  });

  return result;
};

GET /profiles/expired

Lista perfis (CPF e CNPJ) que requerem recertificação baseada no schedule de revisão.

Autenticação: Authorization: Bearer {JWT_TOKEN}

Parâmetros de Consulta: Nenhum

Resposta:

{
  "cpf_profiles": [
    {
      "id": "uuid-perfil-1",
      "cpf": "12345678901",
      "name": "João da Silva",
      "current_risk_level": "high",
      "next_review_date": "2025-01-01",
      "days_overdue": 8,
      "last_query_date": "2024-10-05"
    }
  ],
  "cnpj_profiles": [
    {
      "id": "uuid-perfil-2",
      "cnpj": "12345678000195",
      "name": "Empresa ABC Ltda",
      "current_risk_level": "moderate",
      "next_review_date": "2025-01-05",
      "days_overdue": 4,
      "last_query_date": "2024-07-10"
    }
  ],
  "summary": {
    "total_expired": 2,
    "cpf_count": 1,
    "cnpj_count": 1
  }
}

Caso de Uso:

📊 Dashboards de compliance
🔔 Alertas de recertificação
🤖 Workflows automatizados de revisão

Schedule de Revisão Baseado em Risco:

Nível de Risco	Período de Revisão
very_low	365 dias (1 ano)
low	365 dias (1 ano)
moderate	180 dias (6 meses)
high	90 dias (3 meses)
rejected	30 dias (1 mês)

cURL:

curl -X GET https://api.lucent-kyc.com/api/profiles/expired \
  -H "Authorization: Bearer SEU_JWT_TOKEN"

JavaScript/TypeScript:

const getExpiredProfiles = async (token: string) => {
  const response = await fetch('https://api.lucent-kyc.com/api/profiles/expired', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  const data = await response.json();

  // Alertar sobre perfis expirados
  if (data.summary.total_expired > 0) {
    console.warn(`⚠️ ${data.summary.total_expired} perfis precisam de recertificação`);
  }

  return data;
};

🔗 Próximos Passos

Gestão de Perfis - Ver histórico e detalhes de perfis
Avaliação de Risco - Entender cálculos de risco
REST API v1 - Endpoints para integração externa
Guia de Início Rápido - Tutorial completo

Visão Geral​

Endpoints​

POST /kyc/cpf​

POST /kyc/cnpj​

POST /kyc/mock​

POST /kyc/batch​

GET /profiles/expired​

🔗 Próximos Passos​

Visão Geral

Endpoints

POST /kyc/cpf

POST /kyc/cnpj

POST /kyc/mock

POST /kyc/batch

GET /profiles/expired

🔗 Próximos Passos