Estrutura do pacote (campos wcsp_*)

Em todo cálculo de frete por vendedor, o Frete para Marketplace adiciona campos próprios à estrutura de pacote padrão do WooCommerce. Esta página documenta esses campos — útil quando você está escrevendo um filtro custom em cima do split.

A struct completa

Um pacote pós-split tem todos os campos nativos do WooCommerce mais os campos wcsp_* adicionados pelo plugin:

$package = array(
    // === Campos do plugin ===
    'wcsp_vendor_id'       => 123,                    // int — ID do usuário do vendedor
    'wcsp_vendor_name'     => 'Loja do João',         // string — nome da loja
    'wcsp_vendor_postcode' => '01001-000',            // string — CEP de origem do vendedor

    // === Campos nativos do WooCommerce ===
    'contents'             => array( /* itens do vendedor */ ),
    'contents_cost'        => 150.00,
    'applied_coupons'      => array(),
    'destination'          => array(
        'country'   => 'BR',
        'state'    => 'SP',
        'postcode' => '04567-890',
        'city'     => 'São Paulo',
        'address'  => 'Rua...',
        'address_2'=> 'Apt...',
    ),
    'user'                 => array(
        'ID' => 1,
    ),

    // === Campos adicionais por marketplace ===
    'vendor_id'            => 123,         // Dokan, WCFM, WC Marketplace usam essa chave
    'seller_id'            => 123,         // Dokan usa essa chave
    'extra_package_data'   => array( ... ),// Marketplace-specific
);

Os campos wcsp_* em detalhe

wcsp_vendor_id

int — ID do usuário WordPress do vendedor responsável pelo pacote.

Quando usar: quando você precisa identificar qual vendedor é o "dono" do pacote (pra aplicar regras específicas, sobretaxas, descontos, telemetria).

add_filter( 'woocommerce_package_rates', function( $rates, $package ) {
    $vendor_id = $package['wcsp_vendor_id'] ?? null;
    if ( ! $vendor_id ) {
        return $rates;
    }
    // ...
}, 10, 2 );

wcsp_vendor_name

string — nome de exibição da loja do vendedor. É o mesmo nome que aparece no checkout como título do pacote (antes de passar pelo filtro wcsp_package_name).

Quando usar: pra logging, mensagens de erro, integrações que precisam exibir o nome ao cliente sem ter que rebuscar no banco.

wcsp_vendor_postcode

string — CEP de origem do vendedor. É o resultado final do filtro wcsp_vendor_postcode aplicado ao vendedor.

Quando usar: quando você está escrevendo integração com um método de envio custom que precisa do CEP de origem.

add_filter( 'meu_metodo_envio_origem', function( $origem, $package ) {
    $cep = $package['wcsp_vendor_postcode'] ?? '';
    if ( $cep ) {
        return $cep;
    }
    return $origem;
}, 10, 2 );

Campos adicionais por marketplace

Cada marketplace adiciona seus próprios campos no pacote pra manter compatibilidade com integrações nativas:

Dokan

• vendor_id (mesmo valor de wcsp_vendor_id) — usado por hooks Dokan.
• seller_id — adicionado também às taxas de envio (WC_Shipping_Rate) pra associação do pedido ao vendedor.

WCFM

• vendor_id
• processing_time — tempo de processamento do vendedor (se preenchido), em dias.
• pickup_address — endereço de coleta separado (se preenchido).

WC Marketplace

• vendor_id
• extra_package_data — array com dados específicos do plugin pra fulfillment.

YITH, WC Vendors

vendor_id consistente, sem campos adicionais especiais.

Lendo do pacote dentro de filtros

Em qualquer filtro que receba o $package, esses campos estão disponíveis. Exemplos:

// Sobretaxar pacote do vendedor 42 em 10%
add_filter( 'woocommerce_package_rates', function( $rates, $package ) {
    if ( ( $package['wcsp_vendor_id'] ?? 0 ) === 42 ) {
        foreach ( $rates as $rate ) {
            $rate->cost *= 1.10;
        }
    }
    return $rates;
}, 10, 2 );

// Logar nome da loja em desenvolvimento
add_filter( 'wcsp_package_name', function( $name, $vendor_id, $package ) {
    error_log( sprintf( 'Calculando frete pra %s', $package['wcsp_vendor_name'] ) );
    return $name;
}, 10, 3 );

Filtros relacionados

• wcsp_vendor_postcode — preenche o wcsp_vendor_postcode do pacote.
• wcsp_package_name — usa wcsp_vendor_name no resultado.
• Filtros dos métodos de envio — todos recebem o $package com os campos wcsp_*.