Como Adicionar Campos Customizados no Checkout do WooCommerce sem Plugins

O checkout é a etapa mais crítica de uma loja virtual. Muitas vezes, empresas precisam coletar informações específicas durante a compra — como CPF/CNPJ, inscrição estadual, horário preferencial de entrega ou instruções para embalagem. No entanto, o uso excessivo de plugins para adicionar simples campos pode sobrecarregar o banco de dados, aumentar o tempo de carregamento da página e criar incompatibilidades durante atualizações do sistema.

Neste artigo, você aprenderá a utilizar os hooks nativos do WooCommerce para adicionar campos personalizados de forma limpa, segura e performática, garantindo que os dados sejam armazenados diretamente nos metadados do pedido.

O Problema dos Plugins Genéricos no Checkout

Adicionar plugins de terceiros apenas para alterar o formulário de checkout costuma introduzir scripts desnecessários no front-end, elevando o TTFB (Time to First Byte). Quando a taxa de conversão do e-commerce depende de milissegundos, a manipulação direta do ecossistema do WooCommerce via código é a abordagem ideal.

Guia Prático: Utilizando Hooks Nativos do WooCommerce

Para customizar o checkout mantendo o código modular, dividimos o processo em três etapas: exibição do campo, salvamento dos dados e exibição no painel administrativo.

1. Exibindo o Campo no Formulário

Utilizamos o filtro woocommerce_checkout_fields para injetar o novo campo no grupo de cobrança (billing).

add_filter( 'woocommerce_checkout_fields', 'custom_adicionar_campo_checkout' );

function custom_adicionar_campo_checkout( $fields ) {
    $fields['billing']['billing_documento_adicional'] = array(
        'type'        => 'text',
        'label'       => __( 'Inscrição Estadual / Documento Adicional', 'woocommerce' ),
        'placeholder' => __( 'Informe caso seja pessoa jurídica', 'woocommerce' ),
        'required'    => false,
        'class'       => array('form-row-wide'),
        'clear'       => true,
    );
    return $fields;
}

2. Salvando os Dados nos Metadados do Pedido

Após o envio do formulário, usamos a ação woocommerce_checkout_update_order_meta para persistir o valor no banco de dados.

add_action( 'woocommerce_checkout_update_order_meta', 'custom_salvar_campo_checkout' );

function custom_salvar_campo_checkout( $order_id ) {
    if ( ! empty( $_POST['billing_documento_adicional'] ) ) {
        update_post_meta( $order_id, '_billing_documento_adicional', sanitize_text_field( $_POST['billing_documento_adicional'] ) );
    }
}

Em implementações que realizo para e-commerces de alto volume, asseguro rigorosamente que todas as entradas passem por funções de sanitização como sanitize_text_field(), prevenindo falhas de segurança como Cross-Site Scripting (XSS).

3. Exibindo a Informação na Gestão do Pedido

Para permitir que a equipe de operação consulte a informação no painel do WooCommerce, associamos a exibição à ação woocommerce_admin_order_data_after_billing_address:

add_action( 'woocommerce_admin_order_data_after_billing_address', 'custom_exibir_campo_admin_order', 10, 1 );

function custom_exibir_campo_admin_order( $order ){
    $documento = get_post_meta( $order->get_id(), '_billing_documento_adicional', true );
    if ( $documento ) {
        echo '<p><strong>' . __( 'Documento Adicional' ) . ':</strong> ' . esc_html( $documento ) . '</p>';
    }
}

Boas Práticas de Engenharia no WooCommerce

1. Uso de Child Themes ou Plugin Customizado: Nunca insira regras de negócio no arquivo functions.php do tema pai para evitar a perda de código em atualizações.
2. Tratamento de Validação: Caso o campo seja obrigatório, adicione a ação woocommerce_checkout_process para interceptar e validar os dados antes da criação do pedido.
3. Compatibilidade com Checkout em Blocos: Caso sua loja utilize o Checkout em Blocos (Gutenberg), a extensão deve ser feita através das APIs de extensibilidade JS do WooCommerce.

Precisa de Ajustes Avançados na Sua Loja Virtual?

Personalizações arquiteturais no WooCommerce demandam conhecimento técnico em hooks, desempenho e segurança. Se a sua empresa necessita de integrações complexas com ERPs, otimização de checkout ou desenvolvimento sob medida, entre em contato para avaliarmos uma consultoria técnica adequada à sua operação.