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.
---

# /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');

function create_moloni_invoice($order_id) {
    $order = wc_get_order($order_id);
    // Chamar API Moloni via MCP
    // mcp__moloni__create_invoice(...)
}
```

### CTT Tracking

```php
// Adicionar tracking number
add_action('woocommerce_order_status_processing', 'add_tracking_number');

function add_tracking_number($order_id) {
    $tracking = generate_ctt_tracking($order_id);
    update_post_meta($order_id, '_tracking_number', $tracking);
}
```

## Performance WooCommerce

```php
// Desactivar scripts desnecessários
add_action('wp_enqueue_scripts', function() {
    // Desactivar em páginas que não são WooCommerce
    if (!is_woocommerce() && !is_cart() && !is_checkout()) {
        wp_dequeue_style('woocommerce-general');
        wp_dequeue_style('woocommerce-layout');
        wp_dequeue_style('woocommerce-smallscreen');
        wp_dequeue_script('wc-cart-fragments');
    }
}, 100);

// Optimizar queries
add_filter('woocommerce_product_query', function($q) {
    $q->set('no_found_rows', true); // Se não precisar paginação
});
```

## Checklist Nova Loja

```
[ ] WordPress + WooCommerce instalados
[ ] Tema compatível configurado
[ ] Páginas: Shop, Cart, Checkout, My Account, Terms
[ ] Gateways de pagamento activos e testados
[ ] Shipping zones Portugal configuradas
[ ] Taxas IVA: 23% (Continental), 13% (Madeira), 6% (Açores)
[ ] Emails transaccionais personalizados
[ ] SSL instalado e forçado
[ ] RGPD: Política Privacidade, Cookies
[ ] Teste de compra completo (real + teste)
```

## Datasets Dify

| Dataset | ID | Prioridade |
|---------|----|-----------:|
| **Wordpress** | `9da0b2b9-5051-4b99-b9f6-20bf35067092` | 1 |
| **WooCommerce** | (disponível) | 1 |
| **E-commerce** | (disponível) | 2 |

### Como Consultar

```javascript
# PRIMARIO: NotebookLM (Gemini 2.5 RAG)
# mcp__notebooklm__notebook_query({notebook_id: "5be0d1a6-00f2-4cd9-b835-978cb7721601", query: "<tema>"})  // WordPress e Elementor
# FALLBACK: Dify KB (se NotebookLM insuficiente)

// Hooks e customizações WooCommerce
mcp__dify-kb__dify_kb_retrieve_segments({
  dataset_id: "9da0b2b9-5051-4b99-b9f6-20bf35067092",
  query: "woocommerce hooks checkout cart filters"
})
```

---

**Versão**: 1.0.0 | **Autor**: Descomplicar®