Status automáticos baseados em eventos

O Correios Updater traduz os eventos dos Correios em mudanças de status do WooCommerce. Cada categoria de evento cai em um dos cinco status que você configura — entrega, saída pra entrega, aguardando retirada, falha, ou simplesmente "rastreio adicionado".

Esta página explica o que dispara cada um.

Status após inserir código de rastreamento

Quando dispara: assim que uma nota interna do pedido contém "Adicionado o código de rastreamento dos Correios" (ou a versão em inglês "Added a Correios tracking code").

O que muda: o pedido vai pra Status após inserir código de rastreamento. Uma nota é adicionada: "Correios Updater: Rastreio adicionado."

Por que isso é útil: muitas lojas marcam o pedido como "Enviado" / "Despachado" depois que o código aparece. Em vez de fazer isso manualmente, o plugin faz automaticamente.

Status após entrega realizada

Quando dispara: quando o evento mais recente dos Correios contém uma das frases:

• "Objeto entregue ao destinatário"
• "Objeto disponível para retirada em Caixa Postal"
• "Objeto entregue na Caixa de Correios Inteligente"

O que muda:

1. O timestamp da entrega é gravado no meta _wc_correios_status_updater_package_delivered.
2. Uma nota é adicionada com o código de rastreio entregue.
3. Se o pedido tem múltiplos códigos, o plugin verifica se todos já foram entregues antes de mudar o status. Pedido com 2 códigos só muda quando ambos forem entregues.
4. O status do pedido vira Status após entrega realizada.
5. A action wc_correios_status_updater_order_delivered é disparada (útil pra integrações — veja Actions disponíveis).

Status 'Saiu para entrega'

Quando dispara: evento "Objeto saiu para entrega ao destinatário".

O que muda: o status vira Status 'Saiu para entrega' e uma nota é adicionada.

Status Aguardando Retirada

Quando dispara: evento contém "Objeto aguardando retirada no endereço indicado" ou "Objeto encaminhado para retirada no endereço indicado".

O que muda:

1. O endereço da agência é extraído da resposta dos Correios e formatado.
2. O endereço é salvo no meta correios_updater_address (formato: Rua Exemplo, 123, Centro, Cidade - UF, CEP: 00000000).
3. O status do pedido vira Status Aguardando Retirada.
4. Uma nota é adicionada com o endereço.

Isso é especialmente útil pra notificar o cliente onde ele precisa ir buscar.

Status para Pedido não entregue

Quando dispara: evento bate em mais de 100 cenários de falha. Alguns exemplos:

• "Objeto não entregue - prazo de retirada encerrado"
• "Objeto devolvido ao remetente"
• "Endereço incorreto"
• "Carteiro não atendido"
• "Objeto retido pela alfândega"

O que muda:

1. A descrição da falha é gravada no meta wc_correios_status_not_delivered_message.
2. O status vira Status para Pedido não entregue.
3. Um e-mail é enviado pro admin (não pro cliente — falha é seu problema, não do comprador).
4. Uma nota detalhada é adicionada ao pedido.

Detecção de mudança vs. duplicação

Pra evitar disparar e-mails duas vezes pelo mesmo evento, o plugin guarda o dtHrCriado do evento mais recente em _wc_correios_status_updater_count. Cada execução compara: se o evento mais recente nos Correios é mais novo que o último visto, processa; se não, ignora.

Customizando o que conta como cada categoria

Cada uma das categorias acima tem um filtro PHP que permite mudar a lógica. Veja Filtros disponíveis — busca por wc_correios_status_updater_is_delivered, wc_correios_status_updater_is_failed, etc.

Exemplo: adicionar um texto customizado como "entregue":

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