Validação de CPF em plugin WordPress: passo a passo com a API SmartCPF

Validar CPF é uma necessidade recorrente em projetos WordPress brasileiros — seja em formulários de cadastro, checkout de e-commerce, áreas de membros ou sistemas de agendamento. A validação apenas do dígito verificador (algoritmo do módulo 11) não garante que o CPF exista na base da Receita Federal, tampouco retorna dados cadastrais úteis como nome, data de nascimento ou situação cadastral.

A API SmartCPF resolve isso oferecendo consulta em tempo real à base oficial, com resposta estruturada em JSON, autenticação simples via header X-API-KEY e modelo de créditos previsível. Este tutorial mostra como integrar a validação completa em um plugin WordPress, do registro da chave até o tratamento de erros de rede e da própria API.

Como funciona a consulta de CPF na SmartCPF

A API expõe o endpoint GET https://api.smartcpf.com.br/v2/individuals/{cpf}?package=X, onde {cpf} pode vir com ou sem formatação (pontos e traço) e package define o nível de detalhe do retorno. A autenticação é exclusivamente via header X-API-KEY — não use Authorization: Bearer, nem api_key na query string, nem outro método.

O parâmetro package aceita valores como basic (dados cadastrais essenciais), complete (inclui e-mails, telefones e endereços) e score (adiciona score de risco). A resposta traz campos como consultId (UUID único da consulta), balance (créditos restantes), executionTimeMs e o objeto result com os dados do CPF consultado.

Vantagens de usar a SmartCPF em plugins WordPress

1. Consulta à base oficial em tempo real
Não depende de bases locais desatualizadas; a API consulta a Receita Federal no momento da requisição.

2. Autenticação simples e segura
Um único header X-API-KEY evita complexidade de OAuth, tokens JWT ou rotação de segredos no lado do cliente.

3. Modelo de créditos previsível
Cada consulta consome 1 crédito (ou mais, dependendo do package); o campo balance no retorno permite monitorar o saldo sem chamadas extras.

4. Resposta padronizada e versionada
O envelope meta + result + success + errors facilita parsing e tratamento de erros consistente em qualquer linguagem.

5. Suporte a CPF formatado ou limpo
Aceita 111.111.111-11 ou 11111111111 sem necessidade de normalização prévia no plugin.

6. Execução rápida (média < 100ms)
O campo executionTimeMs confirma latência baixa, adequada para validação síncrona em formulários.

Desafios ao integrar validação de CPF no WordPress

1. Dependência de rede externa
Se a API estiver indisponível, o fluxo de cadastro falha; é necessário fallback (ex.: validação só do dígito verificador) ou fila de retentativa.

2. Gestão de créditos
Plugins de alto volume podem esgotar o saldo rápido; implemente alerta quando balance cair abaixo de um limite.

3. Tratamento de CPFs inválidos ou inexistentes
A API retorna success: false e errors preenchido; o plugin deve distinguir erro de validação (formato) de CPF não encontrado na base.

4. LGPD e consentimento
Consultar dados de terceiros exige base legal; o plugin deve registrar consentimento do titular antes de chamar a API.

5. Cache excessivo pode servir dados desatualizados
Evite cache de longa duração para consultas de CPF; a situação cadastral pode mudar (regular → suspenso, por exemplo).

Como implementar com a SmartCPF

O exemplo abaixo registra um shortcode [smartcpf_validar] que renderiza um formulário, valida o CPF via AJAX e exibe o resultado. Inclui nonce para segurança, sanitização de entrada, tratamento de erros de rede e da API, e exibição dos campos principais do retorno.

smartcpf-validator.php

<?php
/**
 * Plugin Name: SmartCPF Validador
 * Description: Validação de CPF via API SmartCPF v2 com shortcode e AJAX.
 * Version: 1.0.0
 * Author: SmartCPF
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Registra o shortcode [smartcpf_validar]
 */
add_action( 'init', function () {
    add_shortcode( 'smartcpf_validar', 'smartcpf_render_form' );
} );

/**
 * Enfileira scripts e localiza variáveis para o AJAX
 */
add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'smartcpf-validator',
        plugin_dir_url( __FILE__ ) . 'assets/js/validator.js',
        [ 'jquery' ],
        '1.0.0',
        true
    );

    wp_localize_script( 'smartcpf-validator', 'smartcpf_ajax', [
        'ajax_url'      => admin_url( 'admin-ajax.php' ),
        'nonce'         => wp_create_nonce( 'smartcpf_validate_nonce' ),
        'api_base_url'  => 'https://api.smartcpf.com.br/v2',
        // A API Key DEVE vir de variável de ambiente ou opção segura — NUNCA hardcoded.
        // Exemplo: get_option( 'smartcpf_api_key' ) ou $_ENV['SMARTCPF_API_KEY']
        'api_key'       => get_option( 'smartcpf_api_key', '' ),
        'package'       => 'complete',
    ] );
} );

