claude-plugins/wordpress/skills/woocommerce/SKILL.md

---
name: woocommerce
description: Desenvolvimento e optimização de lojas WooCommerce. Personalização de checkout, integração de gateways de pagamento portugueses (Multibanco, MB Way, IfthenPay), funcionalidades custom e performance.
layer: wiki
---

# /woocommerce - WooCommerce Development

Desenvolvimento e optimização de lojas WooCommerce.

## Quando Usar

- Configurar loja WooCommerce
- Personalizar checkout
- Integrar gateways de pagamento PT
- Desenvolver funcionalidades custom
- Optimizar performance

## Contexto NotebookLM

ANTES de executar, consultar notebooks para contexto especializado:

| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| WordPress e Elementor | 5be0d1a6 | Sempre |
| E-commerce Prático | 226e384e | Para estratégia e-commerce |

```
mcp__notebooklm__notebook_query({
  notebook_id: "5be0d1a6-00f2-4cd9-b835-978cb7721601",
  query: "<adaptar ao contexto do pedido do utilizador>"
})

mcp__notebooklm__notebook_query({
  notebook_id: "226e384e-d4bc-48f4-bb82-7927360436cc",
  query: "<adaptar ao contexto e-commerce do pedido>"
})
```

Integrar insights do NotebookLM nas recomendações e decisões.

### Procedimentos Relacionados
- `PROC-WiP-Starter-Template.md` — Template inicial para lojas WooCommerce

---

## Hooks WooCommerce Essenciais

### Actions

```php
// Before/after cart
add_action('woocommerce_before_cart', 'show_cart_notice');
add_action('woocommerce_after_cart', 'show_shipping_info');

// Checkout
add_action('woocommerce_before_checkout_form', 'show_checkout_notice');
add_action('woocommerce_checkout_order_processed', 'after_order', 10, 3);

// Product
add_action('woocommerce_before_single_product', 'show_product_notice');
add_action('woocommerce_after_add_to_cart_button', 'add_custom_button');

// Admin
add_action('woocommerce_admin_order_data_after_billing_address', 'show_admin_meta');
add_action('woocommerce_process_product_meta', 'save_product_meta');
```

### Filters

```php
// Modificar preço
add_filter('woocommerce_cart_item_price', 'custom_price', 10, 2);
add_filter('woocommerce_get_price_html', 'custom_price_html', 10, 2);

// Checkout fields
add_filter('woocommerce_checkout_fields', 'custom_checkout_fields');
add_filter('woocommerce_billing_fields', 'custom_billing_fields');

// Cart
add_filter('woocommerce_add_cart_item_data', 'add_cart_item_data', 10, 2);
add_filter('woocommerce_cart_item_name', 'custom_cart_item_name', 10, 3);

// Emails
add_filter('woocommerce_email_subject_new_order', 'custom_email_subject', 10, 2);
```

## Gateways Portugal

| Gateway | Plugin | Notas |
|---------|--------|-------|
| **MB Way** | IfthenPay / Eupago | Pagamento instantâneo |
| **Multibanco** | IfthenPay / Eupago | Referências MB |
| **Stripe** | Stripe for WooCommerce | Cartões + Apple/Google Pay |
| **PayPal** | WooCommerce PayPal | Standard e Express |

### Configuração IfthenPay

```php
// Webhook para confirmação automática
add_action('woocommerce_api_ifthenpay_webhook', 'handle_ifthenpay_callback');

function handle_ifthenpay_callback() {
    $order_id = $_GET['order_id'] ?? null;
    $status = $_GET['status'] ?? null;

    if ($status === 'success') {
        $order = wc_get_order($order_id);
        $order->payment_complete();
    }
}
```

## Customização Checkout

```php
// Adicionar campo NIF
add_filter('woocommerce_checkout_fields', function($fields) {
    $fields['billing']['billing_nif'] = [
        'label' => 'NIF',
        'required' => true,
        'class' => ['form-row-wide'],
        'validate' => ['validate_nif']
    ];
    return $fields;
});

// Validar NIF
add_action('woocommerce_checkout_process', function() {
    if (empty($_POST['billing_nif'])) {
        wc_add_notice('NIF é obrigatório', 'error');
    }
});

// Guardar NIF
add_action('woocommerce_checkout_update_order_meta', function($order_id) {
    if (!empty($_POST['billing_nif'])) {
        update_post_meta($order_id, '_billing_nif', sanitize_text_field($_POST['billing_nif']));
    }
});
```

## REST API

```php
// Endpoint custom
add_action('rest_api_init', function() {
    register_rest_route('wc/v3', '/products/featured', [
        'methods' => 'GET',
        'callback' => function() {
            $args = [
                'status' => 'publish',
                'featured' => true,
                'limit' => 10
            ];
            $products = wc_get_products($args);
            return rest_ensure_response($products);
        }
    ]);
});
```

## WP-CLI WooCommerce

```bash
# Listar produtos
wp wc product list --user=1 --format=table

# Criar produto
wp wc product create --name="Produto Teste" --regular_price=99.99 --user=1

# Listar pedidos
wp wc order list --status=processing --user=1

# Actualizar stock
wp wc product update 123 --stock_quantity=50 --user=1

# Limpar transients
wp transient delete --all
```

## Integrações

### Moloni (Facturação)

```php
// Auto-criar factura após pedido pago
add_action('woocommerce_order_status_completed', 'create_moloni_invoice');

functi