Filtros disponíveis

Os filtros do Correios Updater permitem alterar quase todos os comportamentos do plugin sem editar o código fonte. Esta é a referência completa.

Pra hooks de ação (reagir a eventos), veja Actions disponíveis.

Seleção de pedidos pra verificar

wc_correios_status_updater_get_orders_args

Modifica os argumentos que o plugin passa pro wc_get_orders ao buscar pedidos pra verificar.

apply_filters( 'wc_correios_status_updater_get_orders_args', $args );

Args padrão:

[
    'limit'  => -1,
    'status' => $settings['status_to_check'],
    'return' => 'ids',
]

Exemplo: verificar apenas pedidos pagos com PIX.

add_filter( 'wc_correios_status_updater_get_orders_args', function( $args ) {
    $args['meta_query'] = [
        [
            'key'   => '_payment_method',
            'value' => 'pix',
        ],
    ];
    return $args;
});

wc_correios_status_updater_tracking_code

Modifica o array de códigos de rastreio extraídos pra um pedido. É o jeito de incluir códigos vindos de fontes não suportadas nativamente.

apply_filters( 'wc_correios_status_updater_tracking_code',
    $tracking_codes,  // array
    $order,           // WC_Order
    $settings         // array
);

Exemplo: incluir códigos de um campo custom.

add_filter( 'wc_correios_status_updater_tracking_code', function( $codes, $order ) {
    $extra = $order->get_meta( '_meu_codigo_correios' );
    if ( $extra ) {
        $codes[] = $extra;
    }
    return $codes;
}, 10, 2 );

wc_correios_status_updater_run_event

Permite pular o processamento pra um pedido específico, mesmo que ele esteja na fila.

apply_filters( 'wc_correios_status_updater_run_event',
    true,           // padrão: processar
    $event, $tracking_code, $order
);

Exemplo: pular pedidos marcados como teste.

add_filter( 'wc_correios_status_updater_run_event', function( $run, $event, $code, $order ) {
    return $order->get_meta( '_skip_correios' ) ? false : $run;
}, 10, 4 );

Cron e fila

correios_updater_cron_interval

Intervalo (em minutos) entre rodadas automáticas. Padrão: 180 (3 horas).

add_filter( 'correios_updater_cron_interval', function() {
    return 60; // verifica a cada hora
});

Classificação de eventos

Cada categoria de evento tem um filtro próprio pra mudar a lógica de detecção. Útil pra integrar transportadoras alternativas que retornam descrições diferentes, ou pra refinar comportamentos específicos.

wc_correios_status_updater_is_delivered

Define o que conta como "entregue".

add_filter( 'wc_correios_status_updater_is_delivered', function( $is_delivered, $event ) {
    if ( strpos( $event['descricao'], 'Texto custom de entrega' ) !== false ) {
        return true;
    }
    return $is_delivered;
}, 10, 2 );

wc_correios_status_updater_is_failed

Define o que conta como falha de entrega.

wc_correios_status_updater_is_waiting_pickup

Define o que conta como aguardando retirada.

wc_correios_status_updater_is_not_delivered

Define o que conta como pedido não entregue.

wc_correios_status_updater_is_delivery_route

Define o que conta como saiu pra entrega.

Todos têm a mesma assinatura: recebem $is_X (boolean atual) e $event (array). Retornam boolean.

E-mails

wc_correios_status_updater_trigger_email

Permite suprimir o envio do e-mail do cliente em casos específicos.

apply_filters( 'wc_correios_status_updater_trigger_email',
    true,                  // padrão: enviar
    $events, $tracking_code, $order
);

Exemplo: não notificar pedidos B2B.

add_filter( 'wc_correios_status_updater_trigger_email', function( $send, $events, $code, $order ) {
    return $order->get_meta( '_is_b2b' ) ? false : $send;
}, 10, 4 );

wc_correios_status_updater_notification_allowed_for_order

Controla a janela de tempo em que pedidos recebem notificação. Por padrão: pedidos com mais de 40 dias não recebem mais e-mail.

apply_filters( 'wc_correios_status_updater_notification_allowed_for_order',
    ( time() - ( DAY_IN_SECONDS * 40 ) < $order->get_date_created()->getTimestamp() )
);

Exemplo: notificar todos, sem limite de idade.

add_filter( 'wc_correios_status_updater_notification_allowed_for_order', '__return_true' );

wc_correios_status_updater_tracking_update_message

Modifica a mensagem do e-mail do cliente depois dos placeholders serem processados.

apply_filters( 'wc_correios_status_updater_tracking_update_message',
    $formatted_message,
    $order_object
);

wc_correios_status_updater_tracking_update_failed

Modifica a mensagem do e-mail de falha pro admin.

Anotações no pedido

wc_correios_status_updater_add_order_note

Liga ou desliga as notas internas que o plugin adiciona em cada atualização. Útil em lojas com volume muito alto onde notas excessivas poluem o histórico.

apply_filters( 'wc_correios_status_updater_add_order_note', true );

Exemplo: desligar notas de notificação.

add_filter( 'wc_correios_status_updater_add_order_note', '__return_false' );

Configurações globais

wc_correios_status_updater_settings

Modifica o array completo de configurações do plugin antes de ser usado em runtime. Útil pra forçar valores em ambientes específicos (staging vs produção).

apply_filters( 'wc_correios_status_updater_settings', $settings );

Exemplo: forçar log ligado em staging.

add_filter( 'wc_correios_status_updater_settings', function( $settings ) {
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        $settings['enable_log'] = 'yes';
    }
    return $settings;
});

wc_correios_status_updater_status_to_check

Modifica especificamente o array de status verificados.

wc_correios_status_updater_status_after_delivery

Modifica especificamente o status final pós-entrega.

Veja também

• Actions disponíveis — pra reagir a eventos.
• Funções auxiliares — pra usar dentro dos seus filtros.