Hooks e filtros

Referência completa dos filtros e actions disponíveis pra customizar o Frete Offline. Use pra integrar com lógica de negócio específica do seu site.

Snippets prontos pra usar estão em Snippets PHP.

Filtros — fluxo de cálculo

wc_table_shipping_table_rate

Permite alterar qual arquivo CSV é usado, em tempo real.

apply_filters( 'wc_table_shipping_table_rate', $table, $package, $method );

• $table (int|string) — ID do attachment ou caminho do arquivo.
• $package — dados do pacote.
• $method — instância do método.

Útil pra usar tabelas diferentes por país/região do cliente.

wcts_attached_file

Modifica o path do arquivo depois que o WordPress já o resolveu.

apply_filters( 'wcts_attached_file', $file, $package, $method );

Mais granular que wc_table_shipping_table_rate — atue aqui se você quer apontar pra um arquivo fora da media library.

wcts_matched_rules_extra_data

Adiciona dados extras que serão passados adiante pra outros filtros (wcts_pre_rules, wc_table_shipping_weight, etc).

apply_filters( 'wcts_matched_rules_extra_data', [], $package, $method );

Útil pra calcular algo uma vez (ex: contar itens no carrinho) e reusar em vários hooks.

wcts_pre_rules

Permite interceptar uma regra antes da validação padrão. Vale tanto pro modo CSV quanto pro modo banco de dados.

apply_filters( 'wcts_pre_rules', null, $row, $package, $method, $extra_data );

Retorne:

• null → continua validação normal.
• array → considera linha matched (pula validação).
• false → descarta a linha.

wcts_invalid_rule

Permite aceitar uma linha que falhou na validação de peso.

apply_filters( 'wcts_invalid_rule', false, $package, $method, $row, $map );

Retorne true pra forçar aceitar mesmo com peso fora da faixa.

wcts_ignore_weight_rule

Controla se colisão exata de borda de peso é ignorada (peso = limite máximo de uma linha = limite mínimo da próxima).

apply_filters( 'wcts_ignore_weight_rule', true );

Padrão: true (ignora exatos pra evitar duplicar matches).

wcts_custom_rules (modo CSV) / wcts_custom_rules_database (modo DB)

Adiciona validação personalizada por linha.

// CSV
apply_filters( 'wcts_custom_rules', true, $instance_id, $map, $row, $package );
// DB
apply_filters( 'wcts_custom_rules_database', true, $instance_id, $rate_data, $package );

Retorne true (válido), false (rejeita) ou string de erro.

Filtros — peso e custo

wc_table_shipping_weight_unit

Modifica a unidade de peso usada na comparação.

apply_filters( 'wc_table_shipping_weight_unit', $weight_unit, $package );

wc_table_shipping_weight

Modifica o peso final calculado do carrinho antes de bater com a tabela.

apply_filters( 'wc_table_shipping_weight', $weight, $package, $extra_weight, $weight_unit, $method, $extra_data );

Use pra peso dimensional, multiplicadores, ou capar valores extremos. Exemplo em Snippets PHP.

wcts_cart_contents_cost

Modifica o valor do carrinho usado nas comparações de frete grátis.

apply_filters( 'wcts_cart_contents_cost', $cost, $rate );

Útil quando você quer aplicar desconto antes de checar mínimo de frete grátis.

wc_table_shipping_cost

Modifica o custo final do frete depois de tudo (taxas inclusas).

apply_filters( 'wc_table_shipping_cost', $cost, $rate, $package, $method );

O ponto mais flexível pra reescrever custo. Snippets em Snippets PHP.

wc_table_shipping_free_shipping_matched

Disparado quando uma regra de frete grátis bate.

apply_filters( 'wc_table_shipping_free_shipping_matched', $cost, $postcode, $instance_id, $map, $row, $package );

Cost é 0 por padrão. Você pode forçar valor diferente se quiser sobrescrever a regra.

Filtros — saída e identificação

wc_table_shipping_method_key

Modifica a chave única que identifica o método retornado.

apply_filters( 'wc_table_shipping_method_key', $key, $instance_id, $map, $row );
// ou (DB)
apply_filters( 'wc_table_shipping_method_key', $key, $instance_id, $rate_data );

Padrão: wcts_<instance_id>_<md5_hash_da_linha>. Mude se precisar de chaves estáveis pra integração externa.

wc_table_shipping_rate

Modifica os argumentos do rate final antes de adicionar ao checkout.

apply_filters( 'wc_table_shipping_rate', $args, $rate, $method, $extra_data );

$args tem chaves: id, label, cost, taxes, package, meta_data. Customize aqui pra adicionar metadata específica do método (ver Salvar dados da tabela no pedido).

wc_table_shipping_delimiter

Permite mudar o delimitador padrão do CSV via código.

apply_filters( 'wc_table_shipping_delimiter', ',' );

Filtros — admin (mapeamento de colunas)

wcts_mapping_columns

Adiciona/remove colunas mapeáveis na interface de admin.

apply_filters( 'wcts_mapping_columns', $columns );

Default: zipcode_start, zipcode_end, weight_start, weight_end, cost, delivery_time, label, free_shipping.

wcts_placeholder_columns

Modifica os placeholders dos selects de mapeamento.

apply_filters( 'wcts_placeholder_columns', $placeholders );

wcts_default_column_values

Modifica os valores reconhecidos pela auto-detecção.

apply_filters( 'wcts_default_column_values', $defaults );

Útil pra adicionar variações de nome (em outros idiomas, padrões internos da loja).

wcts_row_importer_parsed_data

Modifica dados parseados do CSV antes de inserir no banco (modo DB).

apply_filters( 'wcts_row_importer_parsed_data', $data, $importer );

wc_table_shipping_form_fields

Adiciona/modifica campos no formulário do método.

apply_filters( 'wc_table_shipping_form_fields', $fields );

Actions

wc_table_shipping_before_method_settings

Disparado antes do form de configurações ser renderizado.

do_action( 'wc_table_shipping_before_method_settings', $post );

wc_table_shipping_after_method_settings

Disparado depois do form.

do_action( 'wc_table_shipping_after_method_settings', $post );

Use pra injetar HTML adicional (ex: link pra documentação interna, instruções da equipe).

Próximos passos

• Snippets PHP — exemplos prontos usando esses hooks.
• Salvar dados da tabela no pedido — recipe específica pro filter wc_table_shipping_rate.