/**
 * Renderiza o formulário de validação
 */
function smartcpf_render_form(): string {
    ob_start();
    ?>
    <div id="smartcpf-validator" class="smartcpf-validator">
        <form id="smartcpf-form" method="post" action="#">
            <label for="smartcpf-cpf">CPF:</label>
            <input
                type="text"
                id="smartcpf-cpf"
                name="cpf"
                placeholder="000.000.000-00"
                maxlength="14"
                required
                pattern="\d{3}\.?\d{3}\.?\d{3}-?\d{2}"
                title="Formato: 000.000.000-00"
            >
            <button type="submit" id="smartcpf-submit">Validar</button>
        </form>

        <div id="smartcpf-result" class="smartcpf-result" style="display:none;"></div>
        <div id="smartcpf-loading" class="smartcpf-loading" style="display:none;">Consultando...</div>
        <div id="smartcpf-error" class="smartcpf-error" style="display:none;"></div>
    </div>
    <?php
    return ob_get_clean();
}

/**
 * Handler AJAX para validar CPF na API SmartCPF
 */
add_action( 'wp_ajax_smartcpf_validate', 'smartcpf_ajax_validate' );
add_action( 'wp_ajax_nopriv_smartcpf_validate', 'smartcpf_ajax_validate' );

function smartcpf_ajax_validate(): void {
    // Verifica nonce
    check_ajax_referer( 'smartcpf_validate_nonce', 'nonce' );

    // Sanitiza entrada
    $cpf = isset( $_POST['cpf'] ) ? sanitize_text_field( wp_unslash( $_POST['cpf'] ) ) : '';
    $cpf = preg_replace( '/\D/', '', $cpf ); // Remove não-dígitos

    if ( ! $cpf || strlen( $cpf ) !== 11 ) {
        wp_send_json_error( [ 'message' => 'CPF inválido. Informe 11 dígitos.' ] );
        return;
    }

    // Validação básica do dígito verificador (módulo 11) antes de chamar a API
    if ( ! smartcpf_validar_digitos( $cpf ) ) {
        wp_send_json_error( [ 'message' => 'CPF inválido (dígito verificador incorreto).' ] );
        return;
    }

    $api_key = get_option( 'smartcpf_api_key', '' );
    if ( empty( $api_key ) ) {
        wp_send_json_error( [ 'message' => 'API Key não configurada no painel do plugin.' ] );
        return;
    }

    $package = 'complete'; // ou 'basic', 'score'
    $url     = "https://api.smartcpf.com.br/v2/individuals/{$cpf}?package={$package}";

    // Requisição HTTP com wp_remote_get
    $response = wp_remote_get( $url, [
        'timeout'   => 15,
        'headers'   => [
            'X-API-KEY' => $api_key,
            'Accept'    => 'application/json',
        ],
    ] );

    // Erro de rede / timeout / DNS
    if ( is_wp_error( $response ) ) {
        $msg = 'Erro de conexão com a API: ' . $response->get_error_message();
        error_log( '[SmartCPF] ' . $msg );
        wp_send_json_error( [ 'message' => $msg ] );
        return;
    }

    $http_code = wp_remote_retrieve_response_code( $response );
    $body      = wp_remote_retrieve_body( $response );

    // HTTP 4xx/5xx
    if ( $http_code >= 400 ) {
        $error_data = json_decode( $body, true );
        $msg        = $error_data['message'] ?? "Erro HTTP {$http_code} na API SmartCPF";
        error_log( "[SmartCPF] HTTP {$http_code}: {$msg}" );
        wp_send_json_error( [ 'message' => $msg, 'http_code' => $http_code ] );
        return;
    }

    $data = json_decode( $body, true );

    // API retornou success: false (ex.: CPF não encontrado)
    if ( empty( $data['success'] ) ) {
        $errors = $data['errors'] ?? [ [ 'message' => 'CPF não encontrado ou erro desconhecido' ] ];
        $msg    = is_array( $errors ) ? $errors[0]['message'] : 'Erro na consulta';
        wp_send_json_error( [ 'message' => $msg, 'api_errors' => $errors ] );
        return;
    }

    // Sucesso — retorna dados estruturados para o front-end
    wp_send_json_success( [
        'meta'   => $data['meta'] ?? [],
        'result' => $data['result'] ?? [],
    ] );
}

/**
 * Validação do dígito verificador (módulo 11) — algoritmo oficial da Receita Federal
 */
