Já cria etiquetas com a Japan Post My Page API? Mantenha sua integração — adicione a Zonos para etiquetas com destino aos EUA e tarifas pré-pagas.
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.
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:
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.
Cria o Declaration ID de tarifas dos EUA e o vincula ao número de rastreamento.
Adiciona a marcação DDP à etiqueta.
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.
A Zonos trata isto por você
Você não envia credenciais da Japan Post nem o código da operação (ctCode, ctId, ctPw), a data de envio (sendDate) ou as observações de declaração DDP. A Zonos define isso automaticamente ao chamar a My Page.
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.
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).
Quando criar uma etiqueta dos EUA pela Zonos, confirme que funcionou de ponta a ponta:
O fluxo retorna um número de rastreamento e uma etiqueta. Verifique shipmentCreateWorkflow.trackingDetails.number e shipmentCartons[].label.url na resposta.
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.
DDP está impresso na etiqueta. Abra a etiqueta retornada e confirme a marcação DDP.
O envio aparece no Zonos Dashboard na sua Verified Account.
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).
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.
Teste antes de ir para produção
Valide o fluxo completo em um envio de teste antes de enviar volume de produção para os EUA pela Zonos. Sua integração My Page permanece no lugar para todo o resto.
Usar a Zonos com a My Page API
Usar a Zonos com a Japan Post My Page API
Já cria etiquetas com a Japan Post My Page API? Mantenha sua integração — adicione a Zonos para etiquetas com destino aos EUA e tarifas pré-pagas.
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
CreateDeclarationShipmentda Zonos em vez de chamar a My Page diretamente. Nessa única solicitação, a Zonos: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.O
CreateDeclarationShipmentencadeia sete etapas. Os mesmos dados que você já monta para uma solicitaçãoctCode=52são distribuídos entre elas:ORIGINeDESTINATIONdopartyCreateWorkflow.itemCreateWorkflow(os itens de linha dentro deshipmentCartons).cartonsCreateWorkflow.shipmentCreateWorkflow.Você não envia credenciais da Japan Post nem o código da operação (
ctCode,ctId,ctPw), a data de envio (sendDate) ou as observações de declaração DDP. A Zonos define isso automaticamente ao chamar a My Page.Como seus campos My Page mapeiam para a Zonos
Cada tabela mostra onde um parâmetro Japan Post My Page
ctCode=52vai 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 →
shipmentCreateWorkflowsendType+transTypeserviceLevel(andshipmentRatingCreateWorkflow.serviceLevelCode)japan_post.air.parcel. Deve ser um níveljapan_post.*.pkgTypecontentsTypeSALE_OF_GOODS,ECOMMERCE_GOODS,COMMERCIAL_GOODS,COMMERCIAL_SAMPLE,RETURNED_GOODS,GIFT,DOCUMENTSouOTHER.senderInstructionnonDelivery.optionRETURN_AFTER_RETENTION,RETURN_IMMEDIATELY,FORWARDouABANDON. A Zonos divide a instrução única de “retorno” da My Page em dois valores.fw_TransTypenonDelivery.transportMethodAIRouMOST_ECONOMICAL.noCmisNonCommercialtrue/false.damgesdeclaredValuetotalWeightcartonsCreateWorkflow.weight+weightUnitRemetente →
partyCreateWorkflow(parteORIGIN)from_namperson.firstName+person.lastNamefrom_companyNameperson.companyNamefrom_postallocation.postalCodefrom_add1/from_add2/from_add3location.line1/location.line2/location.localityfrom_preflocation.administrativeAreaCodefrom_telperson.phoneDestinatário →
partyCreateWorkflow(parteDESTINATION)Os parâmetros
to_*do destinatário mapeiam para a parteDESTINATIONda mesma forma que os campos do remetente.to_namperson.firstName+person.lastNameto_companyNameperson.companyNameto_couCdlocation.countryCodeUSouPR.to_add1/to_add2/to_add3location.line1/location.line2/location.localitylocation.postalCode/location.administrativeAreaCode/person.phoneItens →
itemCreateWorkflowitem_pkgcustomsDescriptionitem_hsCodehsCodeitem_numquantityitem_weightmeasurements(per-unit weight)item_costamountitem_curUnitcurrencyCodeConversões importantes
Estas são as transformações que mais precisam de atenção:
sendType+transType. Escolha o único nível de serviço Zonosjapan_post.*que corresponde ao serviço postal e ao transporte que você envia hoje como dois parâmetros separados.declaredValue) deve ser JPY, ienes inteiros. Outras moedas ou frações de iene serão rejeitadas.weight+weightUnitna caixa; a Zonos converte.Verificar suas etiquetas dos EUA
Quando criar uma etiqueta dos EUA pela Zonos, confirme que funcionou de ponta a ponta:
shipmentCreateWorkflow.trackingDetails.numbereshipmentCartons[].label.urlna resposta.Valide o fluxo completo em um envio de teste antes de enviar volume de produção para os EUA pela Zonos. Sua integração My Page permanece no lugar para todo o resto.
Relacionado
CreateDeclarationShipment.Esta página foi útil?