AJAX no WordPress: admin-ajax e REST API na prática

Atualizado em 19/06/2026

AJAX é o que permite a uma página trocar dados com o servidor sem recarregar — curtir um post, filtrar produtos, carregar mais itens, validar um formulário em tempo real. No WordPress há dois caminhos oficiais para isso: o veterano admin-ajax.php, que existe desde os primórdios do painel, e a REST API, incorporada ao núcleo na versão 4.7. Este artigo mostra os dois na prática, com a segurança que eles exigem, e explica em que cenário cada um brilha. Spoiler: a resposta quase nunca é "sempre use X" — é "depende do contexto".

Os dois caminhos, lado a lado

Antes do código, fixe o modelo mental. Ambos recebem uma requisição do navegador e devolvem dados (em geral JSON), mas têm naturezas diferentes:

• admin-ajax.php: um único arquivo que despacha todas as ações AJAX por meio de um parâmetro action. Carrega o ambiente do WordPress a cada chamada e responde sempre via POST/GET para a mesma URL. Simples e direto, ligado à sessão do usuário.
• REST API: cada recurso tem sua própria rota semântica (/wp-json/...), com método HTTP explícito e respostas potencialmente cacheáveis. Mais estruturada, melhor para integrações e leitura em escala.

Caminho 1: admin-ajax.php (o clássico)

O fluxo tem três peças: (1) enfileirar o script e passar a ele a URL do admin-ajax.php e um nonce; (2) o JavaScript que faz a requisição; (3) o handler PHP que valida e responde.

Os hooks wp_ajax_ e wp_ajax_nopriv_

Cada ação é identificada por um nome (ex.: curtir_post) e atendida por hooks dinâmicos:

• wp_ajax_curtir_post — dispara para usuários logados;
• wp_ajax_nopriv_curtir_post — dispara para visitantes deslogados.

Se a funcionalidade for pública, registre os dois apontando para o mesmo handler. Esquecer o nopriv é a causa mais comum de "funciona quando estou logado, mas no site some" — o WordPress simplesmente devolve 0 para o visitante anônimo, porque nenhum hook respondeu àquela ação.

Passo 1 — Enfileirar o JS e passar ajaxurl + nonce

No painel a variável global ajaxurl já existe; no front-end, não. Por isso passamos a URL (sempre via admin_url()) e um nonce ao script com wp_localize_script():

<?php
add_action( 'wp_enqueue_scripts', 'meu_plugin_enfileirar_ajax' );

function meu_plugin_enfileirar_ajax() {
    wp_enqueue_script(
        'meu-ajax',
        plugins_url( 'js/ajax.js', __FILE__ ),
        array(),       // sem dependência de jQuery: usaremos fetch()
        '1.0.0',
        true           // no rodapé
    );

    // Entrega a URL do endpoint e um nonce ao JavaScript.
    wp_localize_script( 'meu-ajax', 'MEU_AJAX', array(
        'url'   => admin_url( 'admin-ajax.php' ),
        'nonce' => wp_create_nonce( 'curtir_post_nonce' ),
    ) );
}

Passo 2 — O JavaScript (fetch)

O front-end faz um POST para a URL recebida, mandando o parâmetro obrigatório action (que casa com o nome do hook, sem o prefixo) e o nonce:

// js/ajax.js
document.querySelector( '.btn-curtir' )?.addEventListener( 'click', async ( ev ) => {
    const botao = ev.currentTarget;
    const postId = botao.dataset.postId;

    // admin-ajax espera dados de formulário (não JSON cru).
    const corpo = new URLSearchParams( {
        action:  'curtir_post',          // = wp_ajax_curtir_post
        post_id: postId,
        _ajax_nonce: MEU_AJAX.nonce,     // nome que o check_ajax_referer lê
    } );

    const resp = await fetch( MEU_AJAX.url, {
        method: 'POST',
        credentials: 'same-origin',      // envia o cookie de login
        body: corpo,
    } );

    const json = await resp.json();
    if ( json.success ) {
        botao.textContent = 'Curtido (' + json.data.total + ')';
    } else {
        console.error( json.data?.mensagem || 'Erro ao curtir.' );
    }
} );

Repare em credentials: 'same-origin': sem isso, o navegador pode não enviar o cookie de sessão, e o WordPress trataria a chamada como deslogada (caindo no hook nopriv). O nome _ajax_nonce é a chave padrão que o check_ajax_referer() procura automaticamente.

Muito código WordPress ainda usa jQuery, que acompanha o núcleo. A mesma requisição com jQuery.post() fica assim — declare jquery como dependência no wp_enqueue_script para garantir que ele já esteja carregado:

