Consultas de Crédito

Acesse informações abrangentes para análise de crédito através de diferentes tipos de consulta.

Visão Geral

A API permite consultar informações de pessoas através do CPF:

Chave	Descrição	Formato
cpf	CPF da pessoa	11 dígitos (com ou sem formatação)

Tipos de Consulta Disponíveis

📄 Dados CPF

Informações básicas da Receita Federal como nome, situação e data de nascimento.

💰 Score de Crédito

Análise de risco creditício atualizada com principais bureaus.

🏢 Relacionamentos

Vínculos empresariais, societários e participações em empresas.

📊 Dados da Receita

Informações fiscais e tributárias disponíveis.

Consulta de CPF

Endpoint

POST /queries/integration/:slug

Use o slug consulta-cpf para realizar consultas de pessoa física.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
slug	path	✅	Slug do template de consulta (ex: consulta-cpf)
keys	body	✅	Objeto com as chaves de busca

Exemplo de Requisição

curl -X POST "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/consulta-cpf" \
  -H "x-api-key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": {
      "cpf": "12345678901"
    }
  }'

JavaScript

const response = await fetch('https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/consulta-cpf', {
  method: 'POST',
  headers: {
    'x-api-key': 'sua_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    keys: { cpf: '12345678901' }
  })
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/consulta-cpf"
headers = {
    "x-api-key": "sua_api_key",
    "Content-Type": "application/json"
}

response = requests.post(
    url,
    headers=headers,
    json={'keys': {'cpf': '12345678901'}}
)

data = response.json()
print(data)

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/consulta-cpf",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: sua_api_key",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'keys' => ['cpf' => '12345678901']
    ])
]);

$response = curl_exec($curl);
$data = json_decode($response, true);
curl_close($curl);

print_r($data);

Resposta

{
  "statusCode": 201,
  "body": {
    "queryId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED"
  }
}

Obter Resultado da Consulta

Use o queryId para buscar os dados completos:

curl -X GET "https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo/queries/integration/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sua_api_key"

Resposta Completa

{
  "statusCode": 200,
  "body": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:30:08Z",
    "template": {
      "slug": "consulta-cpf",
      "name": "Consulta CPF"
    },
    "keys": {
      "cpf": "12345678901"
    },
    "data": {
      "cpf": "123.456.789-01",
      "nome": "JOÃO DA SILVA SANTOS",
      "dataNascimento": "1985-03-15",
      "situacao": "REGULAR",
      "situacaoDescricao": "Situação regular na Receita Federal",
      "ultimaAtualizacao": "2023-12-01",
      "genero": "M",
      "faixaEtaria": "35-40"
    }
  }
}

Campos da Resposta

Campo	Tipo	Descrição
cpf	string	CPF consultado (formatado)
nome	string	Nome completo
dataNascimento	string	Data de nascimento (YYYY-MM-DD)
situacao	string	Situação na Receita Federal
situacaoDescricao	string	Descrição da situação
ultimaAtualizacao	string	Data da última atualização RFB
genero	string	Gênero inferido (M/F/N)
faixaEtaria	string	Faixa etária calculada

Situações Possíveis

Situação	Descrição
REGULAR	CPF em situação regular
PENDENTE	Pendências na Receita Federal
CANCELADO	CPF cancelado
NULO	CPF considerado nulo
SUSPENSO	Situação suspensa

Tratamento de Erros

Erros Comuns

Código	Erro	Causa	Solução
400	INVALID_CPF	CPF em formato inválido	Verifique se são 11 dígitos válidos
400	MISSING_REQUIRED_KEY	Chave CPF ausente	Inclua o CPF no body
402	INSUFFICIENT_BALANCE	Saldo insuficiente	Adicione créditos
404	PERSON_NOT_FOUND	Pessoa não encontrada	Verifique o CPF informado
503	SOURCE_UNAVAILABLE	Fonte indisponível	Tente novamente em alguns minutos

Exemplo de Erro

{
  "statusCode": 400,
  "error": {
    "code": "INVALID_CPF",
    "message": "CPF inválido ou mal formatado",
    "details": {
      "field": "keys.cpf",
      "received": "123456789",
      "expected": "11 dígitos válidos"
    }
  }
}

Compliance e LGPD

Uso Responsável

Esta consulta deve ser utilizada apenas para fins legítimos e com consentimento do titular dos dados, conforme LGPD e regulamentações aplicáveis.

• ✅ Consulta autorizada apenas para fins legítimos
• ✅ Dados da Receita Federal (fonte oficial)
• ✅ Log auditável de todas as consultas
• ✅ Conformidade com regulamentações

Boas Práticas

1. Validar CPF localmente: Verifique o formato e dígito verificador antes de enviar
2. Obter consentimento: Certifique-se de ter autorização do titular
3. Cache responsável: Respeite a validade dos dados

Exemplo de Integração

Node.js com TypeScript

import axios from 'axios';

interface PersonQueryKeys {
  cpf: string;
}

interface PersonQueryResult {
  queryId: string;
  status: 'COMPLETED' | 'PROCESSING' | 'FAILED';
}

interface PersonData {
  cpf: string;
  nome: string;
  dataNascimento: string;
  situacao: string;
  situacaoDescricao: string;
  genero: string;
  faixaEtaria: string;
}

class ChecktudoPersonClient {
  private baseUrl = 'https://pwe6qnayhg.execute-api.sa-east-1.amazonaws.com/checktudo';
  
  constructor(private apiKey: string) {}

  async queryPerson(cpf: string): Promise<PersonQueryResult> {
    const response = await axios.post(
      `${this.baseUrl}/queries/integration/consulta-cpf`,
      { keys: { cpf } },
      {
        headers: {
          'x-api-key': this.apiKey,
          'Content-Type': 'application/json',
        },
      }
    );
    return response.data.body;
  }

  async getPersonResult(queryId: string): Promise<PersonData> {
    const response = await axios.get(
      `${this.baseUrl}/queries/integration/${queryId}`,
      {
        headers: { 'x-api-key': this.apiKey },
      }
    );
    return response.data.body.data;
  }
}

// Uso
const client = new ChecktudoPersonClient('sua_api_key');

async function main() {
  const { queryId } = await client.queryPerson('12345678901');
  const result = await client.getPersonResult(queryId);
  console.log('Dados da pessoa:', result);
}

main();

Próximos Passos

• Consultas Veiculares
• Tratamento de Erros
• Limitações da API