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

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

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

use Magento\Framework\Component\ComponentRegistrar;

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

<!-- 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>

<!-- 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>

<?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;
    }
    }
}

<!-- 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
// 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.')
    );
    }
    }
}

{
    "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
    }
}

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

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