Usar a Zonos com a Japan Post My Page API

Este guia é para equipes que já integram com a Japan Post My Page Web API para criar etiquetas (operação ctCode=52). Para encomendas com destino aos EUA, que agora exigem tarifas pré-pagas, você cria a etiqueta pela Zonos. A Zonos é uma extensão do fluxo My Page: ela chama a My Page Label API (ctCode=52) em seu nome, adiciona o Declaration ID de tarifas dos EUA e a marcação DDP, e devolve a etiqueta My Page e o número de rastreamento. A Japan Post continua produzindo a etiqueta e cobrando o frete postal pelo seu Later Pay Number.

Em resumo: você continua construindo sobre a My Page, e a Zonos trata a camada de tarifas dos EUA para envios com destino aos Estados Unidos.

Se você está integrando pela primeira vez, comece por Criar um envio único.

Como a Zonos se encaixa 

Para uma encomenda com destino aos EUA, você envia o envio ao fluxo GraphQL CreateDeclarationShipment da Zonos em vez de chamar a My Page diretamente. Nessa única solicitação, a Zonos:

1. Chama a Japan Post Label API (ctCode=52) em seu nome, usando os Later Pay Numbers da sua Verified Account para que o frete postal continue sendo cobrado na sua conta Japan Post.
2. Cria o Declaration ID de tarifas dos EUA e o vincula ao número de rastreamento.
3. Adiciona a marcação DDP à etiqueta.
4. Devolve a etiqueta da Japan Post e o número de rastreamento.

O CreateDeclarationShipment encadeia sete etapas. Os mesmos dados que você já monta para uma solicitação ctCode=52 são distribuídos entre elas:

• Remetente / destinatário → as partes ORIGIN e DESTINATION do partyCreateWorkflow.
• Itens → itemCreateWorkflow (os itens de linha dentro de shipmentCartons).
• Embalagem e peso → cartonsCreateWorkflow.
• Serviço, handling e flags aduaneiros → shipmentCreateWorkflow.

Como seus campos My Page mapeiam para a Zonos 

Cada tabela mostra onde um parâmetro Japan Post My Page ctCode=52 vai no fluxo da Zonos. Para detalhes completos de campos, tipos e quais são obrigatórios, consulte Criar um envio único.

Serviço e handling → shipmentCreateWorkflow

Remetente → partyCreateWorkflow (parte ORIGIN)

Destinatário → partyCreateWorkflow (parte DESTINATION)

Os parâmetros to_* do destinatário mapeiam para a parte DESTINATION da mesma forma que os campos do remetente.

Itens → itemCreateWorkflow

Conversões importantes 

Estas são as transformações que mais precisam de atenção:

• O nível de serviço substitui sendType + transType. Escolha o único nível de serviço Zonos japan_post.* que corresponde ao serviço postal e ao transporte que você envia hoje como dois parâmetros separados.
• O valor segurado (declaredValue) deve ser JPY, ienes inteiros. Outras moedas ou frações de iene serão rejeitadas.
• O peso é enviado à Japan Post em gramas. Informe weight + weightUnit na caixa; a Zonos converte.
• As descrições aduaneiras de itens têm limite de 85 caracteres half-width.
• Todos os campos de endereço devem estar em caracteres ingleses (romanos).

Verificar suas etiquetas dos EUA 

Quando criar uma etiqueta dos EUA pela Zonos, confirme que funcionou de ponta a ponta:

1. O fluxo retorna um número de rastreamento e uma etiqueta. Verifique shipmentCreateWorkflow.trackingDetails.number e shipmentCartons[].label.url na resposta.
2. Um Declaration ID foi criado e vinculado. O envio só tem tarifas pré-pagas quando o Declaration ID está vinculado ao número de rastreamento — a Zonos faz isso na mesma solicitação.
3. DDP está impresso na etiqueta. Abra a etiqueta retornada e confirme a marcação DDP.
4. O envio aparece no Zonos Dashboard na sua Verified Account.
5. No despacho em lote, confirme que a consolidação fecha e retorna o dispatch slip da Japan Post (Code 61). Veja Despacho em lote (consolidação).
6. Compare com uma etiqueta My Page. Crie o mesmo envio das duas formas e confirme que nível de serviço, peso, valor declarado e detalhes dos itens coincidem na etiqueta impressa.

Relacionado 

• Criar um envio único — referência completa de campos do fluxo CreateDeclarationShipment.
• Despacho em lote (consolidação) — agrupe as encomendas do dia em um único dispatch slip da Japan Post.