Atualizado em: 23 de Abril de 2026

Documentação: RP

Rastreio de Pedidos para WooCommerce (WooTatitas) — Guia de Integração para Desenvolvedores

Guia rápido para programadores que desejam usar este plugin como base em seus projetos.

Aviso importante

Este plugin pode mudar funcionalidades sem aviso prévio para acompanhar atualizações do WooCommerce.

Toda customização é de responsabilidade do desenvolvedor. Não edite os arquivos originais do plugin. Faça suas alterações em código externo:

um plugin próprio (preferencialmente must‑use),
um plugin adicional do seu projeto, ou
o functions.php de um tema filho.
Utilize hooks (actions/filters) documentados. Alterações diretas no plugin serão sobrescritas em atualizações.

1. Visão geral

Este plugin adiciona rastreio de pedidos ao WooCommerce em duas frentes principais: uma interface administrativa dentro do pedido para cadastrar transportadora e código de rastreio, e uma interface pública de consulta via shortcode no frontend.

A integração confirmada no código é centrada em WooCommerce, metadados de pedido, um shortcode público e um endpoint AJAX público usado pela consulta de rastreio. Também existe suporte a múltiplos rastreios por pedido, o que permite cenário de entrega dividida.

Para desenvolvedores, o uso mais seguro do plugin é integrar com a estrutura atual de metadados do pedido, reaproveitar o shortcode público quando possível e, quando necessário, consumir o endpoint AJAX já existente para montar experiências próprias no frontend.

2. Pré-requisitos

Requisitos confirmados no plugin:

WordPress 6.0 ou superior
PHP 8.0 ou superior
WooCommerce ativo
WordPress não pode estar em modo Multisite
Usuário com capacidade manage_woocommerce para acessar as configurações e editar rastreios no admin
Compatibilidade declarada com HPOS do WooCommerce (custom_order_tables)

3. Arquitetura de integração

O fluxo confirmado no plugin é este:

1. O plugin carrega um bootstrap próprio em plugins_loaded.

2. No admin:

cria submenu dentro do hub WooTatitas
adiciona a tela de licença e configurações
adiciona um bloco de rastreio na edição do pedido
salva os dados de rastreio em metadados do pedido
gera uma nota visível ao cliente ao salvar rastreios pelo admin

3. No frontend:

registra o shortcode [rastreio_de_pedidos]
carrega JS e CSS apenas quando o shortcode está presente
usa AJAX para consultar o pedido
valida o pedido com base no número do pedido e nos 4 últimos dígitos do celular de cobrança

Pontos públicos confirmados para integração:

action própria de bootstrap
shortcode público
endpoint AJAX público para consulta
metadado _rastreio_info no pedido
option pública de transportadoras habilitadas
objeto JS localizado no frontend

Limites entre público e interno:

Público e integrável: shortcode, AJAX de consulta, metadados de rastreio, opções de transportadoras e comportamento do frontend
Interno e não documentado aqui: licenciamento, updater privado, rechecagens de licença, limpeza, logs internos e rotinas administrativas auxiliares que não foram claramente pensadas como API externa

4. Hooks disponíveis para desenvolvedores

wootatitas_rp_bootstrap

Tipo: Action
Quando é executado: Em plugins_loaded, prioridade 5, no bootstrap mínimo do plugin.

Parâmetros: Nenhum
Retorno: Não se aplica

Exemplo de uso:

add_action( ‘wootatitas_rp_bootstrap’, function () {
if ( shortcode_exists( ‘rastreio_de_pedidos’ ) ) {
// Seu código complementar aqui.
}
} );

5. Funções, métodos ou APIs públicas para integração

[rastreio_de_pedidos]

Finalidade: Exibir o formulário público de consulta de rastreio.
Como usar: Insira o shortcode em uma página, post ou bloco de shortcode. O plugin renderiza o formulário e, quando o usuário envia os dados, consulta o pedido via AJAX.

Parâmetros: Nenhum

Retorno: HTML do formulário de rastreio, com integração ao JS do plugin

Exemplo de uso:

echo do_shortcode( ‘[rastreio_de_pedidos]’ );

6. Endpoints, AJAX, REST API ou Webhooks

get_order_status

Tipo: AJAX
Finalidade: Consultar o status do pedido e os rastreios vinculados a ele no frontend.
Método: POST

Parâmetros aceito:

action (string) — deve ser get_order_status
order_id (int) — ID do pedido
phone_last_4 (string) — 4 últimos dígitos do telefone de cobrança
nonce (string) — nonce gerado com wp_create_nonce( ‘wootatitas_rp_public’ )

