🏪 Estados de encomenda personalizados no WooCommerce: como criar e configurar

Processámos a encomenda, mas não existe um estado padrão para esta fase. «Em processamento» para a montagem, «Concluída» para a expedição e um vazio pelo meio. A loja está a crescer e os sete estados predefinidos do WooCommerce já não são suficientes.

Pode adicionar um estado personalizado de duas formas: com um par de linhas de código no functions.php ou com um plugin pronto a usar. Ambas as abordagens funcionam e não quebram a lógica padrão das encomendas. A seguir, passo a passo, com código testado e uma alternativa sem programação.

💡 Visão geral rápida:

• Que estados vêm com o WooCommerce de origem e porque são insuficientes
• Registar um estado personalizado através de código PHP
• Adicionar vários estados e notificações de email personalizadas
• Plugins para estados de encomenda quando o código não é adequado
• Respostas a perguntas comuns: HPOS, cores, eliminação, tradução

Que estados vêm com o WooCommerce de origem

Por predefinição, o WooCommerce fornece sete estados de encomenda. Cada um está intimamente ligado a um ponto específico do ciclo de vida:

Para uma loja típica, este conjunto é suficiente. Mas assim que surge uma lógica de processamento personalizada, como produção por encomenda ou entrega em várias etapas, sete estados já não chegam. Precisa de «Em montagem», «Entregue ao transportador», «A aguardar pré-pagamento» ou «Requer verificação do gestor».

Passo 1: registar um estado personalizado através de código

Antes do WooCommerce 3.0, os estados usavam a taxonomia shop_order_status e adicionar um novo não era trivial. Agora é mais simples: um estado de encomenda é um estado de publicação do tipo de publicação personalizado shop_order. É registado com uma única função register_post_status() e o filtro wc_order_statuses.

O código é adicionado ao functions.php do tema filho. Antes de qualquer edição, faça uma cópia de segurança completa do site.**

1
// Registering a new order status
2
function sdstudio_register_custom_order_status() {
3
    register_post_status( 'wc-preparing', array(
4
        'label'                     => 'In assembly',
5
        'public'                    => true,
6
        'exclude_from_search'       => false,
7
        'show_in_admin_all_list'    => true,
8
        'show_in_admin_status_list' => true,
9
        'label_count'               => _n_noop(
10
            'In assembly (%s)',
11
            'In assembly (%s)',
12
            'sdstudio'
13
        ),
14
    ) );
15
}
16
add_action( 'init', 'sdstudio_register_custom_order_status' );
17
 
18
// Adding status to WooCommerce list
19
function sdstudio_add_custom_order_status( $order_statuses ) {
20
    $order_statuses['wc-preparing'] = 'In assembly';
21
    return $order_statuses;
22
}
23
add_filter( 'wc_order_statuses', 'sdstudio_add_custom_order_status' );

Depois de guardar o functions.php, o novo estado aparecerá no menu suspenso de estado da encomenda no painel de administração e nos relatórios do WooCommerce. O sistema vê-o como um estado completo, pode filtrar encomendas, alterar o estado manualmente e usá-lo em hooks.

O que está a acontecer aqui

A função register_post_status() cria um novo estado de publicação com o prefixo wc-, uma convenção do WooCommerce. O parâmetro label define o nome legível no painel de administração. O label_count, através de _n_noop(), trata da exibição correta dos contadores na interface em português.

O filtro wc_order_statuses adiciona o estado ao array que o WooCommerce usa para construir a lista. Sem este passo, o estado será registado no sistema, mas não aparecerá no menu suspenso de encomendas.

Visualmente, o resultado é exatamente assim, o novo estado é exibido na lista geral juntamente com os padrão.

Passo 2: adicionar vários estados e notificações de email

Para um estado, o código acima funciona perfeitamente. Se precisar de vários, basta duplicar o register_post_status() dentro da mesma função e adicionar uma entrada ao array $order_statuses. Por exemplo, para uma loja com produção por encomenda:

1
function sdstudio_register_multiple_statuses() {
2
    // Status "In production"
3
    register_post_status( 'wc-in-production', array(
4
        'label'                     => 'In production',
5
        'public'                    => true,
6
        'exclude_from_search'       => false,
7
        'show_in_admin_all_list'    => true,
8
        'show_in_admin_status_list' => true,
9
        'label_count'               => _n_noop(
10
            'In production (%s)',
11
            'In production (%s)',
12
            'sdstudio'
13
        ),
14
    ) );
15
 
16
    // Status "Ready to ship"
17
    register_post_status( 'wc-ready-to-ship', array(
18
        'label'                     => 'Ready to ship',
19
        'public'                    => true,
20
        'exclude_from_search'       => false,
21
        'show_in_admin_all_list'    => true,
22
        'show_in_admin_status_list' => true,
23
        'label_count'               => _n_noop(
24
            'Ready to ship (%s)',
25
            'Ready to ship (%s)',
26
            'sdstudio'
27
        ),
28
    ) );
29
}
30
add_action( 'init', 'sdstudio_register_multiple_statuses' );
31
 
