Actions disponíveis

O Correios Updater dispara hooks de ação pra você plugar comportamento custom em momentos chave. Esta página lista cada um, quando dispara e exemplos práticos.

Pra hooks de filtro (alterar dados em vez de reagir a eventos), veja Filtros disponíveis.

wc_correios_status_updater_handle_last_event

Dispara toda vez que um evento dos Correios é processado pra um pedido — antes de qualquer alteração de status ou envio de e-mail. É o gancho mais usado pra integrações externas.

do_action( 'wc_correios_status_updater_handle_last_event',
    $event,           // array com os dados do evento atual
    $tracking_code,   // string do código de rastreio
    $order,           // WC_Order
    $order_id,        // int
    $events           // array com todos os eventos retornados pelos Correios
);

Casos de uso

• Sincronizar com ERP / WMS externo.
• Logar dados de rastreio em uma tabela própria.
• Disparar webhook pra um serviço de atendimento.

Exemplo

add_action( 'wc_correios_status_updater_handle_last_event', function( $event, $tracking_code, $order ) {
    wp_remote_post( 'https://meu-erp.example.com/api/shipment', [
        'body' => json_encode([
            'order_id'      => $order->get_id(),
            'tracking_code' => $tracking_code,
            'descricao'     => $event['descricao'],
            'data'          => $event['dtHrCriado'],
        ]),
        'headers' => [ 'Content-Type' => 'application/json' ],
    ] );
}, 10, 3 );

wc_correios_status_updater_order_delivered

Dispara quando todos os pacotes do pedido foram entregues. Se o pedido tem múltiplos códigos de rastreio, só dispara depois que todos foram marcados como entregues — não dispara um por código.

do_action( 'wc_correios_status_updater_order_delivered', $order_id );

Casos de uso

• Mandar e-mail de pesquisa de satisfação.
• Dar baixa em estoque consignado.
• Programar envio de e-mail de "como foi sua experiência?" 7 dias depois.
• Atualizar sistema de fidelidade do cliente.

Exemplo

add_action( 'wc_correios_status_updater_order_delivered', function( $order_id ) {
    $order = wc_get_order( $order_id );

    // Agenda e-mail de pesquisa pra 7 dias depois
    wp_schedule_single_event(
        time() + ( 7 * DAY_IN_SECONDS ),
        'minha_loja_enviar_pesquisa_satisfacao',
        [ $order_id ]
    );
});

Hooks de cron / fila

correios_updater_queue

Hook do cron do WordPress. Dispara a montagem da fila de pedidos pra verificação. Não use direto — a chamada manual via do_action( 'correios_updater_queue' ) ignora o cancelamento de tarefas pendentes e pode causar duplicação.

Pra forçar uma rodada, use a interface de configurações ou a URL ?correios-updater-force-cron (veja Fila e cron).

correios_updater_handle_event

Hook do Action Scheduler executado pra cada pedido individual. Também não é pra uso direto — é o que o plugin agenda internamente quando popula a fila.

Veja também

• Filtros disponíveis — pra mudar comportamento (e não só reagir).
• Funções auxiliares — helpers pra usar dentro dos seus actions.
• Fila e cron — entender o ciclo de execução.