O Desafio da Coleta de Dados no Checkout do WooCommerce
Lojas virtuais frequentemente precisam coletar informações específicas dos clientes durante o processo de compra, como CNPJ, horário preferencial de entrega ou instruções personalizadas do pedido. A solução mais comum costuma ser a instalação de plugins genéricos de edição de checkout.
No entanto, o uso excessivo de plugins para tarefas simples pode comprometer a velocidade de carregamento da página, gerar conflitos com scripts do tema e prejudicar a taxa de conversão. A abordagem mais eficiente e limpa é utilizar os hooks nativos do próprio ecossistema do WooCommerce.
Por que Utilizar Hooks Nativos em Vez de Plugins?
O WooCommerce foi construído sobre uma arquitetura modular baseada em actions e filters do WordPress. Ao manipular o checkout por meio do arquivo functions.php do seu tema filho (ou via plugin corporativo interno), você garante:
- Alta Performance: Menos scripts JS e CSS externos sendo carregados.
- Segurança: Controle total sobre a sanitização e validação dos dados inseridos pelo usuário.
- Compatibilidade: Menor risco de quebra de layout após atualizações do WooCommerce.
Passo a Passo Técnico para Adicionar um Campo Personalizado
A estrutura básica para adicionar e processar um novo campo envolve quatro etapas essenciais: exibição no formulário, validação, gravação nos metadados do pedido e exibição no painel administrativo.
1. Adicionando o Campo no Formulário de Checkout
Utilizamos o filtro woocommerce_checkout_fields para injetar o novo campo na seção desejada (faturamento, entrega ou notas do pedido).
add_filter( 'woocommerce_checkout_fields', 'tp_adicionar_campo_checkout' );
function tp_adicionar_campo_checkout( $fields ) {
$fields['billing']['billing_instrucoes_entrega'] = array(
'type' => 'text',
'label' => 'Instruções de Entrega',
'placeholder' => 'Ex: Entregar em horário comercial',
'required' => false,
'class' => array('form-row-wide'),
'clear' => true,
);
return $fields;
}
2. Validando a Entrada dos Dados
Se o campo for obrigatório ou exigir um formato específico, a validação é feita através da action woocommerce_checkout_process.
add_action( 'woocommerce_checkout_process', 'tp_validar_campo_checkout' );
function tp_validar_campo_checkout() {
if ( isset($_POST['billing_instrucoes_entrega']) && empty($_POST['billing_instrucoes_entrega']) ) {
wc_add_notice( 'Por favor, preencha as instruções de entrega.', 'error' );
}
}
3. Salvando os Dados nos Metadados do Pedido
Em implementações que realizo para lojas de alto volume, garanto que todos os dados personalizados sejam armazenados como meta dados do pedido usando woocommerce_checkout_update_order_meta. Isso preserva as informações mesmo se a conta do usuário for alterada posteriormente.
add_action( 'woocommerce_checkout_update_order_meta', 'tp_salvar_campo_checkout' );
function tp_salvar_campo_checkout( $order_id ) {
if ( ! empty( $_POST['billing_instrucoes_entrega'] ) ) {
update_post_meta( $order_id, '_billing_instrucoes_entrega', sanitize_text_field( $_POST['billing_instrucoes_entrega'] ) );
}
}
4. Exibindo o Dado no Painel do Admin
Para que a equipe de operação visualize o campo dentro do pedido no painel do WordPress, utiliza-se a action woocommerce_admin_order_data_after_billing_address.
add_action( 'woocommerce_admin_order_data_after_billing_address', 'tp_exibir_campo_admin', 10, 1 );
function tp_exibir_campo_admin( $order ) {
$instrucoes = get_post_meta( $order->get_id(), '_billing_instrucoes_entrega', true );
if ( $instrucoes ) {
echo '<p><strong>Instruções de Entrega:</strong> ' . esc_html( $instrucoes ) . '</p>';
}
}
Processo de Aplicação e Boas Práticas
Para garantir que a alteração seja feita de forma segura no seu ambiente de produção:
- Ambiente de Staging: Realize as alterações primeiro em um ambiente de testes.
- Uso de Child Theme: Nunca adicione códigos diretamente no tema principal para evitar perda de dados em atualizações.
- Sanitização de Dados: Sempre utilize funções nativas do WordPress como
sanitize_text_field()para evitar vulnerabilidades de segurança.
Precisa de Regras Complexas no Checkout do Seu WooCommerce?
Personalizações avançadas de checkout, como campos condicionais, validação de documentos (CPF/CNPJ) e integração com APIs externas, exigem planejamento arquitetural e conhecimento profundo do ecossistema WordPress.
Se a sua loja precisa de uma solução sob medida sem comprometer a performance ou a segurança, entre em contato para avaliarmos o seu projeto de desenvolvimento ou consultoria técnica.
