Um cliente faz uma encomenda e o administrador deixa uma nota no painel de administração: esclareceu a data de entrega, adicionou um número de rastreamento ou simplesmente escreveu «ligar antes de enviar». Mas o cliente não vê isto. As notas de encomenda no WooCommerce existem apenas no painel de administração por defeito, na barra lateral de edição da encomenda. Não aparecem nos e-mails enviados ao comprador.

O problema resolve-se com um único snippet no functions.php. Sem plugins, sem edição de templates, apenas um hook limpo que exibe as notas no corpo do e-mail. Na prática, temos usado esta abordagem em lojas de clientes há vários anos, sem falhas após atualizações do WooCommerce. Neste guia, vamos ver como o WooCommerce armazena as notas de encomenda, que hook usar e como personalizar o resultado para as suas necessidades.

💡 Resumo rápido:

• Como o WooCommerce armazena as notas de encomenda: o tipo de comentário order_note e a função wc_get_order_notes()
• Duas abordagens para personalização de e-mails: substituição de templates ou hooks, e quando escolher cada uma
• Um snippet pronto a usar para mostrar notas no e-mail de encomenda concluída, com uma explicação linha a linha
• Personalização: estilizar a lista, filtrar apenas notas de cliente, suportar e-mails em texto simples
• Testes através da pré-visualização de e-mail no painel de administração, sem enviar spam para clientes reais

Passo 1: Como o WooCommerce armazena as notas de encomenda

O WooCommerce armazena as notas como comentários do WordPress do tipo order_note. Cada ação numa encomenda (mudança de estado, reembolso, nota de administrador ou mensagem de cliente) é registada na tabela wp_comments com a flag comment_type = 'order_note'.

A diferença entre notas internas e de cliente é determinada pelo campo meta is_customer_note. Se a caixa de seleção «Visível na Minha Conta» estiver ativada ao adicionar uma nota, o WooCommerce define is_customer_note = true e o comprador vê-la na sua conta. As notas internas normais (is_customer_note = false) não são mostradas ao cliente em lado nenhum.

Com o lançamento do High Performance Order Storage (HPOS) no WooCommerce 8.2+, as notas passaram para uma tabela separada wp_wc_order_notes. Consultas SQL diretas à wp_comments com o HPOS ativo podem devolver resultados vazios. Portanto, em vez de get_comments(), é melhor usar wc_get_order_notes(), que funciona corretamente independentemente do modo de armazenamento.

Passo 2: Templates ou hooks, que abordagem escolher

O WooCommerce oferece dois caminhos para a personalização de e-mails: substituição de templates e hooks de ação. Cada um tem o seu caso de uso.

Substituição de templates. Copia um ficheiro de woocommerce/templates/emails/ para yourtheme/woocommerce/emails/ e edita o HTML diretamente. A vantagem é o controlo total sobre a marcação. A desvantagem é que, após grandes atualizações do WooCommerce, o seu template pode divergir da versão atual e os e-mails podem começar a falhar. A documentação sobre a estrutura de templates está agora em woocommerce.com, não no antigo docs.woothemes.com.

Hooks. Associa um callback à ação woocommerce_email_order_meta e o WooCommerce chama a sua função no local certo do e-mail. A vantagem é que não depende das versões do template e funciona sem problemas após atualizações do core. A desvantagem é que está limitado à posição do hook (é executado no bloco de metadados da encomenda, após a tabela de produtos).

Para a nossa tarefa de mostrar notas, um hook é mais do que suficiente. Se precisar de redesenhar completamente os layouts de e-mail, use templates e planeie atualizá-los a cada seis meses, aproximadamente.

Passo 3: Adicionar o código ao functions.php

O hook woocommerce_email_order_meta é executado em todos os e-mails transacionais do WooCommerce: confirmação de encomenda, conclusão, cancelamento, fatura e outros. São passados quatro parâmetros ao callback: o objeto da encomenda $order, a flag $sent_to_admin, a flag $plain_text e o objeto do e-mail $email.

Coloque este código no functions.php do seu tema ativo (ou através do plugin Code Snippets, que é mais seguro, pois não se perde ao mudar de tema):

