Cuando operas tiendas de Pago Contra Entrega (COD) conectadas con transportadoras locales o plataformas logísticas como Dropi, Effi o Mastershop, es frecuente que necesites agregar corregimientos nuevos, estandarizar el nombre de una ciudad o personalizar la lista de departamentos, provincias y distritos de tu país.
Modal COD Form PRO expone 22 filtros nativos de WordPress (apply_filters) dentro de sus catálogos geográficos (includes/states/ e includes/places/) para los 11 países soportados.
1. Regla Técnica Crítica: ¿Por qué usar un mu-plugin en lugar de functions.php?
Antes de escribir tu código, es fundamental comprender el orden de carga de WordPress:
- WordPress carga primero los Must-Use Plugins (
wp-content/mu-plugins/). - Luego carga los plugins activos y ejecuta el hook
plugins_loaded(donde Modal COD Form PRO inicializaPRCOD_States_Places_Colombia,PRCOD_States_Places_Mexico, etc., e incluye los archivosincludes/states/*.phpeincludes/places/*.php). - Recién después carga el archivo
functions.phpdel tema activo.
Dado que los filtros cod_form_{pais}_states y cod_form_{pais}_places se evalúan en el momento exacto en que se incluyen los archivos de ubicaciones durante la inicialización del plugin, cualquier filtro registrado en el functions.php de tu tema llegará demasiado tarde. Por ello, siempre debes registrar estos filtros en un archivo dentro de wp-content/mu-plugins/ (por ejemplo, wp-content/mu-plugins/custom-cod-locations.php).
2. Tabla Completa de los 22 Filtros Geográficos por País
| País (Código ISO) | Filtro de Departamentos / Estados / Provincias | Filtro de Ciudades / Municipios / Distritos |
|---|---|---|
Colombia (CO) |
cod_form_colombia_states |
cod_form_colombia_places |
México (MX) |
cod_form_mexico_states |
cod_form_mexico_places |
Perú Estándar (PE) |
cod_form_peru_states |
cod_form_peru_places |
Perú V2 3 Niveles (PEV2) |
cod_form_peru_states |
cod_form_peru_places (Estructura anidada Depto → Provincia → [Distritos]) |
Chile (CL) |
cod_form_chile_states |
cod_form_chile_places |
Ecuador (EC) |
cod_form_ecuador_states |
cod_form_ecuador_places |
Panamá (PA) |
cod_form_panama_states |
cod_form_panama_places |
Guatemala (GT) |
cod_form_guatemala_states |
cod_form_guatemala_places |
Costa Rica (CR) |
cod_form_costa_rica_states (en states/CR.php) / cod_form_cr_states (en places/CR.php) |
cod_form_costa_rica_places / cod_form_cr_places |
República Dominicana (DO) |
cod_form_rd_states |
cod_form_rd_places |
Paraguay (PY) |
cod_form_paraguay_states |
cod_form_paraguay_places |
Estados Unidos (US) |
cod_form_us_states |
cod_form_us_places |
3. Receta 1: Agregar Corregimientos o Renombrar Ciudades en Colombia (CO)
Crea el archivo wp-content/mu-plugins/custom-cod-locations.php y pega el siguiente código:
<?php
/**
* Plugin Name: Custom Locations for Modal COD Form PRO
* Description: Personaliza departamentos y ciudades para Pago Contra Entrega.
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* 1. Agregar nuevos corregimientos o renombrar ciudades en Colombia
*/
add_filter( 'cod_form_colombia_places', function( $places ) {
// Agregar un corregimiento en Antioquia (ANT)
if ( isset( $places['ANT'] ) && is_array( $places['ANT'] ) ) {
$places['ANT'][] = 'San Antonio de Prado (Medellín)';
$places['ANT'][] = 'Santa Elena (Medellín)';
sort( $places['ANT'] );
}
// Estandarizar el nombre de una ciudad en Cundinamarca (CUN) para coincidir con transportadora
if ( isset( $places['CUN'] ) && is_array( $places['CUN'] ) ) {
$index = array_search( 'San Juan de Rioseco', $places['CUN'], true );
if ( false !== $index ) {
$places['CUN'][ $index ] = 'San Juan de Río Seco';
}
}
return $places;
}, 10, 1 );
4. Receta 2: Personalizar Estados y Municipios en México (MX) o Ecuador (EC)
/**
* Modificar etiquetas de estados en México y añadir colonias/municipios clave
*/
add_filter( 'cod_form_mexico_states', function( $states ) {
if ( isset( $states['DF'] ) ) {
$states['DF'] = 'Ciudad de México (CDMX)';
}
return $states;
}, 10, 1 );
add_filter( 'cod_form_mexico_places', function( $places ) {
if ( isset( $places['JAL'] ) && is_array( $places['JAL'] ) ) {
if ( ! in_array( 'Tlajomulco de Zúñiga Centro', $places['JAL'], true ) ) {
$places['JAL'][] = 'Tlajomulco de Zúñiga Centro';
}
}
return $places;
}, 10, 1 );
5. Receta 3: Trabajar con el Modo Perú V2 de 3 Niveles (Departamento → Provincia → Distrito)
Cuando activas la opción cod_form_peru_use_districts = yes en un sitio con país base Perú (PE), el plugin carga la clase especializada PRCOD_States_Places_Peru_V2 y los archivos includes/states/PEV2.php e includes/places/PEV2.php.
En este modo de 3 niveles, el array $places tiene una estructura asociativa de dos niveles: el primer índice es el código del Departamento (ej. 'LIM' para Lima), el segundo índice es la Provincia (ej. 'Lima'), y su valor es el listado de Distritos (que se guardan en el pedido bajo _billing_district):
/**
* Agregar o personalizar un distrito en Perú V2 (3 niveles: Departamento -> Provincia -> Distrito)
*/
add_filter( 'cod_form_peru_places', function( $places ) {
// Verificar si estamos en la estructura anidada de PEV2 (Provincia => array de Distritos)
if ( isset( $places['LIM']['Lima'] ) && is_array( $places['LIM']['Lima'] ) ) {
if ( ! in_array( 'Santa María de Huachipa', $places['LIM']['Lima'], true ) ) {
$places['LIM']['Lima'][] = 'Santa María de Huachipa';
sort( $places['LIM']['Lima'] );
}
}
return $places;
}, 10, 1 );