📦 Estados de pedido — referencia y transiciones

<?php

// Las constantes son valores de Configuration, no literales
$paidStateId      = (int) Configuration::get('PS_OS_PAYMENT');    // = 2
$pendingStateId   = (int) Configuration::get('PS_OS_BANKWIRE');   // = 10
$errorStateId     = (int) Configuration::get('PS_OS_ERROR');      // = 8
$cancelledStateId = (int) Configuration::get('PS_OS_CANCELED');   // = 6

<?php

/**
 * Cambia el estado de un pedido y envia el email de notificacion.
 *
 * @param int $idOrder       ID del pedido
 * @param int $idOrderState  ID del nuevo estado
 */
private function setOrderState(int $idOrder, int $idOrderState): void
{
    $order = new Order($idOrder);

    if (!Validate::isLoadedObject($order)) {
        throw new \RuntimeException("Order {$idOrder} not found");
    }

    // Crear el historial de estado
    $history                  = new OrderHistory();
    $history->id_order        = $idOrder;
    $history->id_order_state  = $idOrderState;
    $history->id_employee     = (int) Context::getContext()->employee->id;
    $history->date_add        = date('Y-m-d H:i:s');

    $useExistingPayment = !$order->hasInvoice();
    $history->addWithemail($useExistingPayment);
    // addWithemail(true)  → usa el pago existente en lugar de crear uno nuevo
    // addWithemail(false) → fuerza la creacion de factura si el estado lo requiere
}

// Ejemplo en el ConfirmationFrontController tras pago exitoso:
$this->setOrderState($idOrder, (int) Configuration::get('PS_OS_PAYMENT'));

<?php

// En mymodule.php → install()
private function installOrderState(): bool
{
    if (Configuration::get('MYMODULE_OS_PENDING')) {
        return true; // Ya existe
    }

    $state                  = new OrderState();
    $state->color           = '#4169e1'; // Azul
    $state->hidden          = false;
    $state->delivery        = false;
    $state->logable         = true;     // Aparece en estadisticas
    $state->invoice         = false;
    $state->module_name     = $this->name;
    $state->send_email      = true;
    $state->template        = 'payment'; // Plantilla de email (mails/{lang}/payment.html)
    $state->unremovable     = false;

    foreach (Language::getLanguages() as $lang) {
        $state->name[$lang['id_lang']] = 'Pago pendiente (MyModule)';
    }

    if (!$state->add()) {
        return false;
    }

    Configuration::updateValue('MYMODULE_OS_PENDING', (int) $state->id);
    return true;
}

private function uninstallOrderState(): bool
{
    $id = (int) Configuration::get('MYMODULE_OS_PENDING');
    if ($id) {
        $state = new OrderState($id);
        $state->delete();
        Configuration::deleteByName('MYMODULE_OS_PENDING');
    }
    return true;
}

<?php

public function hookActionOrderStatusUpdate(array $params): void
{
    $newStatus = $params['newOrderStatus'];  // OrderState object
    $idOrder   = (int) $params['id_order'];

    // Reaccionar solo a un estado especifico
    if ($newStatus->id === (int) Configuration::get('PS_OS_SHIPPING')) {
        // El pedido acaba de pasar a 'Enviado'
        $order = new Order($idOrder);
        // ... notificar al ERP, actualizar stock externo, etc.
    }
}