32
function sdstudio_add_multiple_statuses( $order_statuses ) {
33
    $order_statuses['wc-in-production'] = 'In production';
34
    $order_statuses['wc-ready-to-ship'] = 'Ready to ship';
35
    return $order_statuses;
36
}
37
add_filter( 'wc_order_statuses', 'sdstudio_add_multiple_statuses' );

Nota: o identificador do estado (o primeiro argumento de register_post_status) começa sempre por wc-. Sem este prefixo, o WooCommerce não reconhecerá o estado.

Notificações de email para estados personalizados

Por predefinição, o WooCommerce não envia emails ao mudar para um estado personalizado. Para ativar as notificações, adicione o filtro woocommerce_email_actions:

1
function sdstudio_add_custom_status_email( $email_actions ) {
2
    $email_actions[] = 'woocommerce_order_status_wc-preparing';
3
    $email_actions[] = 'woocommerce_order_status_wc-in-production';
4
    return $email_actions;
5
}
6
add_filter( 'woocommerce_email_actions', 'sdstudio_add_custom_status_email' );

Depois disto, pode configurar o modelo de email em WooCommerce → Definições → Emails, o novo estado aparecerá na lista de acionadores para personalização. O modelo é criado no tema filho no caminho woocommerce/emails/, o ficheiro é nomeado seguindo o padrão customer-<status>.php.

Plugins para estados de encomenda: quando o código não é adequado

O código não é o único caminho. Se não quiser editar o functions.php ou precisar de alterar estados com frequência, existem plugins. Duas opções principais:

WooCommerce Order Status Manager, a extensão oficial do WooCommerce. Adiciona uma interface para criar e editar estados diretamente do painel de administração: WooCommerce → Definições → Estados de Encomenda. Suporta notificações de email, ícones, cores e importação/exportação de estados. Pago, incluído em alguns planos do WooCommerce.

Flexi Custom Order Status, um plugin gratuito do catálogo do WordPress.org. Também fornece um editor visual para estados, mas com menos funcionalidades. Adequado para cenários básicos: adicionou um estado, atribuiu uma cor, ativou um email.

Que caminho escolher:

• Precisa de um ou dois estados e não tem receio de código, o functions.php é suficiente.
• Existem muitos estados, mudam com frequência ou o site é gerido por um cliente sem competências técnicas, instale um plugin.
• Está a usar HPOS (High-Performance Order Storage), ambas as abordagens funcionam. Os estados ainda se baseiam no register_post_status(), o HPOS não os afeta.

O pequeno vídeo acima mostra o processo de adicionar um estado personalizado em cinco minutos, desde a instalação do plugin até à primeira utilização nas encomendas.

⁉️🤔 Perguntas comuns

O estado personalizado funciona com HPOS?

Sim, completamente. O HPOS altera a forma como os dados da encomenda são armazenados, mas não mexe no estado da publicação. A função register_post_status() continua a ser o mecanismo principal, o seu código funcionará com o HPOS ativado e desativado.

Pode definir uma cor para um estado personalizado?

Através de código, apenas com estilos CSS no painel de administração: aponte à classe .status-wc-preparing e defina o fundo. Mais conveniente, através de plugins: o Order Status Manager e o Flexi fornecem seleção visual de cores sem uma única linha de código.

Como eliminar um estado criado?

Remova-o do register_post_status() e do filtro wc_order_statuses. As encomendas com este estado não desaparecerão, permanecerão na base de dados, mas o estado deixará de ser exibido na lista suspensa. Antes de eliminar, mova todas as encomendas com o estado removível para outro para não as perder de vista.

Como traduzir estados para outro idioma?

O parâmetro label no register_post_status() aceita uma string, especifique o nome no idioma pretendido. Se o site for multilingue, envolva a string numa chamada a __() ou _x() com um domínio de texto e traduza através de ficheiros .po/.mo como qualquer outro texto do tema.

O prefixo wc- é obrigatório?

Sim. O WooCommerce filtra os estados por este prefixo. Se registar um estado sem wc-, ele não aparecerá no painel de administração de encomendas. Exceção, plugins: eles próprios adicionam o prefixo ou contornam a filtragem com mecanismos internos.

Pode adicionar um estado personalizado sem código e sem um plugin?

Sem código e sem um plugin, não. O WooCommerce não fornece uma interface para criar estados de origem. O caminho mínimo sem programação, o Flexi Custom Order Status gratuito do catálogo WordPress.org. Instalação com um clique, configuração através do painel de administração.

O que usar para a sua tarefa

Os estados de encomenda personalizados são um daqueles mecanismos do WooCommerce que é fácil ignorar enquanto a loja é pequena. Mas assim que surge produção, logística faseada ou verificação manual de encomendas, sem eles o painel de administração transforma-se num caos de notas vagas.

• Precisa de um ou dois estados e já editou o functions.php antes, o código do passo 1 resolve a tarefa em cinco minutos.
• Precisa de um editor visual e definições de cores para o cliente, Flexi Custom Order Status (gratuito).
• Os estados fazem parte de um processo de negócio complexo com cenários de email e dezenas de etapas, WooCommerce Order Status Manager (extensão oficial).

Verifique qual a abordagem que melhor se adequa a si e adicione hoje o seu primeiro estado personalizado. Se usar um método diferente ou conhecer um plugin que não esteja no artigo, partilhe nos comentários.