# Como integrar validação de CPF no WooCommerce com API

> Tutorial passo a passo para integrar validação de CPF no checkout do WooCommerce usando a API da CPFHub.io, com exemplos de código em PHP.

**Publicado:** 14/05/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-no-woocommerce-com-api

---


Para integrar validação de CPF no WooCommerce, use o hook `woocommerce_checkout_process` para interceptar o checkout, faça uma chamada GET para `https://api.cpfhub.io/cpf/{cpf}` com o header `x-api-key`, e exiba `wc_add_notice` com a mensagem de erro se o CPF não for encontrado. A validação ocorre antes da criação do pedido e pode bloquear checkouts com CPF inválido, fabricado ou inconsistente com o nome informado.

## Introdução

O WooCommerce é a plataforma de e-commerce mais utilizada no mundo, responsável por uma parcela significativa das lojas virtuais brasileiras. Para lojas que operam no Brasil, a validação de CPF no checkout é essencial tanto para a emissão de notas fiscais quanto para a prevenção de fraudes.

No entanto, o WooCommerce não possui validação de CPF nativa. Plugins populares como o "Brazilian Market on WooCommerce" adicionam o campo de CPF ao checkout, mas geralmente se limitam à validação algorítmica dos dígitos verificadores. Isso significa que CPFs matematicamente válidos mas inexistentes ou pertencentes a terceiros passam pela verificação sem qualquer alerta.

---

## O que o WooCommerce oferece nativamente

O WooCommerce padrão não inclui um campo de CPF no checkout. Para lojas brasileiras, existem plugins que adicionam campos de CPF e CNPJ, incluindo:

* **Brazilian Market on WooCommerce** -- Adiciona campos de CPF/CNPJ, bairro e outros dados brasileiros.
* **Jetkore** -- Campos brasileiros com máscara de formatação.
* **WooCommerce Extra Checkout Fields for Brazil** -- Plugin gratuito com campos brasileiros completos.

Esses plugins adicionam o campo e validam o formato, mas não consultam APIs externas para verificar a existência real do CPF.

---

## Adicionando o campo de CPF ao checkout

Se você ainda não tem um campo de CPF no checkout, pode adicioná-lo via código no arquivo `functions.php` do seu tema filho:

```php
// Adicionar campo de CPF ao checkout
add_filter('woocommerce_checkout_fields', 'adicionar_campo_cpf');

function adicionar_campo_cpf($fields) {
 $fields['billing']['billing_cpf'] = array(
 'type' => 'text',
 'label' => 'CPF',
 'placeholder' => '000.000.000-00',
 'required' => true,
 'class' => array('form-row-wide'),
 'priority' => 25,
 'maxlength' => 14,
 'custom_attributes' => array(
 'inputmode' => 'numeric',
 'pattern' => '[0-9]*',
 ),
 );

 return $fields;
}

// Salvar o CPF no pedido
add_action('woocommerce_checkout_update_order_meta', 'salvar_cpf_pedido');

function salvar_cpf_pedido($order_id) {
 if (!empty($_POST['billing_cpf'])) {
 update_post_meta($order_id, '_billing_cpf', sanitize_text_field($_POST['billing_cpf']));
 }
}
```

---

## Integrando a validação via API no checkout

A validação via API deve ocorrer no momento em que o formulário de checkout é processado, antes da criação do pedido. No WooCommerce, isso é feito através do hook `woocommerce_checkout_process`:

```php
add_action('woocommerce_checkout_process', 'validar_cpf_checkout');

function validar_cpf_checkout() {
 $cpf = isset($_POST['billing_cpf']) ? sanitize_text_field($_POST['billing_cpf']) : '';
 $cpf_limpo = preg_replace('/\D/', '', $cpf);

 // Validação de formato
 if (strlen($cpf_limpo) !== 11) {
 wc_add_notice('O CPF informado é inválido. Verifique se digitou todos os 11 dígitos.', 'error');
 return;
 }

 // Validação algorítmica
 if (!validar_digitos_cpf($cpf_limpo)) {
 wc_add_notice('O CPF informado contém dígitos verificadores incorretos. Confira o número.', 'error');
 return;
 }

 // Validação via API CPFHub.io
 $api_key = get_option('cpfhub_api_key', '');
 if (empty($api_key)) return; // Se não tem chave, pular validação por API

 $response = wp_remote_get(
 'https://api.cpfhub.io/cpf/' . $cpf_limpo,
 array(
 'headers' => array(
 'x-api-key' => $api_key,
 'Accept' => 'application/json',
 ),
 'timeout' => 10,
 )
 );

 if (is_wp_error($response)) {
 // Em caso de erro na API, não bloquear o checkout
 return;
 }

 $body = json_decode(wp_remote_retrieve_body($response), true);

 if (isset($body['success']) && $body['success'] === false) {
 wc_add_notice('O CPF informado não foi encontrado em nossa verificação. Por favor, confira o número.', 'error');
 return;
 }

 // Opcional: verificar se o nome confere
 if (isset($body['data']['nameUpper'])) {
 $nome_checkout = strtoupper(sanitize_text_field($_POST['billing_first_name'] . ' ' . $_POST['billing_last_name']));
 $nome_api = $body['data']['nameUpper'];

 // Verificar se pelo menos o primeiro nome confere
 $primeiro_nome_checkout = explode(' ', trim($nome_checkout))[0];
 if (strpos($nome_api, $primeiro_nome_checkout) === false) {
 wc_add_notice('O nome informado não corresponde ao titular do CPF. Verifique os dados.', 'error');
 return;
 }
 }
}

function validar_digitos_cpf($cpf) {
 if (preg_match('/^(\d)\1{10}$/', $cpf)) return false;

 $soma = 0;
 for ($i = 0; $i < 9; $i++) {
 $soma += intval($cpf[$i]) * (10 - $i);
 }
 $resto = $soma % 11;
 $digito1 = ($resto < 2) ? 0 : 11 - $resto;
 if (intval($cpf[9]) !== $digito1) return false;

 $soma = 0;
 for ($i = 0; $i < 10; $i++) {
 $soma += intval($cpf[$i]) * (11 - $i);
 }
 $resto = $soma % 11;
 $digito2 = ($resto < 2) ? 0 : 11 - $resto;
 if (intval($cpf[10]) !== $digito2) return false;

 return true;
}
```

---

## Configurando a chave de API no painel do WordPress

Para não expor a chave de API no código, armazene-a como uma opção do WordPress. Crie uma página de configuração simples:

```php
add_action('admin_menu', 'cpfhub_menu_configuracao');

function cpfhub_menu_configuracao() {
 add_options_page(
 'CPFHub.io Configurações',
 'CPFHub.io',
 'manage_options',
 'cpfhub-config',
 'cpfhub_pagina_configuracao'
 );
}

function cpfhub_pagina_configuracao() {
 if (isset($_POST['cpfhub_api_key'])) {
 update_option('cpfhub_api_key', sanitize_text_field($_POST['cpfhub_api_key']));
 echo '<div class="updated"><p>Chave salva com sucesso.</p></div>';
 }

 $api_key = get_option('cpfhub_api_key', '');
 ?>
 <div class="wrap">
 <h1>CPFHub.io - Configurações</h1>
 <form method="post">
 <table class="form-table">
 <tr>
 <th>Chave de API</th>
 <td>
 <input type="text" name="cpfhub_api_key"
 value="<?php echo esc_attr($api_key); ?>"
 class="regular-text" />
 <p class="description">
 Obtenha sua chave em
 <a href="https://www.cpfhub.io/" target="_blank">cpfhub.io</a>
 </p>
 </td>
 </tr>
 </table>
 <?php submit_button('Salvar'); ?>
 </form>
 </div>
 <?php
}
```

---

## Adicionando máscara de CPF no frontend

Para melhorar a experiência do usuário, adicione uma máscara de formatação via JavaScript no checkout:

```php
add_action('wp_footer', 'mascara_cpf_checkout');

function mascara_cpf_checkout() {
 if (!is_checkout()) return;
 ?>
 <script>
 document.addEventListener('DOMContentLoaded', function() {
 var campo = document.getElementById('billing_cpf');
 if (!campo) return;

 campo.addEventListener('input', function(e) {
 var valor = e.target.value.replace(/\D/g, '');
 if (valor.length <= 3) {
 e.target.value = valor;
 } else if (valor.length <= 6) {
 e.target.value = valor.slice(0, 3) + '.' + valor.slice(3);
 } else if (valor.length <= 9) {
 e.target.value = valor.slice(0, 3) + '.' + valor.slice(3, 6) + '.' + valor.slice(6);
 } else {
 e.target.value = valor.slice(0, 3) + '.' + valor.slice(3, 6) + '.' + valor.slice(6, 9) + '-' + valor.slice(9, 11);
 }
 });
 });
 </script>
 <?php
}
```

---

## Exibindo o CPF no painel administrativo

Para que o administrador da loja visualize o CPF nos detalhes do pedido:

```php
add_action('woocommerce_admin_order_data_after_billing_address', 'exibir_cpf_admin');

function exibir_cpf_admin($order) {
 $cpf = get_post_meta($order->get_id(), '_billing_cpf', true);
 if ($cpf) {
 echo '<p><strong>CPF:</strong> ' . esc_html($cpf) . '</p>';
 }
}
```

---

## Considerações de performance

A validação via API adiciona uma chamada HTTP ao processo de checkout. Para garantir que isso não impacte negativamente a experiência do usuário:

* **Timeout adequado** -- Configure um timeout de 10 segundos na chamada à API. Se excedido, permita que o checkout prossiga.

* **Fallback gracioso** -- Se a API estiver indisponível, não bloqueie a venda. A validação algorítmica já oferece um nível básico de proteção.

* **Cache de resultados** -- Se o mesmo CPF for utilizado em compras subsequentes, utilize um transient do WordPress para cachear o resultado por 24 horas.

A API da [**CPFHub.io**](https://www.cpfhub.io/) responde em aproximadamente 900ms, dentro do timeout de 10 segundos configurado no `wp_remote_get`. Em caso de indisponibilidade, o código já prevê fallback gracioso: se a chamada retornar erro HTTP, o checkout prossegue com a validação algorítmica como última camada de proteção.

---

## Perguntas frequentes

### Por que não usar apenas o plugin "Brazilian Market on WooCommerce" para validar CPF?
O plugin valida apenas o formato matemático dos dígitos verificadores — não confirma se o CPF existe na base da Receita Federal. CPFs fabricados com formato válido passam pela validação do plugin. A integração com a API garante que o CPF pertence a uma pessoa real e que o nome confere com o cadastro, bloqueando as fraudes mais comuns em e-commerce.

### A validação de CPF no checkout do WooCommerce pode aumentar o tempo de finalização da compra?
Sim, mas o impacto é mínimo. A API responde em aproximadamente 900ms. Com timeout de 10 segundos e fallback gracioso (se a API não responder, o checkout prossegue), o atraso perceptível ao usuário é menor que 1 segundo na maioria dos casos. O benefício em prevenção de fraudes e qualidade de dados supera esse custo.

### É possível usar cache para evitar consultas repetidas ao mesmo CPF no WooCommerce?
Sim. Use o sistema de transients do WordPress (`set_transient` / `get_transient`) para cachear o resultado por 24 horas. Verifique no início da função de validação se já existe um transient para o CPF e pule a chamada à API se o resultado já estiver cacheado — economizando consultas em clientes recorrentes.

### O que fazer quando um cliente legítimo tem CPF rejeitado pela API no checkout?
Configure o fallback corretamente: se a API retornar erro de rede (não erro de CPF inválido), permita que o checkout prossiga. Para rejeições reais (CPF não encontrado), exiba mensagem clara pedindo para conferir o número. Implemente um campo de CPF com máscara para evitar erros de digitação antes da validação.

### 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)
- [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf)

---

## Conclusão

Integrar a validação de CPF via API no checkout do WooCommerce é uma forma eficiente de proteger sua loja contra fraudes, garantir a correta emissão de notas fiscais e melhorar a qualidade dos dados cadastrais dos seus clientes. Com poucas dezenas de linhas de código PHP, é possível adicionar uma camada de segurança que vai muito além da validação algorítmica oferecida pelos plugins padrão.

A implementação é simples e não compromete a conversão: o fallback gracioso garante que indisponibilidades da API não bloqueiem vendas legítimas. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação real de CPF ao checkout da sua loja WooCommerce hoje mesmo.