// js/ajax.js — versão com jQuery
jQuery( function ( $ ) {
    $( '.btn-curtir' ).on( 'click', function () {
        const botao = $( this );

        $.post( MEU_AJAX.url, {
            action:      'curtir_post',      // = wp_ajax_curtir_post
            post_id:     botao.data( 'postId' ),
            _ajax_nonce: MEU_AJAX.nonce,
        } ).done( function ( res ) {
            if ( res.success ) {
                botao.text( 'Curtido (' + res.data.total + ')' );
            } else {
                console.error( res.data && res.data.mensagem );
            }
        } ).fail( function () {
            console.error( 'Falha de rede no AJAX.' );
        } );
    } );
} );

O jQuery.post() já envia o cookie e serializa os dados como formulário automaticamente, o que torna o código mais enxuto; em projetos novos, porém, fetch() dispensa a dependência. Escolha conforme o que o tema/plugin já carrega — não inclua jQuery só para isso.

Passo 3 — O handler PHP

O handler verifica o nonce, checa permissão quando aplicável, processa e responde com wp_send_json_success() ou wp_send_json_error():

<?php
add_action( 'wp_ajax_curtir_post',        'meu_plugin_curtir_post' );
add_action( 'wp_ajax_nopriv_curtir_post', 'meu_plugin_curtir_post' );

function meu_plugin_curtir_post() {

    // 1) Nonce: barra requisições forjadas (CSRF). Encerra sozinho se falhar.
    check_ajax_referer( 'curtir_post_nonce' );

    // 2) Valide/sanitize a entrada — nunca confie no que chega.
    $post_id = isset( $_POST['post_id'] ) ? absint( $_POST['post_id'] ) : 0;

    if ( ! $post_id || 'publish' !== get_post_status( $post_id ) ) {
        wp_send_json_error(
            array( 'mensagem' => 'Post inválido.' ),
            400 // status HTTP
        );
    }

    // 3) Lógica de negócio (exemplo: incrementar um contador em post meta).
    $total = (int) get_post_meta( $post_id, 'curtidas', true ) + 1;
    update_post_meta( $post_id, 'curtidas', $total );

    // 4) Resposta. wp_send_json_success() imprime o JSON e encerra (wp_die).
    wp_send_json_success( array( 'total' => $total ) );
}

Caminho 2: REST API (o moderno)

Para o mesmo objetivo, a REST API oferece uma rota dedicada em vez de um action genérico. A estrutura, a validação de args e o permission_callback são o tema completo do artigo de REST API do WordPress; aqui fica o contraste essencial — uma rota semântica, com método HTTP explícito:

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'meu-plugin/v1', '/curtir/(?P<id>\d+)', array(
        'methods'             => WP_REST_Server::CREATABLE, // POST
        'callback'            => 'meu_plugin_rest_curtir',
        'permission_callback' => '__return_true',           // leitura/escrita pública (consciente)
        'args'                => array(
            'id' => array(
                'required'          => true,
                'sanitize_callback' => 'absint',
            ),
        ),
    ) );
} );

No navegador, a chamada usa o cabeçalho X-WP-Nonce (em vez de um campo _ajax_nonce no corpo) e uma URL limpa como /wp-json/meu-plugin/v1/curtir/42. A resposta pode trazer cabeçalhos de cache, algo que o admin-ajax.php não oferece de fábrica.

Quando usar cada um

Segurança: as regras que valem para os dois

• Nonce sempre. No admin-ajax, check_ajax_referer(); na REST API, o X-WP-Nonce. Sem isso, qualquer site pode forjar requisições em nome do seu usuário (CSRF). Entenda o mecanismo em segurança no código.
• Nonce não é autorização. Ele prova a origem, não o direito. Para ações sensíveis, some a verificação com current_user_can().
• Nunca confie na entrada. Todo $_POST/$_GET é hostil até prova em contrário: sanitize com absint, sanitize_text_field, sanitize_email conforme o tipo.
• Escape na saída. Se o handler devolve HTML, escape com esc_html/esc_attr; se devolve JSON, use as funções wp_send_json_*, que cuidam do Content-Type.
• Trate o erro com status HTTP (400, 403...), para o JavaScript reagir corretamente em vez de exibir "sucesso vazio".

Armadilhas comuns (e como evitar)

Esse handler de AJAX normalmente vive em um plugin próprio e se conecta ao enfileiramento correto de assets. Para decidir entre os dois caminhos com mais profundidade, leia a REST API do WordPress e explore os demais temas de desenvolvimento.