Como consumir API de CPF em WordPress com WP_Http

Para consumir a API de CPF em WordPress, use wp_remote_get com o header x-api-key e trate o retorno com wp_remote_retrieve_response_code e wp_remote_retrieve_body. Essa abordagem segue as boas práticas do ecossistema WordPress, garante compatibilidade com plugins de terceiros e pode ser combinada com a Transients API para cache eficiente.

Introdução

O WordPress alimenta mais de 40% dos sites na internet, sendo a plataforma de escolha para blogs, lojas virtuais, portais corporativos e uma infinidade de outros projetos. No Brasil, muitas empresas utilizam WordPress para gerenciar seus sites e precisam integrar funcionalidades de validação de CPF diretamente na plataforma, seja em formulários de cadastro, áreas de checkout do WooCommerce ou painéis administrativos.

1. Pré-requisitos

Para seguir este guia, você precisará de:

• WordPress 5.0 ou superior — Versões mais recentes oferecem melhor suporte a APIs REST.

• Acesso ao código do tema ou plugin — Para adicionar o código de integração.

• Conta na CPFHub.io — Cadastre-se em CPFHub.io e gere sua chave de API no painel em app.cpfhub.io.

2. Configurando a chave de API no WordPress

A forma mais segura de armazenar a chave de API no WordPress é através do arquivo wp-config.php:

// wp-config.php
define('CPFHUB_API_KEY', 'SUA_CHAVE_DE_API');

Alternativamente, você pode criar uma página de configurações no painel administrativo para gerenciar a chave:

// functions.php ou plugin personalizado
add_action('admin_menu', function () {
    add_options_page(
    'CPFHub Configurações',
    'CPFHub',
    'manage_options',
    'cpfhub-settings',
    'cpfhub_settings_page'
    );
});

function cpfhub_settings_page() {
    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>';
    }
    $apiKey = get_option('cpfhub_api_key', '');
    ?>
    <div class="wrap">
    <h1>CPFHub 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($apiKey); ?>" class="regular-text" /></td>
    </tr>
    </table>
    <?php submit_button('Salvar'); ?>
    </form>
    </div>
    <?php
}

3. Função de consulta com wp_remote_get

A função wp_remote_get é a forma recomendada pelo WordPress para fazer requisições HTTP GET:

function cpfhub_consultar_cpf(string $cpf): ?array {
    $cpf_limpo = preg_replace('/\D/', '', $cpf);
    $api_key = defined('CPFHUB_API_KEY') ? CPFHUB_API_KEY : get_option('cpfhub_api_key', '');
    $url = "https://api.cpfhub.io/cpf/{$cpf_limpo}";

    $response = wp_remote_get($url, [
    'headers' => [
    'x-api-key' => $api_key,
    'Accept' => 'application/json',
    ],
    'timeout' => 30,
    ]);

    if (is_wp_error($response)) {
    error_log('CPFHub erro: ' . $response->get_error_message());
    return null;
    }

    $http_code = wp_remote_retrieve_response_code($response);
    $body = wp_remote_retrieve_body($response);
    $data = json_decode($body, true);

    if ($http_code === 200 && isset($data['success']) && $data['success']) {
    return $data['data'];
    }

    error_log("CPFHub erro HTTP {$http_code}: {$body}");
    return null;
}

Observe o parâmetro timeout definido como 30 segundos. Essa configuração evita que o WordPress fique aguardando indefinidamente por uma resposta.

4. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON com os dados do titular do CPF:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

• success — Indica se a consulta foi bem-sucedida.
• name / nameUpper — Nome completo do titular.
• gender — Gênero (M ou F).
• birthDate — Data de nascimento no formato dd/mm/aaaa.
• day, month, year — Componentes da data separados.

5. Criando um shortcode para consulta de CPF

Shortcodes permitem que editores de conteúdo insiram funcionalidades em qualquer página ou post:

add_shortcode('consulta_cpf', function ($atts) {
    $atts = shortcode_atts(['cpf' => ''], $atts);

    if (empty($atts['cpf'])) {
    return '<p>Informe um CPF válido.</p>';
    }

    $dados = cpfhub_consultar_cpf($atts['cpf']);

    if (!$dados) {
    return '<p>Não foi possível consultar o CPF informado.</p>';
    }

    return sprintf(
    '<div class="cpfhub-resultado">
    <p><strong>Nome:</strong> %s</p>
    <p><strong>CPF:</strong> %s</p>
    <p><strong>Gênero:</strong> %s</p>
    <p><strong>Nascimento:</strong> %s</p>
    </div>',
    esc_html($dados['name']),
    esc_html($dados['cpf']),
    esc_html($dados['gender'] === 'M' ? 'Masculino' : 'Feminino'),
    esc_html($dados['birthDate'])
    );
});

Uso no editor do WordPress:

[consulta_cpf cpf="12345678900"]

6. Endpoint AJAX para consulta dinâmica

Para consultas em tempo real via JavaScript, crie um endpoint AJAX no WordPress:

