# Como integrar validação de CPF em Magento 2 com módulos customizados

> Aprenda a integrar validação de CPF em Magento 2 criando módulos customizados. Exemplos com Service Contract, Observer e API da CPFHub.io.

**Publicado:** 05/06/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-magento-2-com-modulos-customizados

---


Para integrar validação de CPF em Magento 2, crie um módulo customizado com uma classe de serviço que chama a API da CPFHub.io e um Observer que intercepta o evento `sales_order_place_before`. O módulo verifica o CPF do comprador antes de finalizar o pedido, bloqueando transações com dados inconsistentes e reduzindo chargebacks causados por fraude de identidade.

## Introdução

O **Magento 2** é uma das plataformas de e-commerce mais robustas do mercado, amplamente utilizada por lojas virtuais de médio e grande porte no Brasil. Em operações que envolvem vendas para pessoa física, a **validação de CPF** durante o checkout é fundamental para prevenir fraudes, reduzir chargebacks e garantir a correta emissão de notas fiscais.

---

## 1. Pré-requisitos

Antes de iniciar, certifique-se de ter:

* **Magento 2.4 ou superior** — Versão com suporte ativo da comunidade.

* **PHP 8.1 ou superior** — Requisito do Magento 2.4.

* **Acesso SSH ao servidor** — Para criar e registrar o módulo.

