# Como integrar API de CPF em sistemas Salesforce

> Aprenda a integrar a API de consulta de CPF do CPFHub.io no Salesforce usando Apex, Named Credentials e Lightning Web Components.

**Publicado:** 17/07/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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](https://www.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
4. 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)
4. Salve.

---

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

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

```java
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

```javascript
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

```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
<?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

| Cenário Salesforce | Plano CPFHub.io | Consultas/mês |
| --- | --- | --- |
| Sandbox / Desenvolvimento | Grátis (R$ 0) | 50 |
| Produção (equipe pequena) | Pro (R$ 149/mês) | 1.000 |
| Produção (grande volume) | Corporativo | Personalizado |

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

### Leia também

- [Como consumir API de CPF em n8n para automações self-hosted](https://cpfhub.io/blog/como-consumir-api-cpf-n8n-automacoes-self-hosted)
- [Como consumir API de CPF em Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)

---

## 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](https://www.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.