Cómo formatear correctamente las direcciones internacionales: una guía para las API de envío

Para las etiquetas de envío internacionales legibles por máquina, cada dirección de destinatario debe generarse como un conjunto de campos estructurados, con el país de destino siempre en mayúsculas en la última línea. Quienes formatean direcciones internacionales no necesitan un formato global único, sino un sistema que comprenda las reglas de campo específicas de cada país, indique el nivel de confianza de los componentes y active una cola de revisión en caso de incertidumbre, en lugar de bloquear el proceso de compra.

Las tres reglas que debe cumplir toda dirección antes de que se imprima una etiqueta:

• Conjunto de campos estructurados: recipient_name, company, address_line_1 (Calle + número de casa), address_line_2 (Piso/nivel adicional), postal_code, city, administrative_area, country_code — en este orden, almacenados por separado, nunca como un bloque de texto libre.
• Última línea = PAÍS EN MAYÚSCULAS: Escrito íntegramente en un idioma comprensible internacionalmente, sin abreviaturas.
• Confianza en los componentes antes de imprimir las etiquetas: Cada campo recibe su propia puntuación de confianza; los campos con una puntuación baja activan la confirmación del cliente o una revisión manual, no un rechazo definitivo del proceso de compra.

Hallazgos importantes

Las direcciones extranjeras con formato correcto, que cuentan con un nivel de confianza en los componentes y una cola de revisión automática, son el método más fiable para evitar rechazos y devoluciones por parte de las empresas de transporte.

Tema	Detalles
Estructura obligatoria para las etiquetas	Conjunto de campos estructurados con country_display como la última línea en mayúsculas, máximo cinco líneas.
captura prioritaria para el país	Identificar primero el país de destino mejora la precisión del análisis y activa las reglas de validación específicas de cada país.
Puntuación de confianza	Cada campo de la dirección recibe su propia puntuación; las puntuaciones bajas activan la confirmación del cliente o la cola de revisión.
Transliteración y guion original	Se guardan ambas versiones: la versión en latín para la API del operador y la versión original para la entrega local.
Paquete internacional	Generación automatizada de etiquetas y formularios aduaneros, mapeo de múltiples transportistas y validación de direcciones en una sola plataforma.

Contenido

• ¿Qué campos de dirección debe mostrar su sistema por defecto?
• Qué normas de la UPU y del país debes seguir siempre
• Cuándo transcribir, cuándo preguntar al cliente.
• Cómo debería ser el flujo de trabajo de validación automatizada
• Qué debe tener en cuenta con respecto al diseño de la etiqueta y las especificaciones del código de barras.
• Lista de verificación para desarrolladores y mapeo JSON de ejemplo
• ¿Qué casos de prueba evitan errores de envío?
• El paquete internacional automatiza el formato, la validación y la generación de etiquetas.
• Mar de fondo

¿Qué campos de dirección debe mostrar su sistema por defecto?

La API del transportista no acepta direcciones en texto libre. Requiere campos específicos con nombre. La siguiente tabla muestra el esquema mínimo para etiquetas de envío internacionales:

El campo raw_local_script Puede parecer opcional, pero para transportistas como DHL suele ser obligatorio para los envíos a Japón o China, ya que el personal de reparto local no puede leer la versión transliterada. Soluciones internacionales de autocompletado y verificación Reduce los errores tipográficos desde el principio y estandariza las direcciones antes de guardar.

Consejo profesional: Speichern Sie raw_local_script Siempre junto a la versión transliterada. Proporcione al transportista el texto en latín; conserve el original para devoluciones y servicios de entrega locales.

Qué normas de la UPU y del país debes seguir siempre

La La Unión Postal Universal (UPU) recomiendaEl formato de la dirección de destino debe ajustarse a las especificaciones del país de destino, y el nombre del país debe aparecer completo, en mayúsculas, en la última línea. Esta recomendación es importante: los sistemas de clasificación de las compañías telefónicas interpretan la última línea como el código de país.

Otros requisitos vinculantes que suelen causar problemas:

• Máximo cinco líneas en la etiqueta de envío; a menudo, los escáneres automáticos no capturan todas las líneas.
• Posición de la mitad derecha La etiqueta de envío y el formulario de aduanas deben estar en la misma página, sin que se solapen con el código de barras ni con el campo de la dirección. Manual de correo internacional del USPS Prescribe el uso de mayúsculas en todas las líneas de la dirección y exige una dirección de remitente aparte.
• Fuente legible por máquina, sin lápiz, sin escritura a mano en las etiquetas de los transportistas.
• Características específicas de cada país: En los EE. UU., el estado está representado por una abreviatura de dos letras (p. ej. CA, NY) Obligatorio. En Francia, el código postal va antes de la ciudad (75001 PARISJapón y China esperan la dirección en orden inverso (país → provincia → ciudad → calle → nombre), la cual debe convertirse a un formato occidental para la impresión de etiquetas. Rusia requiere caracteres cirílicos para entregas locales, pero caracteres latinos para envíos internacionales. Los países sin códigos postales (por ejemplo, Irlanda, Hong Kong) requieren nombres de ciudades o distritos precisos.

Cuándo transcribir, cuándo preguntar al cliente.

La transliteración consiste en transferir los caracteres de un texto a sus equivalentes latinos, no en traducir el contenido. Москва se vuelve demasiado Moskva, no a MoscowEsta diferencia es relevante para los sistemas de telecomunicaciones porque una traducción puede distorsionar el nombre del lugar.

Reglas prácticas para los sistemas de escritura más comunes:

• Cirílico (Rusia, Ucrania, Bulgaria): Utilice ISO 9 o GOST 7.79 como estándar de transliteración; guarde siempre ambas versiones.
• Kanji/Kana (Japón): Romanización Hepburn para las API de los operadores; la entrega local requiere el original.
• Árabe: Transliteración ALA-LC para servicios postales; conservar la escritura original para el personal de reparto local.
• Diacríticos (francés, español, alemán): Los transportistas como USPS aceptan la normalización ASCII (é → e), pero muchos operadores europeos procesan UTF-8 correctamente. Prueba explícitamente el comportamiento de tu operador.

La conversión automática es arriesgada en situaciones de alta incertidumbre. El USPS recomienda Para alfabetos no latinos, se debe proporcionar una traducción al inglés entre líneas o una representación romanizada. Si el sistema no puede ofrecer una transliteración fiable, el proceso de compra debe solicitar al cliente que seleccione un alfabeto latino.

Consejo profesional: Muestre al cliente un campo de vista previa con la dirección transliterada al finalizar la compra y solicite confirmación. Esto solo toma dos segundos y evita entregas erróneas.

Cómo debería ser el flujo de trabajo de validación automatizada

Un proceso listo para la producción de direcciones internacionales consta de cinco pasos, que se llevan a cabo en este orden:

• Código de país primero: Introduzca el país de destino en el primer campo. captura prioritaria para el país Esto mejora la precisión del análisis sintáctico porque todas las reglas subsiguientes (orden de los campos, formato del código postal, campos obligatorios) dependen del país.
• Análisis sintáctico en componentes: Analizar la entrada de texto libre en campos discretos. El análisis del número de casa es particularmente propenso a errores: en Alemania, el número de casa sigue al nombre de la calle (Hauptstraße 12), en los EE. UU. antes (12 Main Street).
• Normalización: Explicar las abreviaturas (Str. → Straße), Compruebe los formatos de código postal (US-ZIP: 5 o 9 caracteres, DE-PLZ: 5 caracteres), fuerce el uso de mayúsculas para las líneas de la etiqueta.
• Comparación de referencias y puntuación de confianza: Comparación con bases de datos de códigos postales (por ejemplo, la API de validación de direcciones de Google, Loqate). Google recomienda Tres posibles escenarios de respuesta: Aceptar (Dirección correcta, continuar) Confirmar (Se ha detectado una desviación, solicite confirmación al cliente) Solución (Faltan campos críticos, se requiere demanda).
• Cola de reserva y revisión: Si no es posible realizar una verificación de referencias a nivel de edificio, se debe recurrir al código postal y la ciudad. Los índices de confianza relacionados con los componentes y una cola de revisión manual son mejores que un bloqueo total del proceso de compra.

Consejo profesional: Llama a la API de validación al finalizar la compra, no después de que se haya completado el pago. Corregir una dirección después de la confirmación del pedido requiere mucho más trabajo que esperar un segundo al finalizar la compra.

Qué debe tener en cuenta con respecto al diseño de la etiqueta y las especificaciones del código de barras.

La etiqueta de envío y el formulario de aduanas deben estar en el mismo lado del paquete, preferiblemente en el lado derecho. El código de barras y el campo de dirección no deben superponerse. Requisitos específicos:

• Estándar de código de barras: GS1-128 o formatos específicos del transportista (DHL: código de barras de la guía de envío; UPS: MaxiCode + Code 128). Respete el contraste mínimo y el tamaño mínimo especificados por el transportista; un código de barras impreso demasiado pequeño provocará errores de escaneo.
• Fuente: Fuente sans-serif, tamaño mínimo de 8 pt para las líneas de dirección, se recomienda 10 pt. No se permiten notas al pie ni publicidad en las líneas de dirección.
• Dirección del remitente: Dirección completa del remitente en caracteres latinos, en la parte superior izquierda, claramente separada de la dirección del destinatario.
• Declaración de aduanas: Siempre electrónico y generado por computadora. El USPS y las principales compañías de transporte requieren declaraciones de aduana generadas por computadora con una descripción completa de las mercancías. Los documentos de aduana escritos a mano darán lugar a retrasos o rechazo por parte de las principales compañías de transporte. Consulte las instrucciones para la correcta colocación de Documentos de envío Se puede encontrar en la documentación del paquete internacional.

Lista de verificación para desarrolladores y mapeo JSON de ejemplo

Esquema JSON recomendado para una pila de envíos internacionales:

Nombre del campo	Tipo	deber	Nota del analizador sintáctico
country_code	Código ISO alfa-2	Ja	Captura siempre primero
recipient_name	Cadena de caracteres, máximo 35 caracteres	Ja	Por favor, respete el límite del transportista.
company	Cadena de caracteres, máximo 35 caracteres	Opcional	Déjelo en blanco si no está presente.
address_line_1	Cadena de caracteres, máximo 35 caracteres	Ja	Calle + número de casa, orden específico del país
address_line_2	Cadena de caracteres, máximo 35 caracteres	Opcional	Apartamento, Piso, c/o
postal_code	Cordón	condicionado	Validar expresiones regulares para cada país.
city	Cordón	Ja	escritura latina
administrative_area	Cordón	condicionado	Obligatorio para EE. UU., Canadá y Australia.
raw_local_script	Cordón	Opcional	Texto original para entrega local
transliterated	Cordón	condicionado	Versión en escritura latina para la API del operador

Un ejemplo típico de mapeo de entrada sin procesar a salida etiquetada:

{
  "raw_input": "田中太郎, 東京都渋谷区神南1-19-11",
  "parsed_components": {
    "country_code": "JP",
    "recipient_name": "田中太郎",
    "address_line_1": "神南1-19-11",
    "city": "渋谷区",
    "administrative_area": "東京都",
    "raw_local_script": "東京都渋谷区神南1-19-11"
  },
  "formatted_label_output": {
    "line_1": "TANAKA TARO",
    "line_2": "1-19-11 JINNAN",
    "line_3": "SHIBUYA-KU, TOKYO 150-0041",
    "line_4": "JAPAN"
  }
}

Puntos adicionales para la implementación:

• Establezca los tiempos de espera de la API en un máximo de 2 segundos; configure un proveedor de validación secundario como alternativa.
• Almacene las puntuaciones de confianza y las reglas de normalización en el campo de registro de auditoría (raw_input, fuente de datos de referencia utilizada, nivel de confianza por componente, marca de tiempo).
• No acepte sin más las modificaciones realizadas por los empleados.
• Gestione los datos de direcciones de acuerdo con el RGPD: limite el tiempo de almacenamiento, restrinja el acceso al equipo de envíos y no comparta los datos con terceros sin una base legal. Paket International ofrece interfaces preconfiguradas para la integración de API y complementos.

¿Qué casos de prueba evitan errores de envío?

Estos casos deben probarse explícitamente antes de pasar a producción:

• Falta el código postal: Los países que no tienen código postal (Irlanda, Hong Kong) deben poder procesarse sin necesidad de un campo de código postal obligatorio.
• Nombres de lugares duplicados: Springfield Existe en más de 30 estados de EE. UU. Sin administrative_area La dirección es ambigua.
• Caracteres especiales y diéresis: Müller → Mueller o en MullerPruebe el comportamiento de la compañía aérea de forma explícita para cada país de destino.
• Nombres largos: Los límites de caracteres de las operadoras suelen ser de 35 caracteres por línea. Nombres como Gesellschaft für internationale Handelsbeziehungen mbH debe abreviarse sin comprometer la capacidad de entrega.
• Direcciones APO/FPO (ejército estadounidense): Utiliza sus propias reglas de formato, no un formato estándar de calle.
• Escritos variados: Una dirección con un nombre de calle en cirílico y un nombre de ciudad en latín debe separarse y transcribirse correctamente.
• Mercancías voluminosas: Para envíos de gran tamaño, las empresas de transporte pueden requerir campos de dirección adicionales. Consulte la información a continuación. Planificación de transportes especiales Demostrar cómo se estructura la documentación para envíos de mercancías complejos.

Monitorear las métricas que deben rastrearse continuamente: tasa de respuesta por país de destino, tasa de error de escaneo por transportista, porcentaje de revisiones manuales, distribución de confianza por tipo de campo. Configurar alertas para tasas de rechazo de transportistas crecientes en países o áreas de código postal específicos.

Consejo profesional: Realice una revalidación masiva mensual de los datos de direcciones antiguos. Los nombres de las calles, los límites de los códigos postales y los requisitos de las empresas de mensajería cambian. Un acuerdo de nivel de servicio (SLA) para las revisiones manuales (por ejemplo, 24 horas) evita que los casos sin resolver bloqueen los envíos.

El paquete internacional automatiza el formato, la validación y la generación de etiquetas.

Cualquier persona que desee ampliar sus procesos de envío internacional pronto se encontrará con las limitaciones del mantenimiento manual de direcciones. Paket International combina estos pasos en una única plataforma: Software de envío multienvío Con generación automática de etiquetas y formularios aduaneros, gestión de direcciones basada en la confidencialidad y conexión directa con DHL, UPS, FedEx, DPD y DB Schenker.

 

La plataforma gestiona el análisis, la normalización y la asignación de transportistas, genera declaraciones de aduanas electrónicamente y dirige las direcciones no seguras a una cola de revisión en lugar de bloquear el pago. Para las tiendas en línea, una Plugin de WooCommerce Listo; una API abierta para pilas individuales. despacho de aduanas automatizado Reduce la intervención manual y disminuye la tasa de errores en los documentos aduaneros. Pruebe la integración ahora y procese su primer envío internacional de forma totalmente automatizada.

Mar de fondo

Recursos recomendados para la implementación y el cumplimiento:

• Elementos y formato de una dirección internacional — UPU
• Cómo enviar un paquete internacional | USPS
• Directrices para direcciones internacionales — USPS IMM
• Validación de direcciones para el proceso de pago | Plataforma de Google Maps
• Convierta la precisión de los datos de direcciones internacionales en el superpoder oculto de su negocio — Smarty

Recomendación

• Crear etiquetas de envío para vendedores online es más fácil que nunca.
• Documentos de envío: información importante y consejos
• Envíe envíos internacionales sin preocupaciones ni estrés.
• Envíos a la aduana de Suiza: Cómo evitar retrasos