Criar um envio único

CreateDeclarationShipment encadeia seis mutations *Workflow num único pedido GraphQL. Cada passo baseia-se nos dados fornecidos pelos passos anteriores, e todos são submetidos em conjunto, para que um envio completo possa ser criado numa única ida e volta:

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

As mutations Workflow foram concebidas para serem encadeadas: não precisa de passar IDs de um passo para o seguinte, nem de enviar um pedido separado por passo. Submeta o documento completo e receba o Shipment final.

Quando o serviceLevel do passo final é um nível de serviço Japan Post (japan_post.*), a Zonos chama a Japan Post Label API (código 52) em seu nome, utilizando os Later Pay Numbers da sua Verified Account, gera a etiqueta e o número de seguimento, cria o Declaration ID e associa-os — tudo dentro desse passo final shipmentCreateWorkflow.

Porquê uma única mutation? Cada passo depende do anterior (o landed cost precisa dos itens + partes; a etiqueta precisa de tudo). Agrupá-los num único documento GraphQL mantém os dados consistentes e evita cinco idas e voltas adicionais.

Endpoint e autenticação 

Todos os pedidos desta cadeia utilizam o mesmo endpoint. O que indica nos cabeçalhos depende da sua configuração — escolha o separador correspondente.

URL:

https://api.zonos.com/graphql

Cabeçalhos:

credentialToken: {{YOUR_API_TOKEN}}

Exemplo de pedido 

Um pedido CreateDeclarationShipment completo que pode copiar e adaptar — a mutation, as respetivas variáveis e a resposta — para um único pacote Japan Post enviado em DDP para os EUA. Cada dado de entrada é detalhado na secção passo a passo abaixo.

Passo a passo 

A coluna Status de cada tabela abaixo utiliza estes termos:

• Obrigatório — o pedido falha sem ele.
• Obrigatório para a etiqueta — opcional no schema GraphQL, mas necessário para produzir uma etiqueta Japan Post válida para os EUA.
• Condicional — obrigatório consoante outro campo (indicado na própria linha).
• Recomendado — opcional, mas determina o cálculo exato de direitos e impostos.
• Opcional — não é necessário.

1. partyCreateWorkflow

Cria as partes envolvidas no envio — no mínimo um ORIGIN (o local de onde o envio é expedido) e um DESTINATION (o comprador / destinatário).

Exemplo de payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

A resposta devolve os IDs de Party criados e os campos de morada resolvidos.

2. itemCreateWorkflow

Cria as linhas de artigos que compõem o envio. São os SKUs que vão constar da fatura comercial e que determinam o cálculo do landed cost.

O código HS, o país de origem e o valor são os três campos que mais influenciam o resultado de direitos/impostos no passo 5.

3. cartonsCreateWorkflow

Cria os volumes físicos — as caixas, sacos de plástico ou cartas que vão conter os itens.

Cada carton corresponde a um volume na etiqueta da transportadora no passo 6. Vários cartons → envio com vários volumes, com um número de seguimento por carton.

4. shipmentRatingCreateWorkflow

Regista a cotação de envio que o comerciante cobra ao comprador pelo envio.

É a tarifa cotada ao comprador no checkout. Entra no cálculo do landed cost como subtotal de "shipping", para que os direitos e impostos sejam calculados sobre o valor CIF correto.

5. landedCostCalculateWorkflow

Executa o cálculo de direitos, impostos e taxas para o país de destino. Utiliza os itens, as partes e o custo de envio dos passos anteriores.

A resposta inclui amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — são os valores que apresenta ao comprador no checkout e que são impressos na fatura comercial.

6. shipmentCreateWorkflow

O passo final — cria a entidade Shipment, gera a etiqueta da transportadora e (opcionalmente) a fatura comercial / guia de remessa.

Para as Verified Accounts da Japan Post, é também aqui que a Zonos chama a Japan Post Label API (código 52) em seu nome, insere os seus Later Pay Numbers, cria o Declaration ID e associa o Declaration ID ao número de seguimento devolvido pela Japan Post.

Campos principais:

Em contentsType, os dois valores mais comuns para o tráfego de Verified Accounts são ECOMMERCE_GOODS (vendido a um consumidor, BtoC) e COMMERCIAL_GOODS (vendido entre empresas, BtoB). Estes valores definem o pkgType que a Zonos envia na chamada de etiqueta da Japan Post, pelo que a escolha altera o que é impresso na declaração aduaneira — não é apenas uma classificação.

Sub-input nonDelivery

Indica à Japan Post o que fazer com o volume se não puder ser entregue — recusado pelo destinatário, rejeitado na fronteira ou impossível de entregar na morada indicada.

option aceita exatamente estes quatro valores. Não existe o valor RETURN — utilize RETURN_AFTER_RETENTION ou RETURN_IMMEDIATELY para escolher quando o volume é devolvido.

