Cookbook de Actions (do_action) para Integrar ERPs, Transportadoras y Lógica Post-Compra (Free y PRO)

Además de los webhooks HTTP externos, tanto Modal COD Form Free como Modal COD Form PRO disparan acciones nativas de WordPress (do_action) en el servidor durante todo el ciclo de vida del pedido contraentrega, la captura de carritos y la validación antifraude.

Este Cookbook reúne fragmentos de código PHP listos para producción y 100% compatibles con WooCommerce HPOS (High-Performance Order Storage) para integrar tu tienda con ERPs propios, transportadoras locales o reglas de negocio personalizadas.

1. Mapa de Actions de Ciclo de Vida (Free vs PRO)

Hook Action (do_action) Edición Parámetros Recibidos Momento Exacto de Ejecución
modalcodf_order_finalized Free (v2.0+) $order_id (int), $order (WC_Order) Justo después de crear la orden COD, asignar métodos de envío firmados por HMAC y actualizar el estado en MODALCODF_Order_Creator.
cod_order_finalized PRO (v5.0+) $order_id (int), $order (WC_Order) Al finalizar el pedido en PRCOD_Order_Creator::finalize_order() (tanto para órdenes estándar como para órdenes prorrateadas de Dropify/Dropi).
cod_cart_abandoned PRO $cart_id (int), $cart_data (array) Cuando el proceso CRON detecta que un carrito capturado superó el umbral cod_form_abandonment_time sin convertirse en pedido.
cod_cart_recovered PRO $cart_id (int), $order_id (int), $cart_data (array) Cuando una orden recién creada coincide por session_id, email o phone con un carrito abandonado previo.
cod_cart_blocked PRO $reason (string), $order_data (array) Cuando PRCOD_Fraud_Prevention_Validator rechaza el envío del formulario por lista negra (IP/teléfono/email), límite por hora o reCAPTCHA v3.

2. Receta 1: Código Universal post-compra compatible con Free y PRO + HPOS

Si desarrollas un plugin de integración para clientes que pueden estar usando la versión Free o la versión PRO, puedes enganchar la misma función a ambos hooks (modalcodf_order_finalized y cod_order_finalized) utilizando los métodos CRUD de WC_Order para garantizar compatibilidad total con HPOS:

/**
 * Ejecutar lógica post-compra compatible con Modal COD Form Free, PRO y WooCommerce HPOS
 *
 * @param int      $order_id ID del pedido WooCommerce.
 * @param WC_Order $order    Instancia del objeto WC_Order.
 */
function mcod_custom_erp_sync_on_order_finalized( $order_id, $order = null ) {
    if ( ! $order instanceof WC_Order ) {
        $order = wc_get_order( $order_id );
    }
    if ( ! $order ) {
        return;
    }

    // 1. Leer metadatos específicos de Modal COD Form PRO (con fallback limpio en Free)
    $document = $order->get_meta( '_billing_document', true );
    $district = $order->get_meta( '_billing_district', true );

    // 2. Detectar si el pedido incluye productos de Upsell (1-Tick o 1-Click)
    $has_upsells = false;
    foreach ( $order->get_items() as $item ) {
        if ( 'yes' === $item->get_meta( '_cod_is_upsell', true ) ) {
            $has_upsells = true;
            break;
        }
    }

    // 3. Guardar un metadato personalizado usando HPOS CRUD
    $order->update_meta_data( '_erp_cod_priority', $has_upsells ? 'vip_upsell' : 'standard' );
    $order->save();
}
add_action( 'modalcodf_order_finalized', 'mcod_custom_erp_sync_on_order_finalized', 10, 2 );
add_action( 'cod_order_finalized', 'mcod_custom_erp_sync_on_order_finalized', 10, 2 );

3. Receta 2: Cambiar el Estado del Pedido según el Monto Total (Verificación Telefónica Manual)

En operaciones contraentrega, es una excelente práctica enviar automáticamente los pedidos normales al estado processing para despacho inmediato, pero retener en un estado de verificación (on-hold) aquellos pedidos que superen un monto alto (por ejemplo, más de $350.000 COP o $2,000 MXN):

/**
 * Retener en 'on-hold' los pedidos COD de alto valor para confirmación telefónica manual
 */
add_action( 'cod_order_finalized', function( $order_id, $order ) {
    if ( ! $order instanceof WC_Order ) {
        $order = wc_get_order( $order_id );
    }
    if ( ! $order ) {
        return;
    }

    $threshold = 350000; // Umbral en la moneda de la tienda
    if ( (float) $order->get_total() >= $threshold ) {
        $order->update_status(
            'on-hold',
            sprintf( 'Pedido COD de alto valor (%s). Requiere confirmación telefónica antes de despachar.', wc_price( $order->get_total() ) )
        );
    }
}, 20, 2 );

4. Receta 3: Registrar Intentos de Fraude Bloqueados en un Log de Seguridad Propio

Cada vez que el validador antifraude bloquea una transacción en el servidor, puedes capturar el evento cod_cart_blocked para alimentar un firewall (Cloudflare / Wordfence) o auditar el motivo exacto:

/**
 * Auditar en el logger de WooCommerce cada intento de pedido bloqueado por antifraude
 */
add_action( 'cod_cart_blocked', function( $reason, $order_data ) {
    if ( function_exists( 'wc_get_logger' ) ) {
        $logger = wc_get_logger();
        $ip     = isset( $_SERVER['REMOTE_ADDR'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ) ) : 'unknown';
        $phone  = isset( $order_data['phone'] ) ? sanitize_text_field( $order_data['phone'] ) : '';

        $logger->warning(
            sprintf( 'Intento COD Bloqueado | Motivo: %s | IP: %s | Tel: %s', $reason, $ip, $phone ),
            array( 'source' => 'mcodform-security-audit' )
        );
    }
}, 10, 2 );

5. Enlaces Relacionados

Compartir esta información

Aumenta tus ventas

Mejora tu conversión en tiendas WordPress y WooCommerce con pago contra-entrega.