Como integrar validação 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:

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

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

Resposta

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

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:

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:

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

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

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. O plano gratuito com 50 consultas mensais é ideal para testar a integração em ambiente de desenvolvimento. Acesse cpfhub.io para criar sua conta e obter a API key em minutos.