Como integrar validação de CPF em apps Bubble.io (no-code)

Para integrar validação de CPF em apps Bubble.io, instale o plugin API Connector, configure a chamada GET para https://api.cpfhub.io/cpf/[cpf] com a chave de API no header, e crie um workflow visual que exibe nome e data de nascimento automaticamente após a consulta — sem escrever uma linha de código.

Introdução

O Bubble.io é uma das plataformas no-code mais completas do mercado, permitindo a criação de aplicações web complexas sem escrever uma única linha de código. Milhares de startups e empresas brasileiras utilizam o Bubble para construir MVPs, marketplaces, CRMs e plataformas de gestão. Em muitos desses projetos, a validação de CPF é uma necessidade -- seja no cadastro de usuários, na emissão de notas fiscais ou na prevenção de fraudes.

Pré-requisitos

Antes de iniciar a integração, você precisará de:

• Conta no Bubble.io -- Plano gratuito ou pago (o API Connector está disponível em todos os planos).

• Conta no CPFHub.io -- Crie uma conta gratuita em cpfhub.io

• Chave de API -- Gere sua x-api-key no painel de controle (app.cpfhub.io).

O plano gratuito do CPFHub.io oferece 50 consultas por mês, ideal para desenvolvimento e testes no Bubble.

Entendendo a API do CPFHub.io

Para referência, a chamada à API que vamos configurar no Bubble:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

Resposta:

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

Passo 1: instalar o API Connector

O API Connector é o plugin oficial do Bubble para integração com APIs externas.

1. No editor do Bubble, acesse a aba "Plugins".
2. Clique em "Add plugins".
3. Busque por "API Connector".
4. Instale o plugin (é gratuito).

Passo 2: configurar a chamada à API

Após instalar o API Connector, configure a chamada:

1. Acesse a aba "Plugins" e clique no API Connector instalado.
2. Clique em "Add another API".
3. Nomeie a API como "CPFHub".
4. Em "Authentication", selecione "Private key in header".
5. No campo "Key name", insira: x-api-key
6. No campo "Key value", insira sua chave de API do CPFHub.io.

Configurando o endpoint

1. Clique em "Add another call".
2. Nomeie a chamada como "Consultar CPF".
3. Selecione o método: GET.
4. No campo URL, insira: https://api.cpfhub.io/cpf/[cpf]
5. O parâmetro [cpf] entre colchetes indica que é dinâmico.

Headers adicionais

Adicione o header:

• Key: Accept
• Value: application/json

Configurando o parâmetro dinâmico

1. Na seção de parâmetros, o Bubble deve reconhecer automaticamente o parâmetro "cpf".
2. Marque-o como "Não privado" para que possa ser preenchido pelo workflow.
3. Insira um valor de teste (por exemplo, 12345678900).

Inicializando a chamada

1. Clique em "Initialize call".
2. Se a configuração estiver correta, o Bubble exibirá a resposta JSON.
3. O Bubble mapeará automaticamente os campos da resposta.
4. Confirme o mapeamento e salve.

Passo 3: criar o formulário no Bubble

No editor visual do Bubble, crie os seguintes elementos:

Elementos da página

• Input CPF -- Um campo de texto para o usuário digitar o CPF. Defina o placeholder como "000.000.000-00".

• Botão Validar -- Um botão que disparará o workflow de validação.

• Grupo de Resultado -- Um grupo que será exibido somente quando houver resultado. Dentro dele, adicione textos para exibir nome, data de nascimento e gênero.

• Texto de Erro -- Um texto que será exibido quando a validação falhar.

Passo 4: configurar o workflow de validação

1. Selecione o botão "Validar" e acesse a aba "Workflow".
2. Adicione a ação: "Plugins > CPFHub - Consultar CPF".
3. No parâmetro "cpf", use uma expressão para limpar o CPF digitado:

Para remover pontos e traço do CPF, use a fórmula do Bubble:

• Input CPF's value:find & replace (regex pattern: \D, replacement: "")

1. Armazene o resultado em um custom state ou exiba diretamente nos elementos.

Exibindo o resultado

Após a chamada da API, adicione ações condicionais:

• Se "Result's success is yes" -- Mostrar o grupo de resultado com os dados do titular.
• Se "Result's success is no" -- Mostrar a mensagem de erro.

