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:

• Obrigatório — a requisição falha sem ele.
• Obrigatório para etiqueta — opcional no schema GraphQL, mas necessário para produzir uma etiqueta Japan Post válida para os EUA.
• Condicional — obrigatório conforme outro campo (indicado inline).
• Recomendado — opcional, mas determina impostos e tributos precisos.
• Opcional — 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 pela Japan Post.

Campos principais:

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

Sub-input nonDelivery

Informa à Japan Post o que fazer com o pacote se ele não puder ser entregue — recusado pelo destinatário, rejeitado na fronteira ou não entregável no endereço informado.

option aceita exatamente estes quatro valores. Não existe o valor RETURN — use RETURN_AFTER_RETENTION ou RETURN_IMMEDIATELY para escolher quando o pacote retorna.

A API expõe as duas variantes de devolução separadamente; a opção Return do Dashboard cobre ambas.

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

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

O seletor If undeliverable no diálogo Create label do Dashboard grava esse mesmo campo, então uma etiqueta criada no Dashboard e uma etiqueta criada via API se comportam de forma idêntica.

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.

Níveis de serviço Japan Post 

Passe um destes códigos como serviceLevelCode em shipmentRatingCreateWorkflow.

Os códigos de nível de serviço usam pontos, não underscores. Você pode ver a forma com underscore (japan_post_air_parcel) em mensagens de erro e referências internas, mas ela não é um input válido.

Serviços aéreos

Serviços de superfície

Escolhendo entre serviços semelhantes

Pacote pequeno vs. International Air Packet. Ambos têm limite de 2 kg. japan_post.air.packet é o serviço de pacote pequeno rastreado da Japan Post. japan_post.air.small_packet é o equivalente não rastreado. Se precisar de rastreamento para uma encomenda leve, use japan_post.air.packet.

Variantes registradas. Para cartas e impressos, o rastreamento é adicionado pela versão registrada (書留) do serviço. japan_post.air.printed_matter e japan_post.air.letter não o incluem por padrão.

Códigos descontinuados

japan_post.air.epacket_light era o International e-Packet Light. A Japan Post renomeou o serviço para International Air Packet em 1º de junho de 2026 e o expandiu para todos os países e regiões. O serviço em si não mudou.

O código antigo ainda funciona, então integrações existentes continuam funcionando, mas use japan_post.air.packet para novos desenvolvimentos.

Códigos de modo de transporte

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

Valide o código que você envia

Um serviceLevelCode não reconhecido não gera um erro. A requisição retorna HTTP 200 sem array errors, serviceLevel volta como null, e o frete some do total de landed cost — então a resposta parece correta, mas os valores estão errados.

Sempre verifique se 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
  }
}

Essa query recebe o ID da transportadora. Passar o código da transportadora japan_post retorna uma lista vazia sem erro.

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.

VALIDATION_INVALID_TYPE_VARIABLE

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

Este erro nomeia a variável inteira, não o campo que está realmente errado. Quase sempre significa que um valor de enum dentro dessa variável não é membro do seu enum — geralmente nonDelivery.option, contentsType ou serviceLevel.

Não é um problema de tipagem JSON. Colocar ou remover aspas dos seus booleanos e números não muda isso, porque o payload nem chega tão longe — o enum é rejeitado primeiro.

Para encontrar o campo problemático, verifique cada campo com valor de enum na variável em relação aos seus valores aceitos:

Os membros completos do enum para qualquer input estão listados na página de tipo correspondente na Referência da API.

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.