Como integrar API de CPF em sistemas Salesforce

Para integrar a API de CPF do CPFHub.io no Salesforce, crie uma classe Apex que faz chamadas GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key, configure o domínio em Remote Site Settings e exponha a lógica via Lightning Web Component. A integração leva menos de uma hora e permite validar o CPF do titular, obter nome e data de nascimento diretamente no CRM.

Introdução

O Salesforce é o CRM mais utilizado no mundo, e no mercado brasileiro sua adoção é ampla entre empresas de todos os portes. Em processos de vendas, onboarding de clientes e gestão de leads, a validação de CPF é uma necessidade frequente. No entanto, o Salesforce não oferece validação de CPF nativa além de uma verificação básica de formato. Integrar uma API externa de consulta de CPF permite verificar se o CPF existe, obter o nome oficial do titular e enriquecer os dados do CRM.

Pré-requisitos

• Salesforce org -- Developer Edition, Sandbox ou org de produção.

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

• Permissão de administrador -- Para configurar Named Credentials e Remote Site Settings.

Passo 1: configurar Remote Site Settings

Para que o Salesforce possa fazer chamadas externas à API do CPFHub.io, é necessário adicionar o domínio na lista de sites remotos permitidos.

1. No Setup, busque por "Remote Site Settings".
2. Clique em "New Remote Site".
3. Preencha:

• Remote Site Name: CPFHub
• Remote Site URL: https://api.cpfhub.io
• Active: marcado

1. Salve.

Passo 2: configurar Named Credentials

Named Credentials é a forma recomendada pelo Salesforce para armazenar credenciais de APIs externas de forma segura.

1. No Setup, busque por "Named Credentials".
2. Clique em "New Named Credential".
3. Configure:

• Label: CPFHub API
• Name: CPFHub_API
• URL: https://api.cpfhub.io
• Identity Type: Named Principal
• Authentication Protocol: No Authentication (a autenticação será via header customizado no Apex)

1. Salve.

Passo 3: criar a classe Apex de integração

A classe Apex encapsula a lógica de chamada à API do CPFHub.io.

public class CPFHubService {

    private static final String API_KEY = 'SUA_CHAVE_DE_API';
    private static final String BASE_URL = 'https://api.cpfhub.io/cpf/';
    private static final Integer TIMEOUT_MS = 10000;

    public class CPFData {
    @AuraEnabled public String cpf;
    @AuraEnabled public String name;
    @AuraEnabled public String nameUpper;
    @AuraEnabled public String gender;
    @AuraEnabled public String birthDate;
    @AuraEnabled public Integer day;
    @AuraEnabled public Integer month;
    @AuraEnabled public Integer year;
    }

    public class CPFResponse {
    @AuraEnabled public Boolean success;
    @AuraEnabled public CPFData data;
    @AuraEnabled public String erro;
    }

    @AuraEnabled(cacheable=false)
    public static CPFResponse consultarCPF(String cpf) {
    CPFResponse resultado = new CPFResponse();

    // Limpar CPF
    String cpfLimpo = cpf.replaceAll('[^0-9]', '');

    if (cpfLimpo.length() != 11) {
    resultado.success = false;
    resultado.erro = 'CPF deve ter 11 dígitos';
    return resultado;
    }

    try {
    HttpRequest req = new HttpRequest();
    req.setEndpoint(BASE_URL + cpfLimpo);
    req.setMethod('GET');
    req.setHeader('x-api-key', API_KEY);
    req.setHeader('Accept', 'application/json');
    req.setTimeout(TIMEOUT_MS);

    Http http = new Http();
    HttpResponse res = http.send(req);

    if (res.getStatusCode() == 200) {
    Map<String, Object> jsonResponse =
    (Map<String, Object>) JSON.deserializeUntyped(res.getBody());

    Boolean apiSuccess = (Boolean) jsonResponse.get('success');

    if (apiSuccess) {
    Map<String, Object> dataMap =
    (Map<String, Object>) jsonResponse.get('data');

    CPFData dados = new CPFData();
    dados.cpf = (String) dataMap.get('cpf');
    dados.name = (String) dataMap.get('name');
    dados.nameUpper = (String) dataMap.get('nameUpper');
    dados.gender = (String) dataMap.get('gender');
    dados.birthDate = (String) dataMap.get('birthDate');
    dados.day = (Integer) dataMap.get('day');
    dados.month = (Integer) dataMap.get('month');
    dados.year = (Integer) dataMap.get('year');

    resultado.success = true;
    resultado.data = dados;
    } else {
    resultado.success = false;
    resultado.erro = 'CPF não encontrado';
    }

    } else if (res.getStatusCode() == 429) {
    resultado.success = false;
    resultado.erro = 'Rate limit excedido. Tente novamente.';

    } else if (res.getStatusCode() == 401) {
    resultado.success = false;
    resultado.erro = 'Chave de API inválida.';

    } else {
    resultado.success = false;
    resultado.erro = 'Erro HTTP: ' + res.getStatusCode();
    }

    } catch (Exception e) {
    resultado.success = false;
    resultado.erro = 'Erro na consulta: ' + e.getMessage();
    }

    return resultado;
    }
}

Passo 4: criar o Lightning Web Component (LWC)

O LWC permite que os usuários do Salesforce validem CPF diretamente na interface.

cpfValidator.js

import { LightningElement, track } from 'lwc';
import consultarCPF from '@salesforce/apex/CPFHubService.consultarCPF';