Mapeamento dos campos

• Nome: Result's data's name
• Data de nascimento: Result's data's birthDate
• Gênero: Result's data's gender

Passo 5: adicionar máscara de CPF

O Bubble permite adicionar formatação ao campo de CPF usando plugins de máscara ou condicionais.

Opção 1: Plugin de máscara

Instale o plugin "Input Mask" e configure o padrão: 000.000.000-00

Opção 2: Regex no workflow

Antes de enviar à API, aplique a limpeza do CPF no workflow usando find & replace com regex para remover caracteres não numéricos.

Casos de uso no Bubble

Cadastro de usuários

Valide o CPF no momento do registro para garantir que cada conta está vinculada a uma pessoa real. Use o resultado da API para preencher automaticamente o nome do usuário.

Marketplace

Em marketplaces construídos no Bubble, valide o CPF de vendedores e compradores para prevenção de fraudes e conformidade fiscal.

CRM personalizado

Em CRMs no-code, valide o CPF de clientes no momento do cadastro para manter a base de dados limpa e atualizada.

Plataforma de eventos

Valide o CPF dos participantes para emissão de certificados e notas fiscais.

Boas práticas

Validação local antes da API

Antes de chamar a API, verifique no workflow se o CPF tem 11 dígitos. Isso evita consultas desnecessárias e preserva a cota do plano gratuito.

Tratamento de erros

Configure workflows para tratar:

• CPF com menos de 11 dígitos -- Exibir mensagem antes de chamar a API.
• API indisponível -- Exibir mensagem de erro e permitir que o usuário prossiga (graceful degradation).
• Rate limit excedido -- Informar o usuário para tentar novamente em alguns segundos.

Cache de resultados

Se o mesmo CPF pode ser consultado várias vezes (por exemplo, em um CRM), armazene o resultado no banco de dados do Bubble com um timestamp e reutilize-o por um período definido.

Segurança

A chave de API é configurada como "Private" no API Connector, o que significa que ela nunca é exposta no frontend. O Bubble faz a requisição do lado do servidor, protegendo sua chave.

Planos recomendados

Perguntas frequentes

O API Connector do Bubble expõe minha chave de API no frontend?

Não. Quando você configura a chave como "Private key in header" no API Connector, o Bubble realiza a chamada do lado do servidor, nunca expondo o valor no código que chega ao navegador do usuário. Isso é suficiente para proteger a chave em apps Bubble, sem necessidade de um proxy externo adicional.

Como lidar com o CPF mascarado (formato 000.000.000-00) antes de enviar à API?

No workflow do Bubble, antes de chamar a API, aplique a expressão Input CPF's value:find & replace com o padrão regex \D e substituição vazia. Isso remove todos os caracteres não numéricos e envia apenas os 11 dígitos para a API. Alternativamente, instale o plugin "Input Mask" para formatar o campo enquanto o usuário digita.

Posso armazenar o retorno da API de CPF no banco de dados do Bubble?

Sim, mas armazene apenas o necessário: nome, data de nascimento e o resultado da validação são suficientes para a maioria dos casos de uso. Evite salvar o número de CPF em texto simples — prefira um hash ou token de referência. Documente o propósito do armazenamento na política de privacidade do seu app, conforme exigido pela LGPD e orientações da ANPD.

Quais casos de uso no Bubble se beneficiam mais da validação de CPF?

Marketplaces (verificar vendedores e compradores), plataformas de eventos (emissão de certificados e notas fiscais), CRMs (qualidade da base de clientes) e aplicações de crédito ou serviços financeiros são os casos com maior retorno. Em qualquer cenário onde a identidade do usuário importa para operações fiscais, legais ou de prevenção a fraudes, a validação de CPF no cadastro elimina retrabalho posterior.

Conclusão

Integrar validação de CPF em aplicações Bubble.io é um processo visual e acessível, mesmo para quem não tem experiência com programação. O API Connector do Bubble, combinado com a API REST do CPFHub.io, permite implementar validação de CPF em minutos, com segurança e conformidade LGPD. O plano gratuito com 50 consultas mensais é perfeito para desenvolvimento, e a escalabilidade dos planos pagos acompanha o crescimento da sua aplicação no-code.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF ao seu app Bubble.io hoje mesmo.