💸 Reembolsos y notas de abono

<?php

// ── Desde el BO: Pedido → Detalle → "Devolucion parcial" ──
// Pero tambien se puede hacer desde un modulo:

$order = new Order($idOrder);

// ── 1. Crear nota de abono (OrderSlip) ──
$products = [];
foreach ($order->getProducts() as $product) {
    // Devolver 1 unidad del primer producto
    $products[$product['id_order_detail']] = [
        'id_order_detail' => $product['id_order_detail'],
        'quantity'        => 1,
        'unit_price'      => $product['unit_price_tax_incl'],
        'amount'          => $product['unit_price_tax_incl'] * 1,
    ];
    break; // Solo el primero como ejemplo
}

$shipping = false; // true para devolver tambien el envio
OrderSlip::create(
    $order,
    $products,
    $shipping,
    0,    // Importe de envio a devolver
    false, // Generar vale de descuento
    true   // Generar nota de abono PDF
);

// ── 2. Restock automatico ──
foreach ($products as $p) {
    StockAvailable::updateQuantity(
        $p['id_order_detail'], // En realidad necesitas id_product
        0, // id_product_attribute
        $p['quantity'], // Cantidad a reponer
        $order->id_shop
    );
}

// ── 3. Cambiar estado del pedido ──
$history = new OrderHistory();
$history->id_order = $order->id;
$history->changeIdOrderState(
    Configuration::get('PS_OS_REFUND'), // Estado: Reembolsado
    $order->id
);

QUE ES UNA NOTA DE ABONO
- Documento fiscal que registra la devolucion
- Numero correlativo (como las facturas)
- Incluye: productos devueltos, importe, impuestos
- El cliente puede descargarla desde "Mi cuenta"

GENERAR DESDE EL BO
1. Pedido → Detalle del pedido
2. Seccion "Devolucion de productos"
3. Seleccionar productos y cantidades
4. Marcar:
   ☑ Generar nota de abono
   ☑ Generar vale de descuento (opcional)
   ☑ Reponer productos (restock)
5. Si se devuelve envio: indicar importe
6. Clic en "Devolver productos"

NUMERACION
- Pedidos → Notas de abono → Opciones
- Prefijo: #AB o #CN
- Numero siguiente: correlativo
- La numeracion es independiente de las facturas

DESCARGA
- BO: Pedidos → Notas de abono → descargar PDF
- Cliente: Mi cuenta → Notas de abono → PDF

<?php

// ── Hook para reembolsar automaticamente cuando se cambia a estado Reembolsado ──
public function hookActionOrderStatusPostUpdate(array $params): void
{
    $newStatus = $params['newOrderStatus'];
    $idOrder   = (int) $params['id_order'];

    if ((int) $newStatus->id !== (int) Configuration::get('PS_OS_REFUND')) {
        return;
    }

    $order = new Order($idOrder);

    // Solo si es nuestro modulo de pago
    if ($order->module !== $this->name) {
        return;
    }

    // Obtener transaction_id del pago original
    $payments = $order->getOrderPayments();
    $transactionId = $payments[0]->transaction_id ?? null;

    if (!$transactionId) {
        PrestaShopLogger::addLog('Refund failed: no transaction_id', 3);
        return;
    }

    try {
        // Llamar a la API de la pasarela para reembolsar
        $result = $this->gateway->refund([
            'transaction_id' => $transactionId,
            'amount'         => $order->total_paid_tax_incl,
            'currency'       => Currency::getIsoCodeById($order->id_currency),
        ]);

        if ($result->success) {
            // Registrar el pago negativo
            $order->addOrderPayment(
                -$order->total_paid_tax_incl,
                $this->displayName . ' Refund',
                $result->refund_id
            );
        }
    } catch (\Exception $e) {
        PrestaShopLogger::addLog('Refund error: ' . $e->getMessage(), 3);
    }
}