Resposta esperada:

Em sucesso, retorna status do pedido, título contextual, endereço formatado e lista de rastreios
Em erro, retorna mensagem de falha

Autenticação necessária:

Não exige usuário logado
Exige nonce válido
Exige correspondência com os 4 últimos dígitos do telefone de cobrança
Tem limitação simples por IP: mais de 20 tentativas em 10 minutos retorna bloqueio temporário

Exemplo de requisição:

jQuery.ajax({
url: WootatitasData.ajaxurl,
type: ‘POST’,
dataType: ‘json’,
data: {
action: ‘get_order_status’,
order_id: 1234,
phone_last_4: ‘7890’,
nonce: WootatitasData.nonce
}
});

Exemplo de resposta:

{
“success”: true,
“data”: {
“order_status”: “Processando”,
“status_title”: “Será entregue para:”,
“address_html”: “Rua Exemplo, 123
Bairro Exemplo
São Paulo – SP”,
“items”: [
{
“transportadora”: “Correios”,
“rastreio”: “AB123456789BR”
},
{
“transportadora”: “Jadlog”,
“rastreio”: “987654321”
}
]
}
}

7. Estruturas de dados relevantes

7.1. Shortcode público

Item	Valor
Shortcode	`[rastreio_de_pedidos]`
Finalidade	consulta pública de rastreio
Dependência	WooCommerce + licença válida

7.2. Objeto JS localizado no frontend

Quando o shortcode está presente, o plugin localiza o objeto global WootatitasData:

Chave	Tipo	Descrição
`ajaxurl`	string	URL de `admin-ajax.php`
`error_message`	string	mensagem genérica de erro
`nonce`	string	nonce para a action AJAX pública

7.3. Metadado principal do pedido

O plugin usa _rastreio_info como estrutura principal de rastreio. Formato atual confirmado:

array(
‘Correios’ => array(
‘AB123456789BR’,
‘CD987654321BR’,
),
‘Jadlog’ => array(
‘987654321’,
),
)

Meta key	Tipo	Uso
`_rastreio_info`	array	estrutura principal de rastreios por transportadora

Observação importante: a UI do admin normaliza formatos antigos apenas para exibição. Para integrações novas, grave o formato atual acima.

7.4 Metadados legados usados em recuperação

A tela de configurações possui uma rotina de recuperação baseada em dados antigos ou incompletos. Os seguintes metas são lidos nessa rotina:

Meta key	Uso
`_transportadora_responsavel`	dado legado de transportadora
`_numero_rastreio`	dado legado de rastreio

Esses dois campos não são a estrutura principal atual do plugin.

7.5 Option de transportadoras habilitadas

O plugin salva as transportadoras em uma única option:

Option name	Tipo	Uso
`wootatitas_transportadoras_options`	array	flags de transportadoras habilitadas

Chaves confirmadas nessa option:

Chave	Tipo
`azulcargo_enabled`	int
`buslog_enabled`	int
`correios_enabled`	int
`dhl_enabled`	int
`jadlog_enabled`	int
`jtexpress_enabled`	int
`latamcargo_enabled`	int
`loggi_enabled`	int
`transmariano_enabled`	int
`totalexpress_enabled`	int
`uber_enabled`	int

7.6 Transportadoras suportadas no código atual

Slug interno	Nome exibido
`azulcargo`	Azul Cargo
`buslog`	Buslog
`correios`	Correios
`dhl`	DHL
`jadlog`	Jadlog
`jtexpress`	J&T Express
`latamcargo`	Latam Cargo
`loggi`	Loggi
`transmariano`	Transmariano
`totalexpress`	Total Express
`uber`	Uber

7.7 Efeito colateral confirmado ao salvar pelo admin

Quando o rastreio é salvo pela tela administrativa do pedido, o plugin:

atualiza _rastreio_info
evita duplicar a mesma nota já existente
cria uma nota do pedido visível ao cliente com os dados consolidados do rastreio

8. Exemplos práticos de integração

Exemplo 1: renderizar o formulário de rastreio em template PHP

if ( shortcode_exists( ‘rastreio_de_pedidos’ ) ) {
echo do_shortcode( ‘[rastreio_de_pedidos]’ );
}

Exemplo 2: consultar o rastreio em uma interface JS própria

