Criar um envio único

CreateDeclarationShipment encadeia seis mutations *Workflow em uma única requisição GraphQL. Cada etapa usa os dados das anteriores, e todas são enviadas juntas para criar um envio completo em uma única ida e volta:

partyCreateWorkflow            → descrever partes de origem e destino
itemCreateWorkflow             → descrever os itens de linha
cartonsCreateWorkflow          → descrever a embalagem física
shipmentRatingCreateWorkflow   → registrar a cotação de frete da transportadora
landedCostCalculateWorkflow    → calcular impostos / tributos / taxas
shipmentCreateWorkflow         → criar o envio + etiqueta

As mutations Workflow são projetadas para ser encadeadas: você não precisa passar IDs de uma etapa para a próxima nem enviar uma requisição separada por etapa. Envie o documento inteiro e receba o Shipment final.

Quando o serviceLevel na etapa 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 usando os Later Pay Numbers da sua Verified Account, gera a etiqueta e o número de rastreamento, cria o Declaration ID e os vincula — tudo na etapa final shipmentCreateWorkflow.

Por que uma mutation? Cada etapa depende da anterior (landed cost precisa dos itens + partes; a etiqueta precisa de tudo). Agrupá-las em um único documento GraphQL mantém os dados consistentes e evita cinco idas e voltas extras.

Endpoint e autenticação 

As requisições desta cadeia usam o mesmo endpoint. O que você passa nos cabeçalhos depende da sua configuração — escolha sua aba.

URL:

https://api.zonos.com/graphql

Cabeçalhos:

credentialToken: {{YOUR_API_TOKEN}}

Exemplo de requisição 

Uma requisição CreateDeclarationShipment completa para copiar e adaptar — a mutation, variáveis e resposta — para um pacote Japan Post enviado DDP aos EUA. Cada input é detalhado na seção passo a passo abaixo.

Passo a passo 

A coluna Status em cada tabela abaixo usa estes termos:

• Required — a requisição falha sem ele.
• Required for label — opcional no schema GraphQL, mas necessário para produzir uma etiqueta Japan Post válida para os EUA.
• Conditional — obrigatório conforme outro campo (indicado inline).
• Recommended — opcional, mas determina impostos e tributos precisos.
• Optional — não necessário.

1. partyCreateWorkflow

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

Exemplo de payload:

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

A resposta retorna os IDs Party criados e os campos de endereço resolvidos.

2. itemCreateWorkflow

Cria os itens de linha que compõem o envio. São os SKUs que aparecerão na fatura comercial e determinam o cálculo de landed cost.

O código HS, país de origem e valor são os três campos que mais influenciam o resultado de imposto/tributo na etapa 5.

3. cartonsCreateWorkflow

Cria os pacotes físicos — caixas, sacos plásticos ou cartas que conterão os itens.

Cada carton vira um pacote na etiqueta da transportadora na etapa 6. Vários cartons → envio multipiece com um número de rastreamento por carton.

4. shipmentRatingCreateWorkflow

Registra a cotação de frete que o comerciante cobra do comprador.

Esta é a tarifa cotada ao comprador no checkout. Alimenta o cálculo de landed cost como subtotal de "shipping" para que impostos e tributos sejam calculados sobre o valor CIF correto.

5. landedCostCalculateWorkflow

Executa o cálculo de impostos, tributos e taxas para o país de destino. Usa itens, partes e custo de frete das etapas anteriores.

A resposta inclui amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — números exibidos ao comprador no checkout e impressos na fatura comercial.

6. shipmentCreateWorkflow

Etapa final — cria a entidade Shipment, gera a etiqueta da transportadora e (opcionalmente) fatura comercial / packing slip.

Para Japan Post Verified Accounts, é aqui que a Zonos chama a Japan Post Label API (código 52) em seu nome, injeta seus Later Pay Numbers, cria o Declaration ID e o vincula ao número de rastreamento retornado pelo Japan Post.

Campos principais:

Sub-input references

Estes campos são impressos na etiqueta da transportadora e/ou fatura comercial. Use-os para exibir números de PO, licenças e observações que o destinatário ou alfândega precisam ver.

Resposta

Os campos relevantes no Shipment retornado são:

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

trackingDetails.number é o número de rastreamento Japan Post.

O objeto label pode retornar a etiqueta de duas formas — solicite a que se adaptar ao seu fluxo (ou ambas):

Selecione apenas os campos necessários. Solicitar url mantém a resposta pequena; solicitar labelImage retorna a etiqueta completa inline, sem segunda ida e volta. O exemplo acima solicita url.

Tratamento de erros 

• Erros de validação (campos obrigatórios ausentes, códigos de país inválidos, etc.) retornam no array GraphQL errors padrão e abortam o restante da cadeia.
• Erros Japan Post (falha na geração de etiqueta, endereço inválido, etc.) aparecem como erros GraphQL em shipmentCreateWorkflow. Se precisar tentar novamente, contate o suporte — o caminho recomendado é reenviar a mutation completa com input corrigido.

Permissões 

Cada etapa é protegida independentemente. Sua API key deve ter escopo 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 em Verified Account concede todos.

Próximos passos 

• Despacho em lote (consolidação) — agrupe os pacotes do dia em um dispatch slip Japan Post de pagamento diferido.