Como consumir API de CPF em Retool para dashboards internos

Consumir a API de CPF da CPFHub.io no Retool permite que equipes de operações, compliance e suporte consultem dados cadastrais diretamente em dashboards internos, sem depender do time de engenharia. A integração leva menos de 30 minutos: basta criar um Resource REST API apontando para https://api.cpfhub.io com o header x-api-key, e montar os componentes visuais para exibir nome, gênero e data de nascimento retornados pela API.

Introdução

O Retool é uma das plataformas mais populares para construção de ferramentas internas e dashboards. Equipes de operações, compliance e suporte frequentemente precisam consultar dados de CPF de forma rápida sem depender do time de engenharia para cada nova funcionalidade.

1. Por que usar Retool para consulta de CPF

• Sem código backend -- Equipes não técnicas podem consultar CPFs diretamente pelo dashboard.

• Interface visual -- Tabelas, formulários e componentes prontos para exibir dados.

• Controle de acesso -- Permissões granulares para definir quem pode consultar.

• Auditoria -- Logs automáticos de todas as consultas realizadas no Retool.

2. Configure o resource da API no Retool

No Retool, acesse Resources e crie um novo recurso do tipo REST API:

• Name -- CPFHub API

• Base URL -- https://api.cpfhub.io

• Headers -- Adicione um header padrão:

• Key: x-api-key
• Value: SUA_CHAVE_DE_API

• Headers -- Adicione outro header:

• Key: Accept
• Value: application/json

Salve o recurso. Ele ficará disponível para todas as queries do aplicativo.

3. Crie a query de consulta

Dentro do seu aplicativo Retool, crie uma nova Query com as seguintes configurações:

• Resource -- CPFHub API

• Action Type -- GET

• URL Path -- /cpf/{{ textInput1.value }}

• Timeout -- 5000 (5 segundos)

O campo textInput1.value referencia o componente de input onde o usuário digitará o CPF. A query será disparada sob demanda, ao clicar em um botão.

4. Monte a interface do dashboard

Adicione os seguintes componentes na tela do Retool:

4.1 Campo de entrada

Adicione um Text Input com as propriedades:

• Label -- CPF
• Placeholder -- Digite o CPF (somente números)
• Name -- textInput1

4.2 Botão de consulta

Adicione um Button com:

• Label -- Consultar CPF
• Event Handler -- On click, execute a query criada no passo anterior.

4.3 Exibição dos resultados

Adicione um componente JSON Viewer ou Key-Value apontando para {{ query1.data }} para exibir a resposta completa. Para uma exibição mais refinada, use componentes Text individuais:

• Nome -- {{ query1.data.data.name }}
• CPF -- {{ query1.data.data.cpf }}
• Gênero -- {{ query1.data.data.gender }}
• Data de nascimento -- {{ query1.data.data.birthDate }}

5. Exemplo com JavaScript query

Para maior controle, você pode usar uma JavaScript Query no Retool:

const cpf = textInput1.value.replace(/\D/g, '');

if (cpf.length !== 11) {
    return { error: 'CPF deve conter 11 dígitos' };
}

const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(5000)
});

if (!response.ok) {
    const status = response.status;
    if (status === 401) return { error: 'Chave de API inválida.' };
    return { error: `Erro na consulta: HTTP ${status}` };
}

const data = await response.json();
return data;

6. Exemplo de resposta da API

Ao consultar um CPF válido, a resposta retornada pela CPFHub.io segue o formato JSON abaixo, com nome completo, gênero e data de nascimento do titular:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

7. Consulta em lote com tabela

Para cenários em que a equipe precisa validar vários CPFs, adicione uma Table com uma coluna de CPFs e um botão por linha que executa a query. Use um Transformer para agregar os resultados:

const cpfs = table1.selectedRow.cpf;
const cpfLimpo = cpfs.replace(/\D/g, '');

const response = await fetch(`https://api.cpfhub.io/cpf/${cpfLimpo}`, {
    method: 'GET',
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: AbortSignal.timeout(5000)
});

return await response.json();

Lembre-se de respeitar os limites do plano contratado: o plano Gratuito oferece 50 consultas mensais e o plano Pro oferece 1.000. Consultas excedentes são cobradas a R$0,15 cada — a API nunca bloqueia.

8. Boas práticas no Retool

• Segurança -- Armazene a chave de API como variável de ambiente do Retool (Environment Variables), nunca diretamente nas queries.

• Timeout -- Configure timeout de 5 segundos nas queries para evitar travamentos na interface.

• Validação local -- Valide o formato do CPF (11 dígitos) antes de disparar a consulta.

• Feedback visual -- Exiba mensagens claras de carregamento e erro para o usuário ao realizar consultas.

• Permissões -- Use os controles de acesso do Retool para restringir quem pode consultar CPFs.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em cerca de 900ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

O Retool combinado com a API da CPFHub.io entrega uma solução poderosa para equipes internas que precisam consultar dados de CPF sem depender do time de engenharia — com controle de acesso, logs de auditoria e interface visual prontos para uso.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.