# Como consumir API de CPF em WordPress com WP_Http

> Aprenda a consumir uma API de consulta de CPF em WordPress usando WP_Http e wp_remote_get. Exemplos com shortcodes, widgets e boas práticas.

**Publicado:** 21/05/2025
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/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**](https://www.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`:

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

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

```php
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**](https://www.cpfhub.io/) retorna um JSON com os dados do titular do CPF:

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

```php
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:

```php
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:

```javascript
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:

```php
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](https://www.gov.br/anpd) recomenda informar ao cliente sobre o uso dos dados antes da coleta.

### 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)
- [Como exibir feedback visual de validação de CPF (cores, ícones, animações)](https://cpfhub.io/blog/como-exibir-feedback-visual-de-validacao-de-cpf-cores-icones-animacoes)

---

## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.