# Como integrar validação de CPF em WooCommerce com plugins e API

> Guia completo para integrar validação de CPF no WooCommerce usando plugins e API REST. Exemplos de código PHP e boas práticas para e-commerce.

**Publicado:** 12/03/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-woocommerce-com-plugins-e-api

---


## Introdução

O WooCommerce é a plataforma de e-commerce mais utilizada no mundo, presente em mais de 25% das lojas virtuais globais. No Brasil, a necessidade de coletar e validar o CPF do comprador no checkout é uma realidade incontornável, seja para emissão de nota fiscal, prevenção a fraudes ou conformidade regulatória. No entanto, o WooCommerce não traz um campo de CPF nativamente, o que exige o uso de plugins ou integrações personalizadas.

---

## Adicionando o campo de CPF no checkout

### Opção 1: Plugins populares

Existem plugins amplamente utilizados para adicionar campos brasileiros (CPF, CNPJ, bairro, etc.) ao checkout do WooCommerce:

* **Brazilian Market on WooCommerce** -- Plugin gratuito que adiciona campos de CPF, CNPJ, bairro e outros campos específicos do mercado brasileiro ao checkout e ao cadastro.

* **WooCommerce Extra Checkout Fields for Brazil** -- Outro plugin popular que adiciona campos de pessoa física e jurídica, com validação básica de formato.

Esses plugins resolvem a questão do campo no formulário e da validação de formato (dígitos verificadores), mas não realizam consulta de dados cadastrais. Ou seja, eles verificam se o número tem formato válido, mas não confirmam se o CPF existe de fato ou se corresponde ao nome informado.

### Opção 2: Código personalizado

Se preferir não usar plugins adicionais, é possível adicionar o campo de CPF diretamente via código no arquivo `functions.php` do tema:

```php
// Adicionar campo de CPF ao checkout
add_filter('woocommerce_checkout_fields', function($fields) {
 $fields['billing']['billing_cpf'] = array(
 'type' => 'text',
 'label' => 'CPF',
 'placeholder' => '000.000.000-00',
 'required' => true,
 'class' => array('form-row-wide'),
 'priority' => 25,
 );
 return $fields;
});

// Validar formato do CPF no checkout
add_action('woocommerce_checkout_process', function() {
 $cpf = preg_replace('/\D/', '', $_POST['billing_cpf']);

 if (strlen($cpf) !== 11) {
 wc_add_notice('CPF inválido. Informe um CPF com 11 dígitos.', 'error');
 return;
 }

 // Validar dígitos verificadores
 if (!validar_digitos_cpf($cpf)) {
 wc_add_notice('CPF inválido. Verifique os dígitos informados.', 'error');
 }
});

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

 // Primeiro dígito
 $soma = 0;
 for ($i = 0; $i < 9; $i++) {
 $soma += intval($cpf[$i]) * (10 - $i);
 }
 $resto = ($soma * 10) % 11;
 if ($resto === 10) $resto = 0;
 if ($resto !== intval($cpf[9])) return false;

 // Segundo dígito
 $soma = 0;
 for ($i = 0; $i < 10; $i++) {
 $soma += intval($cpf[$i]) * (11 - $i);
 }
 $resto = ($soma * 10) % 11;
 if ($resto === 10) $resto = 0;
 if ($resto !== intval($cpf[10])) return false;

 return true;
}
```

---

## Indo além: validação de CPF via API

A validação de formato impede que o usuário insira um CPF com dígitos incorretos, mas não confirma se aquele CPF pertence a uma pessoa real. Para isso, é necessário consultar uma API de dados cadastrais.

A [**CPFHub.io**](https://www.cpfhub.io/) oferece uma API REST simples que retorna nome completo, gênero e data de nascimento do titular em aproximadamente 900ms — suficiente para integrar ao checkout sem impactar a experiência de compra.

### Exemplo de consulta com cURL

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

### Resposta

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "Pedro Henrique Oliveira",
 "nameUpper": "PEDRO HENRIQUE OLIVEIRA",
 "gender": "M",
 "birthDate": "30/01/1987",
 "day": 30,
 "month": 1,
 "year": 1987
 }
}
```

---

## Integrando a API da CPFHub.io no WooCommerce

### Hook de validação no checkout

O código a seguir integra a consulta à API da CPFHub.io no processo de validação do checkout do WooCommerce:

```php
add_action('woocommerce_checkout_process', function() {
 $cpf = preg_replace('/\D/', '', $_POST['billing_cpf']);
 $nome_informado = $_POST['billing_first_name'] . ' ' . $_POST['billing_last_name'];

 if (strlen($cpf) !== 11 || !validar_digitos_cpf($cpf)) {
 wc_add_notice('CPF inválido.', 'error');
 return;
 }

 // Consultar API da CPFHub.io
 $response = wp_remote_get(
 "https://api.cpfhub.io/cpf/{$cpf}",
 array(
 'headers' => array(
 'x-api-key' => 'SUA_CHAVE_DE_API',
 'Accept' => 'application/json',
 ),
 'timeout' => 10,
 )
 );

 if (is_wp_error($response)) {
 // Em caso de falha na API, permitir prosseguir
 // mas registrar para análise posterior
 error_log('CPFHub API error: ' . $response->get_error_message());
 return;
 }

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

 if (!$body['success']) {
 wc_add_notice('CPF não encontrado. Verifique o número informado.', 'error');
 return;
 }

 // Comparar nome (opcional mas recomendado)
 $nome_oficial = mb_strtoupper($body['data']['name']);
 $nome_usuario = mb_strtoupper(trim($nome_informado));

 // Registrar dados para auditoria
 WC()->session->set('cpf_validado', true);
 WC()->session->set('cpf_nome_oficial', $body['data']['name']);
});
```

### Salvando o CPF no pedido

Para que o CPF fique registrado no pedido, adicione:

```php
add_action('woocommerce_checkout_update_order_meta', function($order_id) {
 if (!empty($_POST['billing_cpf'])) {
 $cpf = preg_replace('/\D/', '', $_POST['billing_cpf']);
 update_post_meta($order_id, '_billing_cpf', $cpf);
 }
});

// Exibir CPF na página de detalhes do pedido no admin
add_action('woocommerce_admin_order_data_after_billing_address', function($order) {
 $cpf = get_post_meta($order->get_id(), '_billing_cpf', true);
 if ($cpf) {
 echo '<p><strong>CPF:</strong> ' . esc_html($cpf) . '</p>';
 }
});
```

---

## Máscara de formatação no frontend

Para melhorar a experiência do usuário, adicione uma máscara de formatação ao campo de CPF usando JavaScript:

```javascript
jQuery(document).ready(function($) {
 $('#billing_cpf').on('input', function() {
 var valor = $(this).val().replace(/\D/g, '');
 valor = valor.replace(/(\d{3})(\d)/, '$1.$2');
 valor = valor.replace(/(\d{3})(\d)/, '$1.$2');
 valor = valor.replace(/(\d{3})(\d{1,2})$/, '$1-$2');
 $(this).val(valor);
 });

 $('#billing_cpf').attr('maxlength', '14');
});
```

Esse script pode ser adicionado via `wp_enqueue_script` no seu tema ou plugin.

---

## Tratamento de falhas da API

Em um ambiente de produção, é essencial tratar cenários de falha da API para não bloquear vendas desnecessariamente:

* **Timeout da API** -- Se a API não responder dentro do prazo (10 segundos), permita a compra mas sinalize para revisão manual.

* **Erro 429 (Rate limit)** -- Implemente retry com backoff exponencial ou permita a compra e valide posteriormente.

* **Erro 500/503** -- Permita a compra e registre o erro para análise.

A regra geral é: a validação de CPF deve aumentar a segurança, mas nunca deve impedir uma venda legítima por falha técnica.

---

## Planos da CPFHub.io para e-commerce

| Plano | Preço | Consultas/mês | Ideal para |
| --- | --- | --- | --- |
| Grátis | R$ 0 | 50 | Testes e lojas em início |
| Pro | R$ 149/mês | 1.000 | Lojas com até 1.000 pedidos/mês |
| Corporativo | Sob consulta | Personalizado | E-commerces de grande porte |

---

## Perguntas frequentes

### O que é necessário para implementar validação de CPF neste contexto?
A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

### A API CPFHub.io funciona para todos os volumes de consulta?
Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

### 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.

### Quanto tempo leva para integrar a API CPFHub.io?
A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

### 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 no WooCommerce é essencial para lojas virtuais brasileiras. Plugins populares resolvem a adição do campo e a validação de formato, mas a validação real — que confirma a existência do CPF e os dados do titular — exige uma API como a da [**CPFHub.io**](https://www.cpfhub.io/). O plano gratuito com 50 consultas mensais é ideal para testar a integração em ambiente de desenvolvimento. Acesse [cpfhub.io](https://www.cpfhub.io/) para criar sua conta e obter a API key em minutos.