export default class CpfValidator extends LightningElement {
    @track cpf = '';
    @track resultado = null;
    @track erro = '';
    @track carregando = false;

    handleCPFChange(event) {
    this.cpf = event.target.value;
    this.resultado = null;
    this.erro = '';
    }

    async handleValidar() {
    const cpfLimpo = this.cpf.replace(/\D/g, '');

    if (cpfLimpo.length !== 11) {
    this.erro = 'CPF deve ter 11 dígitos.';
    return;
    }

    this.carregando = true;
    this.erro = '';
    this.resultado = null;

    try {
    const response = await consultarCPF({ cpf: cpfLimpo });

    if (response.success) {
    this.resultado = response.data;
    } else {
    this.erro = response.erro || 'CPF não encontrado.';
    }
    } catch (error) {
    this.erro = 'Erro ao validar CPF.';
    } finally {
    this.carregando = false;
    }
    }

    get temResultado() {
    return this.resultado !== null;
    }

    get generoFormatado() {
    if (!this.resultado) return '';
    return this.resultado.gender === 'M' ? 'Masculino' : 'Feminino';
    }
}

cpfValidator.html

<template>
    <lightning-card title="Validação de CPF" icon-name="standard:contact">
    <div class="slds-p-around_medium">
    <lightning-input
    label="CPF"
    value={cpf}
    onchange={handleCPFChange}
    placeholder="000.000.000-00"
    type="text"
    maxlength="14">
    </lightning-input>

    <div class="slds-m-top_medium">
    <lightning-button
    label={carregando ? 'Validando...' : 'Validar CPF'}
    variant="brand"
    onclick={handleValidar}
    disabled={carregando}>
    </lightning-button>
    </div>

    <template if:true={erro}>
    <div class="slds-m-top_medium slds-text-color_error">
    {erro}
    </div>
    </template>

    <template if:true={temResultado}>
    <div class="slds-m-top_medium slds-box slds-theme_success">
    <p><strong>Nome:</strong> {resultado.name}</p>
    <p><strong>Nascimento:</strong> {resultado.birthDate}</p>
    <p><strong>Gênero:</strong> {generoFormatado}</p>
    </div>
    </template>
    </div>
    </lightning-card>
</template>

cpfValidator.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>58.0</apiVersion>
    <isExposed>true</isExposed>
    <targets>
    <target>lightning__RecordPage</target>
    <target>lightning__AppPage</target>
    <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

Casos de uso no Salesforce

Cadastro de leads

Adicione o componente LWC na página de Lead para validar o CPF antes de converter o lead em conta e contato.

Onboarding de clientes

Use a validação de CPF no fluxo de abertura de conta (Account) para garantir que os dados do cliente são reais.

Oportunidades de venda

Valide o CPF do comprador durante o processo de vendas para evitar problemas na faturação.

Automação com Flow Builder

Chame a classe Apex a partir de um Flow do Salesforce para automatizar a validação de CPF em processos de negócio.

Boas práticas para Salesforce

• Custom Metadata Types -- Em vez de hardcoded no Apex, armazene a chave de API em Custom Metadata Types para facilitar a manutenção.

• Callout limits -- O Salesforce tem limite de 100 callouts por transação. Para validações em lote, use Queueable Apex.

• Test classes -- Crie mocks para a API nos testes Apex usando HttpCalloutMock.

• Error handling -- Trate todos os cenários de erro (timeout, rate limit, API indisponível) de forma amigável ao usuário.

• Governor limits -- Esteja atento aos limites de governança do Salesforce ao integrar APIs externas.

Planos recomendados

O plano gratuito do CPFHub.io inclui 50 consultas mensais sem cartão de crédito — ideal para desenvolvimento e testes em sandbox. Ao atingir o limite, a API não bloqueia as requisições: cada consulta adicional é cobrada a R$0,15, garantindo continuidade da operação sem interrupções.

Perguntas frequentes

O Salesforce suporta chamadas externas a APIs de CPF nativamente?

O Salesforce não valida CPF por padrão, mas oferece toda a infraestrutura necessária para integrar APIs externas com segurança. Usando Remote Site Settings para liberar o domínio e Named Credentials para gerenciar credenciais, a classe Apex pode fazer chamadas ao CPFHub.io sem expor a chave de API no código.

Como lidar com o limite de callouts por transação no Salesforce?

O Salesforce permite até 100 callouts por transação síncrona. Para validações em lote — como enriquecimento de leads importados em massa — use Queueable Apex ou Batch Apex, que processam os registros de forma assíncrona e respeitam os governor limits da plataforma.

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.

É possível usar a API CPFHub.io em automações do Salesforce Flow Builder?

Sim. A classe Apex anotada com @AuraEnabled pode ser chamada a partir de um Screen Flow ou Autolaunched Flow, permitindo validar CPF como parte de qualquer processo de negócio configurado no Flow Builder — desde onboarding de clientes até aprovação de oportunidades.

Conclusão

Integrar a API de consulta de CPF do CPFHub.io no Salesforce enriquece o CRM com dados verificados, melhora a qualidade dos cadastros e previne fraudes nos processos de vendas e onboarding. A implementação com Apex e Lightning Web Components é direta e segue as melhores práticas da plataforma Salesforce. O plano gratuito é ideal para desenvolvimento em sandboxes, e os planos pagos atendem operações de qualquer escala.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a enriquecer seus registros Salesforce com dados verificados de CPF hoje mesmo.