Uso de Zonos con la Japan Post My Page API

Esta guía es para equipos que ya integran la Japan Post My Page Web API para crear etiquetas (operación ctCode=52). Para paquetes con destino a EE. UU., que ahora requieren aranceles prepagados, crea la etiqueta a través de Zonos. Zonos es una extensión del flujo de My Page: llama a la My Page Label API (ctCode=52) en su nombre, agrega el Declaration ID de aranceles de EE. UU. y la marca DDP, y le devuelve la etiqueta y el número de seguimiento de My Page. Japan Post sigue produciendo la etiqueta y facturando su franqueo a través de su Later Pay Number.

En resumen: sigue construyendo sobre My Page, y Zonos gestiona la capa de aranceles de EE. UU. para envíos con destino a Estados Unidos.

Si integra por primera vez, comience con Crear un envío individual.

Cómo encaja Zonos 

Para un paquete con destino a EE. UU., envía el envío al flujo GraphQL CreateDeclarationShipment de Zonos en lugar de llamar directamente a My Page. En esa única solicitud, Zonos:

1. Llama a la Japan Post Label API (ctCode=52) en su nombre, usando los Later Pay Numbers de su Verified Account para que el franqueo siga facturándose a su cuenta de Japan Post.
2. Crea el Declaration ID de aranceles de EE. UU. y lo vincula al número de seguimiento.
3. Agrega la marca DDP a la etiqueta.
4. Le devuelve la etiqueta y el número de seguimiento de Japan Post.

CreateDeclarationShipment encadena siete pasos. Los mismos datos que ya reúne para una solicitud ctCode=52 se distribuyen entre ellos:

• Remitente / destinatario → las partes ORIGIN y DESTINATION de partyCreateWorkflow.
• Artículos → itemCreateWorkflow (los artículos dentro de shipmentCartons).
• Embalaje y peso → cartonsCreateWorkflow.
• Servicio, manejo y banderas aduaneras → shipmentCreateWorkflow.

Cómo se mapean sus campos de My Page a Zonos 

Cada tabla muestra dónde va un parámetro de Japan Post My Page ctCode=52 en el flujo de Zonos. Para detalles completos de campos, tipos y cuáles son obligatorios, consulte Crear un envío individual.

Servicio y manejo → shipmentCreateWorkflow

Remitente → partyCreateWorkflow (parte ORIGIN)

Destinatario → partyCreateWorkflow (parte DESTINATION)

Los parámetros to_* del destinatario se mapean a la parte DESTINATION de la misma forma que los campos del remitente.

Artículos → itemCreateWorkflow

Conversiones a tener en cuenta 

Estas son las transformaciones que más a menudo requieren atención:

• El nivel de servicio reemplaza sendType + transType. Elija el único nivel de servicio japan_post.* de Zonos que coincida con el servicio postal y el transporte que envía hoy como dos parámetros separados.
• El valor asegurado (declaredValue) debe estar en JPY, yenes enteros. Otras monedas o yenes fraccionarios serán rechazados.
• El peso se envía a Japan Post en gramos. Proporcione weight + weightUnit en el cartón; Zonos convierte.
• Las descripciones aduaneras de artículos están limitadas a 85 caracteres de ancho medio.
• Todos los campos de dirección deben estar en caracteres ingleses (romanos).

Verificar sus etiquetas de EE. UU. 

Cuando crea una etiqueta de EE. UU. a través de Zonos, confirme que funcionó de extremo a extremo:

1. El flujo devuelve un número de seguimiento y una etiqueta. Verifique shipmentCreateWorkflow.trackingDetails.number y shipmentCartons[].label.url en la respuesta.
2. Se creó y vinculó un Declaration ID. El envío tiene aranceles prepagados solo cuando el Declaration ID está vinculado al número de seguimiento; Zonos hace esto dentro de la misma solicitud.
3. DDP está impreso en la etiqueta. Abra la etiqueta devuelta y confirme que la marca DDP está presente.
4. El envío aparece en su Zonos Dashboard bajo su Verified Account.
5. Para despacho por lotes, confirme que la consolidación se cierra y devuelve el comprobante de despacho de Japan Post (Code 61). Consulte Despacho por lotes (consolidación).
6. Compare con una etiqueta de My Page. Cree el mismo envío de ambas formas y confirme que el nivel de servicio, el peso, el valor declarado y los detalles de los artículos coinciden en la etiqueta impresa.

Relacionado 

• Crear un envío individual — referencia completa de campos para el flujo CreateDeclarationShipment.
• Despacho por lotes (consolidación) — agrupe los paquetes del día en un comprobante de despacho de Japan Post.