Cómo agregar departamentos, provincias y distritos al checkout de WooCommerce
Opciones para adaptar el checkout de WooCommerce a las ubicaciones del Perú sin añadir campos innecesarios ni romper los envíos.
WooCommerce incluye país, región, ciudad, dirección y código postal, pero no organiza por defecto el checkout con departamentos, provincias y distritos del Perú como muchas tiendas necesitan.
Adaptarlo sirve para calcular envíos, normalizar direcciones y reducir errores. No significa que debas pedir el código oficial de ubigeo al cliente. En la mayoría de tiendas basta con mostrar listas dependientes y guardar los nombres de las ubicaciones.
Qué problema resuelve
Un campo libre de ciudad puede producir variantes como:
- San Juan de Lurigancho.
- SJL.
- San Juan L.
- Lima.
- Lima, SJL.
Eso dificulta aplicar tarifas por distrito, exportar pedidos y conectar facturación o logística.
Una estructura ordenada permite:
- Elegir departamento.
- Mostrar sus provincias.
- Mostrar los distritos de la provincia.
- Aplicar reglas de entrega.
- Guardar una dirección consistente.
Antes de modificar el checkout
Define para qué usarás los campos.
| Necesidad | Configuración posible |
|---|---|
| Solo vender en Lima | Lista de distritos o zonas de reparto |
| Vender a todo el Perú | Departamento, provincia y distrito |
| Cotizar el envío después | Ubicación para validar cobertura |
| Conectar un courier | Campos compatibles con su integración |
| Emitir comprobantes | Datos que solicite el sistema, sin mezclar dirección fiscal y entrega |
No añadas DNI, RUC, referencia, fecha de nacimiento o varios teléfonos como obligatorios sin una razón clara.
Opción 1: usar un plugin de ubicaciones peruanas
Es la ruta más sencilla cuando existe un plugin compatible con tu versión de WordPress y WooCommerce.
Antes de instalarlo, revisa:
- Fecha de actualización.
- Versiones compatibles.
- Soporte.
- Reseñas recientes.
- Cómo guarda los datos.
- Compatibilidad con bloques de checkout.
- Compatibilidad con el plugin de envíos o facturación.
- Qué ocurre al desactivarlo.
Haz la prueba en staging. Un plugin puede funcionar en el checkout clásico y fallar en el checkout basado en bloques, o modificar nombres de campos que otra integración espera.
No recomendamos un plugin universal porque la compatibilidad cambia. Evalúa el que utilice tu pasarela, facturador o proveedor logístico cuando exista una integración oficial.
Opción 2: usar zonas y métodos de envío
Si solo necesitas tarifas por áreas, quizá no haga falta implementar las tres listas.
WooCommerce permite crear zonas de envío. Puedes combinar:
- Recojo.
- Tarifa fija.
- Envío gratuito bajo condiciones.
- Métodos ofrecidos por plugins.
Para Lima, una solución puede agrupar distritos por zonas tarifarias. Para provincias, puedes separar departamentos o trabajar con una cotización posterior.
La ventaja es una configuración más simple. La desventaja es que WooCommerce no reconoce cada distrito de Perú de forma nativa, por lo que quizá necesites códigos postales, campos adicionales o un plugin.
Opción 3: desarrollo personalizado
Tiene sentido cuando:
- El negocio usa reglas propias.
- Hay integración con ERP, facturación o courier.
- Se necesita guardar código de ubigeo.
- Las tarifas dependen de varios campos.
- El plugin disponible no es compatible.
La personalización debe seguir los hooks y APIs de WooCommerce. Evita editar directamente el núcleo, el tema padre o el plugin: las actualizaciones borrarían los cambios.
Documenta:
- Nombre de cada campo.
- Clave con la que se guarda.
- Si aparece en pedidos y correos.
- Validaciones.
- Reglas de envío.
- Dependencias.
- Comportamiento si falta JavaScript.
¿Es necesario pedir el código de ubigeo?
Generalmente no. El cliente reconoce nombres, no códigos.
El código puede ser útil internamente para:
- Facturación.
- Logística.
- Bases de datos.
- Cruces con sistemas externos.
La interfaz puede mostrar Miraflores y guardar además el código correspondiente. No obligues al comprador a buscarlo.
Cómo ordenar los campos
Un orden habitual para productos físicos es:
- Nombre y apellidos.
- Teléfono.
- Correo.
- Departamento.
- Provincia.
- Distrito.
- Dirección.
- Referencia opcional.
Si el negocio emite factura, muestra los campos correspondientes solo cuando el cliente elija esa opción.
El código postal no se utiliza de forma uniforme en todas las operaciones peruanas. Si tu courier no lo requiere, evita convertirlo en obligatorio.
Configurar tarifas por distrito
No mezcles una lista de distritos con una tarifa plana sin probar todas las combinaciones.
Define una tabla de operación:
| Zona | Distritos | Tarifa | Plazo |
|---|---|---|---|
| Recojo | Punto definido | S/0 | Según horario |
| Zona 1 | Distritos cercanos | Según operación | Rango informado |
| Zona 2 | Distritos intermedios | Según operación | Rango informado |
| Fuera de cobertura | Otros | Cotización o bloqueo | No aplica |
Los valores deben corresponder con el costo real del negocio. Actualiza la tabla si cambia el operador.
Compatibilidad con facturación
La dirección de entrega y la información fiscal no siempre son lo mismo.
Comprueba qué datos envía la integración:
- Departamento.
- Provincia.
- Distrito.
- Código de ubigeo.
- RUC.
- Razón social.
- Tipo de comprobante.
Haz pedidos con boleta y factura. Un checkout que se ve bien puede guardar campos vacíos o enviarlos con claves incompatibles.
Revisa la guía sobre facturación electrónica para tiendas online.
Compatibilidad con pagos y bloques de checkout
Algunas personalizaciones antiguas dependen del checkout clásico. WooCommerce también ofrece bloques de carrito y checkout, cuyo sistema de extensibilidad es diferente.
Antes de cambiar el diseño:
- Confirma qué checkout está activo.
- Revisa documentación del plugin.
- Prueba la pasarela.
- Prueba la validación.
- Revisa el pedido en el administrador.
- Revisa correos y facturación.
No cambies al checkout por bloques en producción solo para solucionar el ubigeo.
Pruebas obligatorias
Prueba desde celular y computadora:
- Departamento con varias provincias.
- Provincia con muchos distritos.
- Cambio de selección después de completar la dirección.
- Distrito fuera de cobertura.
- Recojo.
- Tarifa gratuita.
- Cupón.
- Pago aprobado y rechazado.
- Boleta y factura.
- Correos.
- Edición del pedido en administración.
Comprueba que el total no cambie de forma inesperada al volver desde la pasarela.
Rendimiento y mantenimiento
Una base de ubicaciones extensa no debería cargarse repetidamente desde servicios externos lentos durante el checkout.
Evita:
- Llamadas innecesarias a APIs.
- Duplicar librerías.
- Cargar todos los distritos en cada página.
- Plugins abandonados.
- Código pegado sin documentación.
Después de actualizar WooCommerce, vuelve a probar el checkout. Es una parte crítica de la tienda.
Enlaces relacionados
- Cómo crear una tienda online en Perú
- Cómo instalar WordPress y WooCommerce
- Cómo elegir una pasarela de pago
- Qué hacer cuando WooCommerce no envía correos