function smartcpf_validar_digitos( string $cpf ): bool {
    if ( strlen( $cpf ) !== 11 || preg_match( '/^(\d)\1{10}$/', $cpf ) ) {
        return false; // Todos dígitos iguais é inválido
    }

    for ( $t = 9; $t < 11; $t++ ) {
        $sum = 0;
        for ( $i = 0; $i < $t; $i++ ) {
            $sum += (int) $cpf[$i] * ( ( $t + 1 ) - $i );
        }
        $digit = ( ( $sum * 10 ) % 11 ) % 10;
        if ( (int) $cpf[$t] !== $digit ) {
            return false;
        }
    }
    return true;
}

/**
 * Página de configurações do plugin (opcional — para salvar a API Key)
 */
add_action( 'admin_menu', function () {
    add_options_page(
        'SmartCPF Validador',
        'SmartCPF Validador',
        'manage_options',
        'smartcpf-validator',
        'smartcpf_settings_page'
    );
} );

add_action( 'admin_init', function () {
    register_setting( 'smartcpf_validator_group', 'smartcpf_api_key', [
        'type'              => 'string',
        'sanitize_callback' => 'sanitize_text_field',
    ] );
} );

function smartcpf_settings_page(): void {
    ?>
    <div class="wrap">
        <h1>Configurações SmartCPF Validador</h1>
        <form method="post" action="options.php">
            <?php settings_fields( 'smartcpf_validator_group' ); ?>
            <table class="form-table">
                <tr>
                    <th scope="row"><label for="smartcpf_api_key">API Key (X-API-KEY)</label></th>
                    <td>
                        <input
                            type="password"
                            id="smartcpf_api_key"
                            name="smartcpf_api_key"
                            value="<?php echo esc_attr( get_option( 'smartcpf_api_key', '' ) ); ?>"
                            class="regular-text"
                            required
                        >
                        <p class="description">Obtenha sua chave em <a href="https://smartcpf.com.br" target="_blank">smartcpf.com.br</a>. Armazenada como opção do WordPress.</p>
                    </td>
                </tr>
            </table>
            <?php submit_button(); ?>
        </form>
    </div>
    <?php
}

E o JavaScript para o front-end (arquivo assets/js/validator.js):

assets/js/validator.js