add_action('wp_ajax_cpfhub_consultar', 'cpfhub_ajax_consultar');
add_action('wp_ajax_nopriv_cpfhub_consultar', 'cpfhub_ajax_consultar');

function cpfhub_ajax_consultar() {
    check_ajax_referer('cpfhub_nonce', 'nonce');

    $cpf = isset($_POST['cpf']) ? sanitize_text_field($_POST['cpf']) : '';

    if (empty($cpf)) {
    wp_send_json_error(['message' => 'CPF não informado.']);
    }

    $dados = cpfhub_consultar_cpf($cpf);

    if ($dados) {
    wp_send_json_success($dados);
    } else {
    wp_send_json_error(['message' => 'CPF não encontrado.']);
    }
}

No front-end, registre o script e faça a chamada AJAX:

jQuery(document).ready(function($) {
    $('#cpf-form').on('submit', function(e) {
    e.preventDefault();
    var cpf = $('#cpf-input').val().replace(/\D/g, '');

    $.ajax({
    url: cpfhub_ajax.ajax_url,
    type: 'POST',
    timeout: 30000,
    data: {
    action: 'cpfhub_consultar',
    nonce: cpfhub_ajax.nonce,
    cpf: cpf
    },
    success: function(response) {
    if (response.success) {
    $('#resultado').html(
    '<p>Nome: ' + response.data.name + '</p>' +
    '<p>Nascimento: ' + response.data.birthDate + '</p>'
    );
    } else {
    $('#resultado').html('<p>' + response.data.message + '</p>');
    }
    },
    error: function() {
    $('#resultado').html('<p>Erro ao consultar. Tente novamente.</p>');
    }
    });
    });
});

7. Implementando cache com Transients API

O WordPress possui a Transients API, ideal para armazenar resultados temporários de chamadas externas. Isso reduz o consumo de consultas na API, especialmente útil no plano gratuito com 50 consultas mensais:

function cpfhub_consultar_cpf_cache(string $cpf, int $expiracao = 86400): ?array {
    $cpf_limpo = preg_replace('/\D/', '', $cpf);
    $cache_key = 'cpfhub_' . $cpf_limpo;

    $cached = get_transient($cache_key);
    if ($cached !== false) {
    return $cached;
    }

    $dados = cpfhub_consultar_cpf($cpf_limpo);

    if ($dados) {
    set_transient($cache_key, $dados, $expiracao);
    }

    return $dados;
}

O transient expira após 24 horas (86400 segundos) por padrão, mas você pode ajustar conforme a necessidade do seu projeto.

8. Boas práticas de segurança

Ao integrar APIs externas no WordPress, siga estas recomendações:

• Sanitize todas as entradas — Utilize sanitize_text_field() para limpar dados recebidos de formulários.

• Use nonces em requisições AJAX — A função check_ajax_referer() protege contra ataques CSRF.

• Escape todas as saídas — Utilize esc_html() ao exibir dados da API no front-end.

• Armazene chaves de forma segura — Prefira wp-config.php em vez de armazenar no banco de dados.

• Use a Transients API — Reduza chamadas externas com cache, sem comprometer a atualização dos dados.

Perguntas frequentes

Por que usar wp_remote_get em vez de curl ou file_get_contents no WordPress?

wp_remote_get é a abstração HTTP nativa do WordPress. Ela respeita configurações de proxy do servidor, é compatível com filtros do core, funciona em ambientes com cURL desabilitado e facilita testes com mocks. Usar funções nativas garante compatibilidade com o ecossistema de plugins e com atualizações futuras do WordPress.

Como o cache com Transients API afeta a precisão dos dados de CPF?

Os dados retornados pela API (nome, data de nascimento, gênero) raramente mudam. Um TTL de 24 horas é seguro para a maioria dos casos. Para situações onde a precisão em tempo real é obrigatória — como verificações antifraude — desative o cache ou use TTL de minutos.

A API da CPFHub.io bloqueia requisições vindas de WordPress quando o limite é atingido?

Não. A API nunca bloqueia — quando o limite mensal de consultas é atingido, ela continua respondendo normalmente e cobra R$0,15 por consulta adicional. Não há interrupção de serviço, independentemente do volume.

Como integrar a validação de CPF com formulários do WooCommerce?

Use o hook woocommerce_checkout_process para chamar cpfhub_consultar_cpf antes de processar o pedido. Se a API retornar success: false, adicione um erro com wc_add_notice e impeça a conclusão do checkout. Combine com o cache de Transients para evitar chamadas duplicadas no mesmo CPF. A ANPD recomenda informar ao cliente sobre o uso dos dados antes da coleta.

Conclusão

Integrar a consulta de CPF em WordPress é uma tarefa acessível quando utilizamos as funções nativas da plataforma, como wp_remote_get e a Transients API para cache. Essas abordagens seguem as melhores práticas do ecossistema WordPress e garantem compatibilidade com plugins e temas de terceiros.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito.