# WooCommerce WP-CLI — Referência Completa (CWP)

**Manual Hub:** `06-Operacoes/Documentacao/Manuais/WooCommerce com WP-CLI_ Guia Completo.md`

---

## Namespace e Entidades Disponíveis

O WooCommerce CLI opera sob `wp wc`. Todas as operações mapeiam para REST API v3.

| Entidade | Comando Base |
|----------|-------------|
| `customer` | Contas, moradas, métricas |
| `product` | Inventário, preços, stock |
| `product_cat` / `product_tag` | Categorias e tags |
| `product_attribute` | Atributos globais |
| `product_variation` | Variações de produto variável |
| `shop_order` | Encomendas |
| `order_note` | Notas de encomenda |
| `shop_coupon` | Cupões de desconto |
| `setting` | Settings WooCommerce |
| `shipping_zone` | Zonas de envio |
| `shipping_zone_location` | Localizações por zona |
| `shipping_zone_method` | Métodos por zona |
| `payment_gateway` | Gateways de pagamento |
| `tax` | Taxas de imposto |
| `tax_class` | Classes de imposto |
| `tool` | Ferramentas de manutenção |
| `webhook` | Webhooks server-to-server |

---

## Tipos de Produto — Exemplos Completos

### Produto Simples

```bash
PATH_WP="/home/USER/public_html"

/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="T-Shirt Premium Algodão Orgânico" \
  --type=simple \
  --regular_price="29.99" \
  --sale_price="24.99" \
  --sku="TSHIRT-PREM-001" \
  --manage_stock=true \
  --stock_quantity=150 \
  --status=publish \
  --description="Descrição completa do produto." \
  --short_description="Descrição curta para listagens." \
  --allow-root --path=$PATH_WP
```

### Produto Virtual (sem envio)

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Consulta Online 1h" \
  --type=simple \
  --virtual=true \
  --regular_price="75.00" \
  --sku="CONSULT-1H" \
  --status=publish \
  --allow-root --path=$PATH_WP
```

### Produto Downloadable

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="eBook Guia SEO 2026" \
  --type=simple \
  --virtual=true \
  --downloadable=true \
  --regular_price="19.90" \
  --sku="EBOOK-SEO-2026" \
  --downloads='[{"name":"eBook SEO 2026","file":"https://site.pt/ficheiros/ebook-seo-2026.pdf"}]' \
  --download_limit=3 \
  --download_expiry=365 \
  --allow-root --path=$PATH_WP
```

### Produto Externo/Afiliado

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Software Cloud Parceiro" \
  --type=external \
  --regular_price="99.00" \
  --product_url="https://parceiro.com/checkout/123" \
  --button_text="Comprar na Loja do Parceiro" \
  --sku="EXT-SOFT-123" \
  --allow-root --path=$PATH_WP
```

### Produto Agrupado (Grouped)

```bash
# 1. Criar produto pai agrupado
GROUP_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 --name="Pack Bundle Completo" --type=grouped --sku="PACK-BUNDLE-001" \
  --porcelain --allow-root --path=$PATH_WP)

# 2. Criar filho vinculado ao grupo
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Item A do Pack" \
  --type=simple \
  --regular_price="15.00" \
  --sku="PACK-ITEM-A" \
  --parent_id=$GROUP_ID \
  --allow-root --path=$PATH_WP
```

### Produto Variável com Variações

```bash
# 1. Criar produto pai variável
PARENT_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Sapatilhas Running" \
  --type=variable \
  --attributes='[{"name":"Tamanho","variation":true,"visible":true,"options":["39","40","41","42","43"]},{"name":"Cor","variation":true,"visible":true,"options":["Preto","Branco"]}]' \
  --porcelain --allow-root --path=$PATH_WP)

# 2. Criar variação (Tamanho 40, Cor Preto)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product_variation create $PARENT_ID \
  --user=1 \
  --regular_price="89.99" \
  --sku="RUN-40-PT" \
  --attributes='[{"name":"Tamanho","option":"40"},{"name":"Cor","option":"Preto"}]' \
  --manage_stock=true \
  --stock_quantity=25 \
  --allow-root --path=$PATH_WP
```

### Produto com Categorias e Atributos Visíveis

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product create \
  --user=1 \
  --name="Casaco Impermeável Inverno" \
  --type=simple \
  --regular_price="120.00" \
  --categories='[{"id":15},{"id":22}]' \
  --attributes='[{"name":"Material","visible":true,"options":["Poliéster","Gore-Tex"]},{"name":"Cor","visible":true,"options":["Preto","Azul Marinho"]}]' \
  --allow-root --path=$PATH_WP
```

---

## Gestão de Stock

```bash
PATH_WP="/home/USER/public_html"

# Actualizar stock de produto único
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product update 456 \
  --user=1 \
  --manage_stock=true \
  --stock_quantity=75 \
  --stock_status=instock \
  --allow-root --path=$PATH_WP

# Colocar produto fora de stock (sem alterar quantidade)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product update 456 \
  --user=1 --stock_status=outofstock \
  --allow-root --path=$PATH_WP

# Actualizar stock em massa por prefixo SKU
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"
for ID in $($WP wc product list --user=1 --sku="TSHIRT-*" --format=ids); do
  $WP wc product update $ID --user=1 --stock_quantity=200 --porcelain
done
```

---

## Gestão de Encomendas

### Consulta e Filtros

```bash
PATH_WP="/home/USER/public_html"

# Encomendas por estado
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_order list \
  --user=1 --status=processing \
  --fields=id,total,currency,date_created \
  --format=table \
  --allow-root --path=$PATH_WP

# Estados disponíveis: pending, processing, on-hold, completed, cancelled, refunded, failed
```

### Actualizar Estado

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_order update 355 \
  --user=1 --status=completed \
  --allow-root --path=$PATH_WP
```

### Adicionar Nota (Visível ao Cliente)

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc order_note create 355 \
  --user=1 \
  --note="Expedido via CTT. Rastreio: PT-99887766." \
  --customer_note=true \
  --allow-root --path=$PATH_WP
```

### Conclusão Massiva com Relatório

```bash
#!/bin/bash
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"

ORDER_IDS=$($WP wc shop_order list --user=1 --status=processing --format=ids)
TOTAL=0

for ID in $ORDER_IDS; do
  $WP wc shop_order update $ID --user=1 --status=completed --porcelain
  TOTAL=$((TOTAL+1))
  echo "[OK] Encomenda #$ID concluída."
done

echo "Total processado: $TOTAL encomendas."
```

---

## Clientes

```bash
PATH_WP="/home/USER/public_html"

# Listar com métricas de lifetime value
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc customer list \
  --user=1 \
  --role=customer \
  --fields=id,email,orders_count,total_spent \
  --format=table \
  --allow-root --path=$PATH_WP

# Criar cliente completo (B2B)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc customer create \
  --user=1 \
  --email="empresa@exemplo.pt" \
  --first_name="Carlos" \
  --last_name="Mendes" \
  --username="carlosmendes_b2b" \
  --password="SenhaForte!2026" \
  --billing='{"first_name":"Carlos","last_name":"Mendes","company":"Empresa Lda","address_1":"Avenida da Liberdade 123","city":"Lisboa","postcode":"1250-140","country":"PT"}' \
  --shipping='{"first_name":"Carlos","last_name":"Mendes","company":"Armazém Empresa","address_1":"Rua da Indústria 45","city":"Sintra","postcode":"2710-000","country":"PT"}' \
  --allow-root --path=$PATH_WP
```

---

## Shipping Zones — Configuração Completa

```bash
PATH_WP="/home/USER/public_html"

# 1. Criar zona geográfica
ZONE_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone create \
  --user=1 --name="Portugal Continental" \
  --porcelain --allow-root --path=$PATH_WP)

# 2. Adicionar países à zona
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone_location create $ZONE_ID \
  --user=1 --code="PT" --type=country \
  --allow-root --path=$PATH_WP

# 3. Adicionar método de portes fixos
METHOD_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone_method create $ZONE_ID \
  --user=1 --method_id=flat_rate \
  --porcelain --allow-root --path=$PATH_WP)

# 4. Definir custo
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone_method update $ZONE_ID $METHOD_ID \
  --user=1 --settings='{"cost":"3.99","title":"Portes Padrão"}' \
  --allow-root --path=$PATH_WP

# 5. Adicionar envio gratuito acima de X€
FREE_ID=$(/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone_method create $ZONE_ID \
  --user=1 --method_id=free_shipping \
  --porcelain --allow-root --path=$PATH_WP)

/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone_method update $ZONE_ID $FREE_ID \
  --user=1 --settings='{"requires":"min_amount","min_amount":"50"}' \
  --allow-root --path=$PATH_WP

# Listar todas as zonas
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shipping_zone list \
  --user=1 --format=table --allow-root --path=$PATH_WP
```

---

## Payment Gateways

```bash
PATH_WP="/home/USER/public_html"

# Listar todos os gateways
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway list \
  --user=1 --fields=id,title,enabled --allow-root --path=$PATH_WP

# Activar gateway
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway update bacs \
  --user=1 --enabled=true --allow-root --path=$PATH_WP

# Desactivar gateway (emergência)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway update paypal \
  --user=1 --enabled=false --allow-root --path=$PATH_WP

# Configurar Stripe em modo teste
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc payment_gateway update stripe \
  --user=1 \
  --settings='{"testmode":"yes","test_publishable_key":"pk_test_XXXX","test_secret_key":"sk_test_XXXX"}' \
  --allow-root --path=$PATH_WP
```

---

## Tributação

```bash
PATH_WP="/home/USER/public_html"

# Criar taxa IVA 23% (Portugal)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc tax create \
  --user=1 \
  --country=PT \
  --rate="23" \
  --name="IVA 23%" \
  --class=standard \
  --allow-root --path=$PATH_WP

# Criar taxa reduzida 6%
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc tax create \
  --user=1 --country=PT --rate="6" --name="IVA 6%" --class=reduced-rate \
  --allow-root --path=$PATH_WP

# Criar classe de taxa personalizada
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc tax_class create \
  --user=1 --name="Taxa Super Reduzida" \
  --allow-root --path=$PATH_WP

# Activar cálculo de impostos
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_calc_taxes "yes" \
  --allow-root --path=$PATH_WP
```

---

## Cupões

```bash
PATH_WP="/home/USER/public_html"

# Criar cupão de desconto percentual
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_coupon create \
  --user=1 \
  --code="VERAO2026" \
  --discount_type=percent \
  --amount="15" \
  --usage_limit=500 \
  --expiry_date="2026-09-30" \
  --allow-root --path=$PATH_WP

# Criar cupão de desconto fixo
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_coupon create \
  --user=1 \
  --code="DESCONTO10" \
  --discount_type=fixed_cart \
  --amount="10" \
  --minimum_amount="50" \
  --allow-root --path=$PATH_WP

# Listar cupões activos
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc shop_coupon list \
  --user=1 --fields=id,code,amount,discount_type,usage_count \
  --format=table --allow-root --path=$PATH_WP
```

---

## Ferramentas de Manutenção

```bash
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"

# Listar todas as ferramentas
$WP wc tool list --user=1 --fields=id,name,description --format=table

# Limpar transients
$WP wc tool run clear_transients --user=1

# Recalcular contadores de taxonomias (categorias/tags)
$WP wc tool run recount_terms --user=1

# Eliminar variações órfãs
$WP wc tool run delete_orphaned_variations --user=1

# Limpar sessões e carrinhos abandonados
$WP wc tool run clear_sessions --user=1

# Regenerar imagens de produto
$WP wc tool run regenerate_thumbnails --user=1

# Regenerar dados de lookup (tabela de relatórios)
$WP wc tool run clear_lookup_table --user=1

# Sequência completa de limpeza (recomendada após alterações massivas)
$WP wc tool run delete_orphaned_variations --user=1
$WP wc tool run recount_terms --user=1
$WP wc tool run clear_sessions --user=1
$WP wc tool run clear_transients --user=1
$WP cache flush
$WP rewrite flush
echo "Limpeza concluída."
```

---

## WP All Import — Importação Massiva

```bash
PATH_WP="/home/USER/public_html"

# Verificar se plugin está activo
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp plugin is-active wp-all-import-pro \
  --allow-root --path=$PATH_WP && echo "Activo" || echo "Inactivo"

# Executar perfil de importação pré-configurado (ID=5)
# Configurar mapeamentos no painel WP All Import primeiro
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp all-import run 5 \
  --force-run --disable-log \
  --allow-root --path=$PATH_WP

# Listar perfis de importação
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp all-import status \
  --allow-root --path=$PATH_WP
```

---

## Importação via CSV (Script)

```bash
#!/bin/bash
# Importar produtos a partir de CSV (colunas: SKU,TITULO,PRECO)
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"
CSV="/home/USER/produtos.csv"
ERROS=0
OK=0

tail -n +2 "$CSV" | while IFS=, read -r SKU TITULO PRECO; do
  ID=$($WP wc product create \
    --user=1 \
    --sku="$SKU" \
    --name="$TITULO" \
    --regular_price="$PRECO" \
    --type=simple \
    --status=publish \
    --porcelain 2>/dev/null)

  if [ -n "$ID" ] && [ "$ID" -gt 0 ] 2>/dev/null; then
    echo "[OK] $SKU → ID $ID"
    OK=$((OK+1))
  else
    echo "[ERRO] $SKU — falhou"
    ERROS=$((ERROS+1))
  fi
done

echo "Importação concluída. OK: $OK | Erros: $ERROS"
```

---

## Scripts de Manutenção

### Normalização Preventiva de Dados

```bash
#!/bin/bash
PATH_WP="/home/USER/public_html"
WP="/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp --allow-root --path=$PATH_WP"

echo "=== LIMPEZA WOOCOMMERCE ==="
echo "Site: $PATH_WP | $(date)"

$WP wc tool run delete_orphaned_variations --user=1 --quiet && echo "[OK] Variações órfãs"
$WP wc tool run recount_terms --user=1 --quiet && echo "[OK] Contadores taxonomias"
$WP wc tool run clear_sessions --user=1 --quiet && echo "[OK] Sessões"
$WP wc tool run clear_transients --user=1 --quiet && echo "[OK] Transients"
$WP cache flush && echo "[OK] Object cache"
$WP rewrite flush && echo "[OK] Rewrite rules"
$WP db optimize --quiet && echo "[OK] BD optimizada"

echo "=== CONCLUÍDO ==="
```

### Manutenção WooCommerce em Todos os Sites CWP

```bash
#!/bin/bash
find /home -name wp-config.php -not -path "*/backup*" 2>/dev/null | while read config; do
  dir=$(dirname "$config")
  user=$(stat -c '%U' "$dir")

  php_fpm=$(ps aux | grep "php-fpm: pool ${user}" | grep -v grep | head -1 | grep -o 'php-fpm[0-9][0-9]' | head -1)
  php_ver=${php_fpm:-php-fpm82}
  php_bin="/opt/alt/${php_ver}/usr/bin/php"
  WP="$php_bin /usr/local/bin/wp --allow-root --path=$dir"

  echo "=== $user ($dir) ==="

  # Verificar se WooCommerce está activo
  if $WP plugin is-active woocommerce 2>/dev/null; then
    $WP wc tool run clear_transients --user=1 --quiet 2>/dev/null
    $WP wc tool run recount_terms --user=1 --quiet 2>/dev/null
    echo "  [WC] Limpeza WooCommerce concluída."
  else
    echo "  [--] WooCommerce não activo."
  fi
done
```

---

## Limitações e Bugs Conhecidos

### Memory Exhaustion — Override CWP

```bash
# -d memory_limit antes de /usr/local/bin/wp
/opt/alt/php-fpm83/usr/bin/php -d memory_limit=2G /usr/local/bin/wp wc product list \
  --user=1 --per_page=100 --format=ids \
  --allow-root --path=/home/USER/public_html

# Para catálogos muito grandes: iterar com --per_page=100 e --page=N
for PAGE in 1 2 3 4 5; do
  /opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp wc product list \
    --user=1 --per_page=100 --page=$PAGE --format=ids \
    --allow-root --path=/home/USER/public_html
done
```

### Bug `wp wc update` — Versão BD não actualiza

```bash
# Verificar versão instalada
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp plugin get woocommerce \
  --field=version --allow-root --path=/home/USER/public_html

# Forçar actualização manual do registo BD
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_db_version "9.X.X" \
  --allow-root --path=/home/USER/public_html
```

### Bypass Wizard de Onboarding

```bash
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_onboarding_opt_in "yes" \
  --allow-root --path=/home/USER/public_html

/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_task_list_hidden "yes" \
  --allow-root --path=/home/USER/public_html

/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_setup_wizard_data \
  '{"setup_wizard":"completed"}' --allow-root --path=/home/USER/public_html
```

---

## Settings via wp_options

Algumas configurações WooCommerce não têm endpoint CLI nativo. Usar `wp option update` directamente:

```bash
PATH_WP="/home/USER/public_html"

# Moeda
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_currency "EUR" \
  --allow-root --path=$PATH_WP

# Posição do símbolo de moeda
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_currency_pos "right_space" \
  --allow-root --path=$PATH_WP

# Separadores de preço (PT-PT)
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_price_thousand_sep "." \
  --allow-root --path=$PATH_WP
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_price_decimal_sep "," \
  --allow-root --path=$PATH_WP

# País de base da loja
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_default_country "PT" \
  --allow-root --path=$PATH_WP

# Activar impostos
/opt/alt/php-fpm83/usr/bin/php /usr/local/bin/wp option update woocommerce_calc_taxes "yes" \
  --allow-root --path=$PATH_WP
```

---

*Referência WooCommerce CLI CWP | Descomplicar® | v1.0.0 | 18-02-2026*