Plugin de WordPress — Copomex for WordPress

Plugin oficial para WordPress 5.5+ / PHP 8.1+. Usa la WP HTTP API, sin dependencias externas. Expone la API en 4 capas: clase PHP, shortcodes, REST proxy y panel de admin.

Instalación

Desde el panel de WordPress

1. Ve a Plugins → Añadir nuevo → Subir plugin
2. Sube el archivo .zip del plugin
3. Actívalo

Manual

Copia la carpeta copomex/ a wp-content/plugins/ y actívalo desde Plugins.

Configuración

Ve a Ajustes → Copomex e ingresa tu token de API.

Usa pruebas como token para desarrollo — sin costo, sin registro, devuelve datos aleatorios con estructura real.

Estructura del plugin

copomex/
├── copomex.php                          # Header + bootstrap
├── includes/
│   ├── class-copomex-client.php         # Clase principal (24 métodos)
│   ├── class-copomex-exception.php      # Excepciones tipadas
│   ├── class-copomex-admin.php          # Página de ajustes
│   ├── class-copomex-shortcodes.php     # Shortcodes
│   └── class-copomex-rest.php           # REST proxy
└── example/
    └── example.php                      # Snippets de uso

Capa 1 — Clase PHP (para desarrolladores)

Copomex_Client está disponible globalmente una vez activo el plugin. Toma el token de Ajustes → Copomex de forma automática.

$client = new Copomex_Client();
 
// Con token explícito
$client = new Copomex_Client('TU_TOKEN');

Manejo de errores

try {
    $result = $client->info_cp('00000');
} catch (Copomex_API_Exception $e) {
    // $e->api_code, $e->api_message
} catch (Copomex_HTTP_Exception $e) {
    // $e->status_code
}

Códigos postales

// Info completa (una entrada por colonia)
$client->info_cp('06600');
 
// Info simplificada (un objeto)
$client->info_cp('06600', simplified: true);
 
// Búsqueda parcial
$client->search_cp('066', limit: 10);
 
// Colonias de un CP
$client->get_colonia_por_cp('06600');
 
// CPs de un estado
$client

Estados

$client->get_estados();
$client->get_estado_clave();

Municipios

$client->get_municipio_por_estado('Jalisco');
$client->get_municipio_clave_por_estado('Jalisco');
$client->get_municipio_clave_por_clave_estado('14');

Colonias

$client->get_colonia_por_municipio('Guadalajara');
$client->get_colonia_por_estado_municipio('Jalisco', 'Guadalajara');

Ciudades

$client->get_cities_by_state_code('14');

Localidades

$client->get_localidad_por_estado_municipio('Jalisco', 'Guadalajara');
$client->get_localidad_por_clave_estado_municipio('14', '039');
$client->info_localidad('14', '039', '0001');

Vialidades

$client->get_vialidad('14', '039', 'juarez', 10);
$client->get_tipo_vialidad();

Geocoding (2 créditos por consulta)

$client->info_cp_geocoding('06600');
$client->info_cp_geocoding('06600', calle: 'Insurgentes', numero: '123');
$client->info_cp_geocoding_reverse(19.4326, -99.1332);

Cuenta

$client->consultas_disponibles();
$client->ultima_actualizacion_db();

Capa 2 — Shortcodes (para editores de contenido)

No requieren PHP. Funcionan en cualquier editor de WordPress.

[copomex_info_cp cp="06600"]

Muestra información del código postal en una lista de definición (<dl>).

[copomex_info_cp cp="06600"]

[copomex_colonias cp="06600"]

Lista las colonias del código postal en una lista (<ul>).

[copomex_colonias cp="06600"]

Los elementos generados tienen clases CSS para estilizarlos desde tu tema:

Capa 3 — REST API proxy (para JavaScript / AJAX)

El plugin registra endpoints en la WP REST API que hacen de intermediario seguro. El token nunca sale al frontend.

Ejemplo — autocompletado de dirección desde JS

document.getElementById('cp').addEventListener('input', async (e) => {
  const cp = e.target.value;
  if (cp.length !== 5) return;
 
  const res  = await fetch(`/wp-json/copomex/v1/colonias-cp/${cp}`);
  const data = await res.json

Créditos API