Guía de domicilios de envío
Buenas prácticas para mejorar la tasa de entrega de tus tarjetas.
Introducción
El objetivo de esta guía es ayudarte a crear envíos con domicilios de entrega efectivos, respetando las particularidades de cada país y los requisitos de los operadores logísticos.
Un domicilio bien estructurado permite:
- Aumentar la tasa de entregas exitosas
- Reducir rechazos por validaciones automáticas
- Evitar correcciones manuales y reprocesos
- Mejorar la experiencia del usuario final
Funcionamiento de nuestro modelo de domicilios
Desde Pomelo, actuamos como orquestador logístico, integrándonos con distintas transportadoras según el país.
Para reducir dependencias y complejidad, usamos un modelo de domicilio homogéneo, que luego se transforma internamente según los requisitos de cada proveedor logístico.
address estructurado, donde cada campo cumple un rol específico en el flujo de distribución.
Campos que componen un domicilio de envío
En esta tabla te mostramos cómo interpretar cada campo del objeto address según el país, para facilitar la carga correcta de domicilios y reducir errores de entrega.
| Campo API (Pomelo) | Argentina | Brasil | Colombia | México | Perú |
|---|---|---|---|---|---|
street_name | Calle / Avenida | Rua / Avenida | Tipo de vía (Calle, Carrera, Avenida) | Calle / Avenida | Calle / Avenida |
street_number | Numeración | Número | Número / Letras | Número exterior | Número exterior |
floor | Piso | Andar | Piso | Piso | Piso |
apartment | Departamento | Apartamento / Sala | Apartamento | Departamento | Departamento |
neighborhood | Barrio | Bairro | Barrio | Colonia / Barrio | Distrito |
city | Localidad / Ciudad | Cidade | Ciudad | Ciudad | Ciudad |
region | Provincia | UF (Estado) | Departamento | Estado | Departamento |
zip_code | Código Postal | CEP | Código Postal (opcional) | Código Postal | Código Postal / Ubigeo |
country | País | País | País | País | País |
additional_info | Referencias | Observações | — | Referencias | Referencias |
Buenas prácticas generales
✅ Recomendamos
- Separar correctamente calle y número
- Usar el tipo de vía completo: “Avenida”, “Calle”, “Carrera”, “Rua”
- Usar tildes cuando correspondan
- Completar
floor,apartmentoadditional_infocuando aplique - Usar nomenclatura local (barrios, colonias, distritos)
- Mantener consistencia entre todos los campos del
address
❌ Evitar
- Enviar todo el domicilio en un solo campo
- Usar caracteres especiales no permitidos (@, &, /, ())
- Omitir el número de puerta
- Mezclar formatos entre países
- Dejar campos obligatorios vacíos
- Modificar direcciones cuando el envío ya está en reparto
Ejemplos completos por país
Los siguientes ejemplos muestran cómo enviar el objeto address en el endpoint de creación y actualización de domicilio.
🇦🇷 Argentina
🇧🇷 Brasil
📌 Completa el campo region con la Unidade Federativa (UF) de 2 letras que corresponda.
🇨🇴 Colombia
📌 El campo zip_code puede ser opcional según la operación.
🇲🇽 México
🇵🇪 Perú
Recomendación final
Un domicilio correctamente estructurado es el primer paso para garantizar una entrega exitosa.
Seguir estas buenas prácticas permite:
- Procesar los envíos de forma más predecible
- Reducir errores operativos
- Maximizar la probabilidad de que la tarjeta llegue a destino
Ante dudas o casos especiales, recomendamos revisar la documentación oficial o contactar a nuestro equipo de soporte vía Dashboard.