* **Conta na CPFHub.io** — Cadastre-se em [CPFHub.io](https://www.cpfhub.io/) para obter sua API key gratuita (50 consultas/mês, sem cartão de crédito).

---

## 2. Estrutura do módulo

Crie a seguinte estrutura de diretórios dentro de `app/code`:

```
app/code/CpfHub/Validation/
├── etc/
│ ├── module.xml
│ ├── adminhtml/
│ │ └── system.xml
│ └── di.xml
├── Model/
│ └── CpfValidator.php
├── Observer/
│ └── ValidateCpfBeforeOrder.php
├── registration.php
└── etc/
 └── events.xml
```

---

## 3. Registrando o módulo

Crie o arquivo de registro e a declaração do módulo:

```php
<?php
// app/code/CpfHub/Validation/registration.php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
 ComponentRegistrar::MODULE,
 'CpfHub_Validation',
 __DIR__
);
```

```xml
<!-- app/code/CpfHub/Validation/etc/module.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
 <module name="CpfHub_Validation" setup_version="1.0.0">
 <sequence>
 <module name="Magento_Checkout"/>
 </sequence>
 </module>
</config>
```

---

## 4. Configurações de sistema (Admin)

Adicione uma seção no painel administrativo para gerenciar a chave de API:

```xml
<!-- app/code/CpfHub/Validation/etc/adminhtml/system.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
 <system>
 <section id="cpfhub" translate="label" sortOrder="900" showInDefault="1">
 <label>CPFHub Validation</label>
 <tab>general</tab>
 <resource>CpfHub_Validation::config</resource>
 <group id="api" translate="label" sortOrder="10" showInDefault="1">
 <label>API Settings</label>
 <field id="enabled" translate="label" type="select" sortOrder="10" showInDefault="1">
 <label>Habilitado</label>
 <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
 </field>
 <field id="api_key" translate="label" type="obscure" sortOrder="20" showInDefault="1">
 <label>Chave de API</label>
 <backend_model>Magento\Config\Model\Config\Backend\Encrypted</backend_model>
 </field>
 </group>
 </section>
 </system>
</config>
```

---

## 5. Classe de validação (Service)

Crie a classe responsável por consultar a API da CPFHub.io:

```php
<?php
// app/code/CpfHub/Validation/Model/CpfValidator.php

namespace CpfHub\Validation\Model;

use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Framework\HTTP\Client\Curl;
use Psr\Log\LoggerInterface;

class CpfValidator
{
 private const API_BASE_URL = 'https://api.cpfhub.io/cpf/';
 private const CONFIG_ENABLED = 'cpfhub/api/enabled';
 private const CONFIG_API_KEY = 'cpfhub/api/api_key';

 private ScopeConfigInterface $scopeConfig;
 private Curl $curl;
 private LoggerInterface $logger;

 public function __construct(
 ScopeConfigInterface $scopeConfig,
 Curl $curl,
 LoggerInterface $logger
 ) {
 $this->scopeConfig = $scopeConfig;
 $this->curl = $curl;
 $this->logger = $logger;
 }

 public function isEnabled(): bool
 {
 return (bool) $this->scopeConfig->getValue(self::CONFIG_ENABLED);
 }

 public function validate(string $cpf): ?array
 {
 if (!$this->isEnabled()) {
 return null;
 }

 $cpfClean = preg_replace('/\D/', '', $cpf);
 $apiKey = $this->scopeConfig->getValue(self::CONFIG_API_KEY);
 $url = self::API_BASE_URL . $cpfClean;

 try {
 $this->curl->setHeaders([
 'x-api-key' => $apiKey,
 'Accept' => 'application/json',
 ]);
 $this->curl->setTimeout(30);
 $this->curl->get($url);

 $statusCode = $this->curl->getStatus();
 $body = $this->curl->getBody();
 $data = json_decode($body, true);

 if ($statusCode === 200 && isset($data['success']) && $data['success']) {
 return $data['data'];
 }

 $this->logger->warning('CPFHub: Consulta sem sucesso', [
 'cpf' => $cpfClean,
 'status' => $statusCode,
 ]);

 return null;
 } catch (\Exception $e) {
 $this->logger->error('CPFHub: Erro na requisição', [
 'message' => $e->getMessage(),
 ]);
 return null;
 }
 }
}
```

---

## 6. Observer para validação no checkout

Crie um Observer que valida o CPF antes da finalização do pedido:

```xml
<!-- app/code/CpfHub/Validation/etc/events.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
 <event name="sales_order_place_before">
 <observer name="cpfhub_validate_cpf" instance="CpfHub\Validation\Observer\ValidateCpfBeforeOrder" />
 </event>
</config>
```

```php
<?php
// app/code/CpfHub/Validation/Observer/ValidateCpfBeforeOrder.php

namespace CpfHub\Validation\Observer;

use CpfHub\Validation\Model\CpfValidator;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\Exception\LocalizedException;

class ValidateCpfBeforeOrder implements ObserverInterface
{
 private CpfValidator $cpfValidator;

 public function __construct(CpfValidator $cpfValidator)
 {
 $this->cpfValidator = $cpfValidator;
 }

 public function execute(Observer $observer): void
 {
 if (!$this->cpfValidator->isEnabled()) {
 return;
 }

 $order = $observer->getEvent()->getOrder();
 $cpf = $order->getCustomerTaxvat();

 if (empty($cpf)) {
 throw new LocalizedException(__('O CPF é obrigatório para finalizar o pedido.'));
 }

 $dados = $this->cpfValidator->validate($cpf);

 if ($dados === null) {
 throw new LocalizedException(
 __('Não foi possível validar o CPF informado. Verifique e tente novamente.')
 );
 }
 }
}
```

---

## 7. Exemplo de resposta da API

A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna um JSON estruturado com os dados do titular:

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

* **success** — Indica se a consulta foi realizada com sucesso.
* **name** — Nome completo do titular do CPF.
* **nameUpper** — Nome em letras maiúsculas, útil para comparação com dados do pedido.
* **gender** — Gênero do titular (M ou F).
* **birthDate** — Data de nascimento completa.
* **day, month, year** — Componentes da data separados.

---

## 8. Testando com cURL

Para verificar se a integração está funcionando antes de implantar o módulo, teste diretamente via cURL:

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

---

## 9. Ativando o módulo

Após criar todos os arquivos, ative o módulo com os seguintes comandos:

```bash
php bin/magento module:enable CpfHub_Validation
php bin/magento setup:upgrade
php bin/magento cache:flush
```

Em seguida, acesse o painel administrativo em **Stores > Configuration > General > CPFHub Validation** para ativar a funcionalidade e inserir sua chave de API.

---

## 10. Boas práticas para produção

* **Implemente cache** — Utilize o cache do Magento para armazenar resultados de consultas recentes e economizar chamadas à API.

* **Configure logging adequado** — Monitore as consultas e erros para identificar problemas rapidamente.

* **Considere o plano Pro** — Para lojas com alto volume de pedidos, o plano Pro da CPFHub.io (R$149/mês) oferece 1.000 consultas inclusas. Consultas adicionais custam R$0,15 cada e a API nunca bloqueia a operação.

* **Valide o formato do CPF localmente** — Antes de chamar a API, verifique se o CPF possui 11 dígitos e se os dígitos verificadores são válidos. Isso evita consumo desnecessário de consultas.

---

## Perguntas frequentes

### Por que usar um Observer em vez de um plugin (interceptor) do Magento 2 para validar o CPF?

Observers são mais simples de implementar e suficientes para validação pré-pedido. Plugins (before/after/around) são mais adequados quando você precisa modificar argumentos ou retornos de métodos públicos. Para uma validação que deve lançar exceção e bloquear o fluxo se o CPF for inválido, o evento `sales_order_place_before` com um Observer é a abordagem mais direta e performática.

### Como tratar o caso em que a API da CPFHub.io está indisponível durante o checkout?

Configure um timeout adequado (30 segundos no exemplo) e, no bloco `catch`, decida entre falhar aberto (permitir o pedido) ou falha fechada (bloquear). Para lojas com alto risco de fraude, recomenda-se falha fechada com mensagem clara ao comprador. Para lojas com menor risco, falha aberta com log do erro e alerta por e-mail ao time de operações garante melhor experiência de compra.

### A integração funciona com Magento 2 em ambiente de múltiplas lojas (multistore)?

Sim. O módulo lê a configuração pelo `ScopeConfigInterface`, que suporta escopos por store view, website e default. Você pode configurar API keys diferentes por website ou usar a mesma chave em todos os escopos, dependendo da organização das suas contas no CPFHub.io.

### Como garantir conformidade com a LGPD nessa integração com Magento 2?

Não armazene o CPF em logs de debug — use mascaramento (`substr($cpf, 0, 3) . '****'`). Configure a política de retenção dos logs do Magento para não guardar dados pessoais além do necessário. Inclua na política de privacidade da loja que o CPF é validado via API para fins de emissão de nota fiscal e prevenção de fraudes. A [ANPD](https://www.gov.br/anpd) orienta que o tratamento de dados pessoais deve ser documentado e proporcional à finalidade.

### 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)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [API de consulta de CPF: como funciona a autenticação via API key](https://cpfhub.io/blog/api-de-consulta-de-cpf-como-funciona-a-autenticacao-via-api-key)
- [Como evitar chargebacks usando validação de CPF no checkout](https://cpfhub.io/blog/como-evitar-chargebacks-usando-validacao-de-cpf-no-checkout)

---

## Conclusão

A integração da validação de CPF em Magento 2 por meio de módulos customizados permite que lojas virtuais verifiquem a identidade de compradores em tempo real durante o checkout. Essa camada de segurança reduz fraudes, minimiza chargebacks e garante a correta emissão de documentos fiscais. Com a estrutura apresentada — registro do módulo, classe de serviço e Observer — a implementação é limpa, testável e fácil de manter.

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.