jQuery( function ( $ ) {
    const $form       = $( '#smartcpf-form' );
    const $result     = $( '#smartcpf-result' );
    const $loading    = $( '#smartcpf-loading' );
    const $error      = $( '#smartcpf-error' );
    const $submit     = $( '#smartcpf-submit' );
    const ajaxData    = window.smartcpf_ajax;

    $form.on( 'submit', function ( e ) {
        e.preventDefault();

        const cpf = $( '#smartcpf-cpf' ).val().trim();
        if ( ! cpf ) {
            showError( 'Informe um CPF.' );
            return;
        }

        $loading.show();
        $result.hide();
        $error.hide();
        $submit.prop( 'disabled', true );

        $.post( ajaxData.ajax_url, {
            action: 'smartcpf_validate',
            nonce:  ajaxData.nonce,
            cpf:    cpf,
        } )
        .done( function ( response ) {
            if ( response.success ) {
                renderResult( response.data );
            } else {
                showError( response.data?.message || 'Erro desconhecido.' );
            }
        } )
        .fail( function ( xhr ) {
            const msg = xhr.responseJSON?.data?.message || 'Falha na requisição AJAX.';
            showError( msg );
        } )
        .always( function () {
            $loading.hide();
            $submit.prop( 'disabled', false );
        } );
    } );

    function renderResult( data ) {
        const meta   = data.meta || {};
        const result = data.result || {};

        let html = '<div class="smartcpf-success"><h3>CPF Validado com Sucesso</h3>';

        // Dados principais do result
        if ( result.cpf ) {
            html += `<p><strong>CPF:</strong> ${escapeHtml( result.cpf )}</p>`;
        }
        if ( result.name ) {
            html += `<p><strong>Nome:</strong> ${escapeHtml( result.name )}</p>`;
        }
        if ( result.birthDate ) {
            html += `<p><strong>Data de Nascimento:</strong> ${escapeHtml( result.birthDate )}`;
            if ( result.age ) {
                html += ` (${escapeHtml( result.age )} anos)`;
            }
            html += '</p>';
        }
        if ( result.motherName ) {
            html += `<p><strong>Nome da Mãe:</strong> ${escapeHtml( result.motherName )}</p>`;
        }
        if ( result.gender ) {
            html += `<p><strong>Sexo:</strong> ${escapeHtml( result.gender === 'M' ? 'Masculino' : 'Feminino' )}</p>`;
        }
        if ( result.status ) {
            html += `<p><strong>Situação:</strong> <span class="status-${result.status.toLowerCase()}">${escapeHtml( result.status )}</span></p>`;
        }

        // E-mails
        if ( result.emails && result.emails.length ) {
            html += '<p><strong>E-mails:</strong><ul>';
            result.emails.forEach( email => {
                html += `<li>${escapeHtml( email )}</li>`;
            } );
            html += '</ul></p>';
        }

        // Telefones
        if ( result.phones && result.phones.length ) {
            html += '<p><strong>Telefones:</strong><ul>';
            result.phones.forEach( phone => {
                const tags = [];
                if ( phone.type ) tags.push( phone.type );
                if ( phone.operator ) tags.push( phone.operator );
                if ( phone.blockedTelemarketing ) tags.push( 'Bloqueado p/ telemarketing' );
                if ( phone.whatsapp ) tags.push( 'WhatsApp' );
                html += `<li>${escapeHtml( phone.number )} ${tags.length ? '(' + tags.join( ', ' ) + ')' : ''}</li>`;
            } );
            html += '</ul></p>';
        }

        // Metadados da consulta
        html += '<hr><h4>Metadados da Consulta</h4><ul>';
        if ( meta.consultId ) html += `<li><strong>Consult ID:</strong> ${escapeHtml( meta.consultId )}</li>`;
        if ( meta.balance !== undefined ) html += `<li><strong>Saldo restante:</strong> ${escapeHtml( meta.balance )} créditos</li>`;
        if ( meta.executionTimeMs ) html += `<li><strong>Tempo de execução:</strong> ${escapeHtml( meta.executionTimeMs )} ms</li>`;
        if ( meta.apiVersion ) html += `<li><strong>Versão da API:</strong> ${escapeHtml( meta.apiVersion )}</li>`;
        if ( meta.date ) html += `<li><strong>Data/Hora:</strong> ${escapeHtml( meta.date )}</li>`;
        html += '</ul></div>';

        $result.html( html ).show();
    }

    function showError( message ) {
        $error.html( `<p>${escapeHtml( message )}</p>` ).show();
    }

    function escapeHtml( text ) {
        const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;' };
        return String( text ).replace( /[&<>"']/g, m => map[m] );
    }
} );

Resposta da API

response.json

{
  "meta": {
    "searchType": "CPF G",
    "consultId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
    "user": "Desenvolvedor WordPress",
    "message": "CPF encontrado com sucesso",
    "ip": "127.0.0.1",
    "success": true,
    "apiVersion": "v2",
    "date": "2025-08-17T14:32:10.123Z",
    "executionTimeMs": 74.1,
    "balance": 9.77
  },
  "result": {
    "cpf": "111.111.111-11",
    "name": "João da Silva",
    "birthDate": "10/09/1992",
    "age": 33,
    "motherName": "Maria da Silva",
    "gender": "M",
    "status": "Regular",
    "emails": ["[email protected]"],
    "phones": [
      {
        "number": "(55) 99999-9999",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": false
      }
    ],
    "addresses": []
  },
  "success": true,
  "errors": []
}

O fluxo demonstrado resolve na prática:

Validação em duas camadas: dígito verificador local (módulo 11) antes da chamada de rede, economizando créditos em CPFs obviamente inválidos.
Rastreabilidade: o consultId (ex.: a1b2c3d4-e5f6-...) permite auditar cada consulta nos logs da SmartCPF.
Controle de custos: o campo balance (ex.: 9.77) retorna o saldo atualizado a cada resposta, permitindo alerta automático quando cai abaixo do limite.
Dados completos para UX: name, birthDate, age, status (ex.: Regular), emails, phones com operadora e tipo — prontos para pré-preencher formulários ou exibir ao usuário.
Performance observável: executionTimeMs (ex.: 74.1) confirma latência adequada para validação síncrona em checkout ou cadastro.

Por que usar a SmartCPF em projetos WordPress

Latência previsível: média abaixo de 100 ms, com executionTimeMs em cada resposta para monitoramento.
Integração sem SDK: wp_remote_get nativo do WordPress resolve a chamada HTTP; apenas o header X-API-KEY é obrigatório.
Modelo de créditos transparente: sem assinatura mensal fixa; paga-se por consulta e o balance retorna em tempo real.
Escalabilidade: a mesma chave funciona em múltiplos sites/plugins; o controle de uso é centralizado no painel da SmartCPF.
Resposta versionada e estável: envelope meta/result/success/errors garante compatibilidade entre versões da API.

Conclusão

Integrar validação real de CPF em um plugin WordPress deixa de ser um problema de manutenção de bases locais ou regex complexas quando se usa a API SmartCPF v2. O padrão X-API-KEY no header, a validação prévia do dígito verificador e o tratamento estruturado de erros (rede, HTTP, API) tornam a solução robusta para produção. O shortcode [smartcpf_validar] exemplifica um fluxo completo — do formulário à exibição de consultId, balance, status e dados de contato — pronto para adaptar a formulários de cadastro, checkout ou áreas restritas.

Crie sua conta na SmartCPF e faça sua primeira consulta em minutos.