# Como consumir API de CPF em Retool para dashboards internos

> Aprenda a consumir a API de consulta de CPF da CPFHub.io em Retool para criar dashboards internos de validação e consulta de dados cadastrais.

**Publicado:** 15/12/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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:

```javascript
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**](https://www.cpfhub.io/) segue o formato JSON abaixo, com nome completo, gênero e data de nascimento do titular:

```json
{
 "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:

```javascript
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](https://www.gov.br/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.

### Leia também

- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## Conclusão

O Retool combinado com a API da [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.