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

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

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:

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:

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:

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

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