Cómo Deshabilitar Estados, Departamentos y Ciudades sin Cobertura Contraentrega en WooCommerce

Uno de los mayores retos operativos en el comercio electrónico con Pago Contra Entrega (COD) en Latinoamérica es evitar que los clientes realicen pedidos desde departamentos, estados, islas o municipios remotos donde las transportadoras no ofrecen servicio de recaudo en efectivo o donde el costo del flete supera el margen del producto.

En esta guía avanzada aprenderás cómo funciona internamente el motor de exclusión geográfica de Modal COD Form PRO y cómo deshabilitar departamentos completos o ciudades específicas tanto desde la interfaz administrativa como programáticamente.

1. Arquitectura del Motor de Exclusión Geográfica

Cuando activas los selectores jerárquicos de ubicaciones (cod_form_use_states_places = yes) en Países, Departamentos y Ciudades Soportados, la clase PRCOD_States_Places_Base intercepta los catálogos geográficos de WooCommerce antes de enviarlos al formulario modal.

El filtrado ocurre en dos niveles almacenados en la tabla wp_options:

Opción en Base de Datos Tipo de Dato Propósito Técnico
cod_form_excluded_states array indexado de códigos de estado (ej. ['AMA', 'GUA', 'VAU']) Elimina el departamento/estado completo tanto del selector de estados como del diccionario de ciudades en frontend.
cod_form_excluded_cities array asociativo por código de estado (ej. ['ANT' => ['Murindó', 'Vigía del Fuerte']]) Mantiene activo el departamento/estado, pero oculta únicamente las ciudades o municipios específicos sin cobertura COD.

2. Cómo Excluir Departamentos o Estados Completos desde el Admin

  1. Ingresa a WooCommerce → Ajustes → Modal COD Form → Tarifas de Envío y Ubicaciones.
  2. Asegúrate de tener activada la casilla Usar Departamentos y Ciudades (States & Places).
  3. En el campo multiselect Excluir Departamentos / Estados (Exclude States), busca y selecciona los departamentos donde no realizas envíos contraentrega (por ejemplo, Amazonas (AMA), San Andrés y Providencia (SAP) o Galápagos (GPS)).
  4. Haz clic en Guardar los cambios.

Internamente, el método get_states($country_code) lee la opción cod_form_excluded_states y ejecuta unset($states[$state_code]) antes de construir el HTML del <select id="state">.

3. Cómo Deshabilitar Ciudades o Municipios Específicos sin Ocultar el Departamento

Muchas veces sí tienes cobertura en las ciudades principales de un departamento (como Medellín, Envigado o Rionegro en Antioquia), pero necesitas bloquear municipios de difícil acceso o trayectos especiales.

  1. En la misma sección Tarifas de Envío y Ubicaciones, desplázate hasta el bloque interactivo Excluir Ciudades por Departamento (Exclude Cities by State).
  2. Selecciona el departamento en el desplegable para inspeccionar todas sus ciudades.
  3. Marca las ciudades que deseas deshabilitar. Verás cómo aparecen como píldoras (chips) en el resumen de exclusiones activas.
  4. Guarda los cambios.

¿Cómo evita el plugin que se pierdan tus exclusiones previas al guardar?

En versiones empresariales, el administrador no necesita abrir cada departamento antes de guardar:

  • Patrón Backup / Require / Restore: Cuando se renderiza la pantalla administrativa, los filtros de exclusión ya están activos en memoria. Para que el administrador pueda seguir viendo las ciudades excluidas dentro del panel y pueda desmarcarlas en el futuro, la página de ajustes respalda temporalmente los arrays de $states y $places filtrados, vuelve a incluir (require) los archivos originales de includes/states/ e includes/places/ para obtener el catálogo 100% íntegro, construye el panel administrativo y finalmente restaura los globales filtrados.
  • Pre-renderizado de Inputs Hidden en PHP: La plantilla administrativa pre-renderiza automáticamente inputs ocultos (<input type="hidden" name="cod_form_excluded_cities[ESTADO][]" value="Ciudad">) para todos los departamentos que ya tienen ciudades excluidas. El script cod-admin-states-places.js sincroniza dinámicamente esos inputs cuando agregas o quitas ciudades, garantizando que al enviar el formulario nunca se sobrescriban ni se borren exclusiones de otros departamentos.

4. Cómo Excluir Estados o Ciudades Dinámicamente por Código PHP

Si necesitas aplicar reglas de exclusión dinámicas (por ejemplo, deshabilitar ciertas ciudades solo cuando el carrito contiene productos pesados o frágiles), puedes interceptar las opciones de WordPress mediante el filtro nativo pre_option_{$option} o option_{$option}:

/**
 * Excluir dinámicamente departamentos adicionales según el peso o categoría del carrito
 */
add_filter( 'option_cod_form_excluded_states', function( $excluded_states ) {
    if ( ! is_array( $excluded_states ) ) {
        $excluded_states = array();
    }

    // Ejemplo: Si estamos en frontend y el subtotal es menor a $50.000, excluir departamentos lejanos
    if ( ! is_admin() && function_exists( 'WC' ) && WC()->cart ) {
        $subtotal = (float) WC()->cart->get_subtotal();
        if ( $subtotal > 0 && $subtotal < 50000 ) {
            $excluded_states[] = 'PUT'; // Putumayo
            $excluded_states[] = 'CAQ'; // Caquetá
        }
    }

    return array_values( array_unique( $excluded_states ) );
}, 10, 1 );

Excluir ciudades específicas programáticamente según condición

/**
 * Deshabilitar municipios específicos de Antioquia y Cundinamarca por código
 */
add_filter( 'option_cod_form_excluded_cities', function( $excluded_cities ) {
    if ( ! is_array( $excluded_cities ) ) {
        $excluded_cities = array();
    }

    $custom_exclusions = array(
        'ANT' => array( 'Vigía del Fuerte', 'Murindó' ),
        'CUN' => array( 'Medina', 'Paratebueno' ),
    );

    foreach ( $custom_exclusions as $state_code => $cities ) {
        if ( ! isset( $excluded_cities[ $state_code ] ) || ! is_array( $excluded_cities[ $state_code ] ) ) {
            $excluded_cities[ $state_code ] = array();
        }
        $excluded_cities[ $state_code ] = array_values(
            array_unique( array_merge( $excluded_cities[ $state_code ], $cities ) )
        );
    }

    return $excluded_cities;
}, 10, 1 );

5. Recomendaciones Estratégicas para Reducir Devoluciones

Compartir esta información

Aumenta tus ventas

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