jQuery.ajax({
url: WootatitasData.ajaxurl,
type: ‘POST’,
dataType: ‘json’,
data: {
action: ‘get_order_status’,
order_id: 1234,
phone_last_4: ‘7890’,
nonce: WootatitasData.nonce
}
}).done(function(response) {
if (!response.success) {
console.warn(response.data);
return;
}

console.log(response.data.items);
});

Exemplo 3: gravar rastreio programaticamente no formato atual

$order_id = 1234;

$rastreio_info = array(
‘Correios’ => array(
‘AB123456789BR’,
),
‘Jadlog’ => array(
‘987654321’,
),
);

update_post_meta( $order_id, ‘_rastreio_info’, $rastreio_info );

Exemplo 4: ler os rastreios já salvos em um pedido

$order_id = 1234;
$rastreio_info = get_post_meta( $order_id, ‘_rastreio_info’, true );

if ( is_array( $rastreio_info ) ) {
foreach ( $rastreio_info as $transportadora => $codigos ) {
foreach ( (array) $codigos as $codigo ) {
echo esc_html( $transportadora . ‘: ‘ . $codigo ) . ‘
‘;
}
}
}

Exemplo 5: habilitar transportadoras por código

update_option(
‘wootatitas_transportadoras_options’,
array(
‘correios_enabled’ => 1,
‘jadlog_enabled’ => 1,
‘loggi_enabled’ => 1,
‘azulcargo_enabled’ => 0,
‘buslog_enabled’ => 0,
‘dhl_enabled’ => 0,
‘jtexpress_enabled’ => 0,
‘latamcargo_enabled’ => 0,
‘transmariano_enabled’ => 0,
‘totalexpress_enabled’ => 0,
‘uber_enabled’ => 0,
)
);

9. Boas práticas

Grave rastreios em _rastreio_info no formato atual, por transportadora e lista de códigos.
Não use _transportadora_responsavel e _numero_rastreio como formato principal de escrita em integrações novas.
Ao consumir o AJAX, trate corretamente respostas de erro, especialmente 403 e bloqueio por excesso de tentativas.
Use o shortcode existente quando a necessidade for apenas disponibilizar a consulta ao cliente.
Se criar uma interface própria de consulta, reutilize admin-ajax.php, a action get_order_status e um nonce válido.
Ao integrar com automações logísticas, sanitize transportadora e código antes de salvar no pedido.
Considere que o plugin consulta o telefone de cobrança, não o telefone de entrega.
Se a sua integração precisar notificar o cliente fora da tela administrativa do pedido, implemente esse envio de forma própria. O plugin só confirma no código a criação da nota ao salvar pelo admin.

10. Limitações e observações

O plugin permite integrar:

consulta pública de rastreio por shortcode
consulta pública via AJAX
leitura e escrita do metadado _rastreio_info
habilitação das transportadoras por option
uso do hook wootatitas_rp_bootstrap para carregar complementos

Até o momento, não foram identificados no código:

API REST pública
webhooks públicos
funções PHP públicas específicas para gravar rastreios
template override por tema
blocks do Gutenberg
custom post types
taxonomias próprias
comandos WP-CLI públicos

11. Resumo técnico

O RP expõe uma superfície de integração enxuta e objetiva: shortcode público, AJAX público de consulta, uma option de transportadoras e um metadado principal no pedido.

O nível de extensibilidade é suficiente para integrar páginas de rastreio, frontends personalizados e automações que gravem rastreio diretamente no pedido, mas não há uma API pública ampla em REST, webhook ou helpers dedicados para escrita.

Os principais cuidados são: usar _rastreio_info no formato atual, tratar corretamente a consulta AJAX, não depender dos campos legados como estrutura principal e evitar integração com partes internas que não foram feitas para consumo externo.

Como instalar

Veja nosso guia de como instalar nosso plugin:

Compre nosso plugin

Gostou do que viu? Compre o nosso plugin:

Documentação: RP

Rastreio de Pedidos para WooCommerce (WooTatitas) — Guia de Integração para Desenvolvedores

1. Visão geral

2. Pré-requisitos

3. Arquitetura de integração

4. Hooks disponíveis para desenvolvedores

5. Funções, métodos ou APIs públicas para integração

6. Endpoints, AJAX, REST API ou Webhooks

7. Estruturas de dados relevantes

8. Exemplos práticos de integração

9. Boas práticas

10. Limitações e observações

11. Resumo técnico

Como instalar

Compre nosso plugin

Direto ao ponto

Sem enrolação

WooCommerce Plugins

Wordpress Plugins

Método de Pagamento

Sites em Wordpress

Empresa

Certificados