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
- Ingresa a WooCommerce → Ajustes → Modal COD Form → Tarifas de Envío y Ubicaciones.
- Asegúrate de tener activada la casilla Usar Departamentos y Ciudades (States & Places).
- 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)).
- 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.
- 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).
- Selecciona el departamento en el desplegable para inspeccionar todas sus ciudades.
- Marca las ciudades que deseas deshabilitar. Verás cómo aparecen como píldoras (chips) en el resumen de exclusiones activas.
- 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
$statesy$placesfiltrados, vuelve a incluir (require) los archivos originales deincludes/states/eincludes/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 scriptcod-admin-states-places.jssincroniza 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
- Combina la exclusión de ciudades sin cobertura con Tarifas de Envío Condicionales para cobrar un recargo de flete en trayectos especiales donde sí entregas pero el costo logístico es mayor.
- Si necesitas agregar un municipio nuevo o renombrar una ciudad para que coincida exactamente con el diccionario de Dropi / Dropify, consulta la siguiente guía sobre Filtros PHP para Agregar o Modificar Ciudades y Departamentos.