A API disponibiliza as duas variantes de devolução em separado; a opção Return do Dashboard abrange ambas.

transportMethod aceita AIR ou MOST_ECONOMICAL e define como um volume devolvido é transportado de volta. Aplica-se apenas às duas opções RETURN_* — o Dashboard só mostra o campo correspondente Return method quando Return está selecionado.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

O seletor If undeliverable da caixa de diálogo Create label do Dashboard grava este mesmo campo, pelo que uma etiqueta criada no Dashboard e uma etiqueta criada através da API comportam-se de forma idêntica.

Sub-input references

Estes campos são impressos na etiqueta da transportadora e/ou na fatura comercial. Utilize-os para apresentar números de ordem de compra (PO), números de licença e observações em texto livre que o destinatário ou a autoridade aduaneira precisem de ver.

Resposta

Os campos relevantes do Shipment devolvido são:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number é o número de seguimento da Japan Post.

O objeto label pode devolver a etiqueta de duas formas — peça a que melhor se adequar ao seu fluxo (ou ambas):

Selecione apenas os campos de que precisa. Pedir url mantém a resposta pequena; pedir labelImage devolve a etiqueta completa na resposta, sem necessidade de uma segunda ida e volta para a obter. O exemplo acima pede url.

Níveis de serviço Japan Post 

Indique um destes códigos como serviceLevelCode em shipmentRatingCreateWorkflow.

Os códigos de nível de serviço utilizam pontos, não underscores. Pode ver a forma com underscores (japan_post_air_parcel) em mensagens de erro e referências internas, mas não é um dado de entrada válido.

Serviços aéreos

Serviços de superfície

Escolher entre serviços semelhantes

Pequeno pacote vs. International Air Packet. Ambos estão limitados a 2 kg. japan_post.air.packet é o serviço de pequenos pacotes com seguimento da Japan Post. japan_post.air.small_packet é o equivalente sem seguimento. Se precisar de seguimento para um volume leve, utilize japan_post.air.packet.

Variantes registadas. Para cartas e impressos, o seguimento é acrescentado pela versão registada (書留) do serviço. japan_post.air.printed_matter e japan_post.air.letter não o incluem por si só.

Códigos descontinuados

japan_post.air.epacket_light correspondia ao International e-Packet Light. A Japan Post mudou o nome do serviço para International Air Packet a 1 de junho de 2026 e alargou-o a todos os países e regiões. O serviço em si não foi alterado.

O código antigo continua a ser reconhecido, para que as integrações existentes continuem a funcionar, mas utilize japan_post.air.packet em novos desenvolvimentos.

Códigos de modo de transporte

japan_post.air, japan_post.surface, japan_post.economy_air e japan_post.custom também são reconhecidos, mas identificam um modo de transporte ou uma alternativa de recurso, e não um produto postal específico. Utilize um dos códigos de serviço acima para envios normais.

Valide o código que envia

Um serviceLevelCode não reconhecido não gera um erro. O pedido devolve HTTP 200 sem array errors, serviceLevel é devolvido como null e o custo de envio deixa de constar do total do landed cost — pelo que a resposta parece correta, mas os valores estão errados.

Confirme sempre que shipmentRatingCreateWorkflow.serviceLevel não é nulo antes de confiar nos totais.

Para obter a lista atual a qualquer momento:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Esta query recebe o ID da transportadora. Indicar o código da transportadora japan_post devolve uma lista vazia, sem qualquer erro.

Tratamento de erros 

• Erros de validação (campos obrigatórios em falta, códigos de país inválidos, etc.) são devolvidos no array errors padrão do GraphQL e interrompem o resto da cadeia.
• Erros da Japan Post (falha na geração da etiqueta, morada inválida, etc.) surgem como erros GraphQL em shipmentCreateWorkflow. Se for necessário repetir, contacte o suporte — o procedimento recomendado é voltar a submeter a mutation completa com os dados de entrada corrigidos.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Este erro indica a variável completa, não o campo que está realmente errado. Quase sempre significa que um valor de enum dentro dessa variável não pertence ao respetivo enum — na maioria dos casos nonDelivery.option, contentsType ou serviceLevel.

Não é um problema de tipos JSON. Colocar ou retirar aspas nos seus booleanos e números não o resolve, porque o payload nem chega a essa fase — o enum é rejeitado primeiro.

Para encontrar o campo errado, compare cada campo com valor de enum na variável com os respetivos valores aceites:

Todos os membros do enum de qualquer input estão listados na página do respetivo tipo na referência da API.

Permissões 

Cada passo é protegido de forma independente. A sua API key tem de ter o âmbito de escrita para cada entidade da cadeia (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). A função padrão de comerciante numa Verified Account concede todos estes âmbitos.

Próximos passos 

• Expedição em lote (consolidação) — agrupe os volumes do dia numa única guia de expedição Japan Post com pagamento diferido.