1
add_action( 'woocommerce_email_order_meta', 'sd_add_order_notes_to_email', 10, 4 );
2
 
3
function sd_add_order_notes_to_email( $order, $sent_to_admin, $plain_text, $email ) {
4
    // Don't break the plain-text version of the email
5
    if ( $plain_text ) {
6
        echo "\n\n" . esc_html__( 'Order Notes:', 'woocommerce' ) . "\n";
7
 
8
        $notes = wc_get_order_notes( array(
9
            'order_id' => $order->get_id(),
10
            'type'     => 'customer',
11
        ) );
12
 
13
        if ( empty( $notes ) ) {
14
            echo esc_html__( 'No notes for this order.', 'woocommerce' ) . "\n";
15
            return;
16
        }
17
 
18
        foreach ( $notes as $note ) {
19
            echo '- ' . wp_strip_all_tags( $note->content ) . "\n";
20
        }
21
        return;
22
    }
23
 
24
    // HTML version: get only customer notes
25
    $notes = wc_get_order_notes( array(
26
        'order_id' => $order->get_id(),
27
        'type'     => 'customer',
28
    ) );
29
 
30
    if ( empty( $notes ) ) {
31
        return;
32
    }
33
 
34
    echo '<h2>' . esc_html__( 'Order Notes', 'woocommerce' ) . '</h2>';
35
    echo '<ul class="order-notes-list" style="list-style:none;padding:0;margin:0 0 24px;">';
36
 
37
    foreach ( $notes as $note ) {
38
        $note_date = sprintf(
39
            '%1$s at %2$s',
40
            date_i18n( get_option( 'date_format' ), strtotime( $note->date_created ) ),
41
            date_i18n( get_option( 'time_format' ), strtotime( $note->date_created ) )
42
        );
43
 
44
        printf(
45
            '<li style="background:#f9f9f9;border-left:4px solid #7f54b3;padding:12px 16px;margin-bottom:10px;border-radius:0 4px 4px 0;">'
46
            . '<div style="margin-bottom:4px;">%s</div>'
47
            . '<small style="color:#888;">%s</small>'
48
            . '</li>',
49
            wp_kses_post( nl2br( $note->content ) ),
50
            esc_html( $note_date )
51
        );
52
    }
53
 
54
    echo '</ul>';
55
}

Eis o que acontece linha a linha:

• Linha 1. Registamos o hook com prioridade 10 e aceitamos todos os 4 parâmetros. Sem 10, 4, o WooCommerce passará apenas o primeiro argumento e obterá um erro.
• Linhas 5-20. Tratamento de e-mails em texto simples. Alguns e-mails são enviados em formato de texto, por isso exibimos as notas como uma lista com travessões, sem HTML.
• Linhas 24-28. wc_get_order_notes() solicita apenas notas de cliente (type => 'customer'). Remova o filtro para mostrar todas as notas, incluindo as internas (mudanças de estado, reembolsos). Se o array estiver vazio, não exibimos nada e não poluímos o e-mail.
• Linhas 34-38. Formatamos a data usando date_i18n(), que respeita o locale do site e as definições de formato de data/hora.
• Linhas 40-48. printf() exibe cada nota num bloco estilizado: barra roxa à esquerda, fundo claro, data a cinza por baixo.

O código não usa dependências externas e é compatível com WooCommerce 3.2+ (a função wc_get_order_notes foi introduzida nesta versão) e HPOS (suporte nativo a partir da 8.2+).

Passo 4: Testar sem enviar spam para os clientes

Depois de adicionar o código, não espere por uma encomenda real para testar. O WooCommerce fornece uma pré-visualização de e-mail integrada: WooCommerce → Definições → E-mails → clique em qualquer e-mail → botão «Pré-visualizar» no fundo. Verá o e-mail tanto em HTML como em texto simples, usando uma encomenda real (a mais recente é usada). Se não houver encomendas, crie uma de teste manualmente.

O que verificar:

• Uma nota de cliente com «Visível na Minha Conta» ativado aparece no e-mail;
• Uma nota interna (sem a caixa de seleção) não aparece (se manteve type => 'customer');
• A versão em texto simples do e-mail não está quebrada (alterne através do link abaixo da pré-visualização);
• O bloco de notas não está duplicado nos e-mails de administrador (adicione uma verificação if ( $sent_to_admin ) return; se necessário).

Se estiver a usar o Code Snippets, basta desativar o snippet para reverter. Se editou o functions.php, comente ou apague o código. Não ficam vestígios na base de dados.

⁉️🤔 Perguntas frequentes

Posso mostrar TODAS as notas, não apenas as de cliente?

Sim. Substitua 'type' => 'customer' por 'type' => 'internal' para obter apenas notas internas. Remova completamente o parâmetro type para obter todas as notas. Tenha em mente que as notas internas podem conter informações de serviço (IDs de reembolso, montantes) que os clientes não devem ver. Para a maioria das lojas, 'type' => 'customer' é suficiente. Se quiser separar a exibição, crie dois blocos: primeiro as notas de cliente com o título «Comentários da Encomenda», depois as notas internas sob o título «Detalhes de Processamento» (isto é para e-mails de administrador, usando a flag $sent_to_admin).

O código funciona para um e-mail específico ou para todos?

O hook woocommerce_email_order_meta é executado em todos os e-mails transacionais: Encomenda Concluída, Encomenda em Processamento, Encomenda em Espera, Fatura do Cliente, etc. Se precisar de limitar a exibição apenas ao e-mail de conclusão da encomenda, envolva o código numa verificação:

1
> if ( 'customer_completed_order' !== $email->id ) {
2
>     return;
3
> }
4
> 

A lista completa de IDs de e-mail está disponível na documentação do WooCommerce: customer_completed_order · customer_processing_order · customer_on_hold_order · customer_invoice · customer_refunded_order · customer_new_account · new_order · cancelled_order · failed_order.

É seguro editar o functions.php num site ativo?

Editar o functions.php diretamente é uma abordagem arriscada. Um erro de sintaxe (um parêntese a mais, uma aspa não fechada) fará com que todo o site mostre um ecrã branco. É mais seguro usar o plugin Code Snippets, que permite adicionar snippets PHP através do painel de administração e desativa automaticamente códigos com erros fatais. Uma alternativa é o WPCode (versão gratuita no wordpress.org), que oferece a mesma funcionalidade mais lógica condicional (apenas administrador, apenas páginas específicas). Se ainda assim editar o functions.php, faça uma cópia de segurança do ficheiro e mantenha o acesso FTP à mão. Um ecrã branco resolve-se substituindo o functions.php pelo original da sua cópia de segurança.

As notas estão a duplicar nos e-mails, o que fiz de errado?

Duas causas prováveis. Primeira: adicionou o código tanto no functions.php como através de um plugin de snippets, por isso o hook é executado duas vezes. Mantenha apenas um. Segunda: o seu tema ou outro plugin já está a associar um callback a este mesmo hook. Verifique pesquisando no código do projeto (grep -r "woocommerce_email_order_meta" wp-content/). Se a duplicação for de um plugin, basta remover o seu código. Se for de um tema, envolva o seu callback em remove_action() antes de add_action() para garantir que apenas um handler é executado.

Conclusão: vale a pena adicionar notas aos e-mails dos clientes

A transparência na comunicação é uma das formas mais baratas de reduzir a carga de trabalho do suporte. Quando um cliente vê «Número de rastreamento: X123456789, entrega a 15 de junho» no e-mail, não vai para o chat perguntar «onde está a minha encomenda?». Um snippet, zero plugins, cinco minutos para implementar, e o efeito mede-se em dezenas de tickets poupados por mês.

Se os seus e-mails já estão personalizados via templates, incorpore a exibição das notas diretamente no template em vez de usar um hook. Se usa um plugin de personalização de e-mails (Kadence, YayMail, ShopMagic), cada um tem o seu próprio mecanismo para adicionar blocos dinâmicos, por isso use-o em vez de código.

Experimente com um tipo de e-mail (Encomenda Concluída), teste numa encomenda de teste e, após uma semana, avalie se está a receber menos perguntas repetitivas dos clientes. Quase de certeza que sim.