Despacho em lote (consolidação)

Este documento descreve o fluxo em três fases para criar um lote de expedição com pagamento diferido da Japan Post através da API GraphQL da Zonos: abrir uma consolidação, associar-lhe n envios e, por fim, fechá-la para receber a guia de expedição (documento de manifesto) da Japan Post.

Os envios para os EUA e para a UE são agrupados em lote da mesma forma. Para envios para a UE, preencha os campos de IOSS e IVA em cada envio, conforme descrito em Enviar para a UE.

Quando utilizar este fluxo 

O programa de pagamento diferido (後納) da Japan Post permite ao comerciante liquidar a fatura diária de envios numa única transação no final do dia, em vez de pagar encomenda a encomenda no momento da entrega. O comerciante leva todas as encomendas do dia à estação de correios, juntamente com uma única guia de expedição (差出票) que abrange até 250 envios. Os portes são faturados ao Later Pay Number previamente registado do comerciante.

Se envia etiquetas Japan Post individuais e paga encomenda a encomenda ao balcão, não precisa deste fluxo — chame diretamente a cadeia de envio único, sem consolidação.

Visão geral 

1. shipmentConsolidationCreate            → open the batch (returns consolidation ID)
2. Attach shipments × n                   → create each shipment + label, attached to the batch
3. shipmentConsolidationUpdate(CLOSED)    → close the batch (returns the dispatch slip)

Existem duas formas de associar envios ao lote — utilize a que melhor se adequar à sua integração (ou combine ambas):

• Associar no momento da criação da etiqueta — passe o ID da consolidação do passo 1 em cada chamada a shipmentCreateWorkflow através do campo shipmentConsolidationId.
• Associar envios existentes por ID — passe shipmentIds em shipmentConsolidationCreate (para iniciar o lote com envios) ou em shipmentConsolidationUpdate (para os adicionar a um lote aberto). Cada envio já tem de ter a respetiva etiqueta Japan Post.

Em ambos os casos, cada etiqueta é criada com o seu Later Pay Number incorporado, para que a Japan Post a aceite na guia de expedição quando o passo 3 fechar o lote.

Porquê chamadas separadas em vez de uma única mutation? Os passos 2.1, 2.2, ..., 2.n decorrem ao longo do dia do comerciante — as etiquetas são impressas e as encomendas são fechadas à medida que os pedidos chegam. O lote não pode ser um único pedido de ida e volta, como acontece na cadeia de envio único: há um intervalo de várias horas entre a abertura e o fecho da consolidação.

Pré-requisitos 

Para que este fluxo funcione numa determinada Verified Account:

• A sua conta tem de ter guardado um Later Pay Number de pagamento diferido da Japan Post (後納お客様番号) — um valor formatado com hífenes, como 1111111111-222222-3333333333-444444. Passe-o em shipmentConsolidationCreate através de accountNumber (passo 1).
• A sua chave de API tem de ter o âmbito SHIPMENT_WRITE, além dos âmbitos habituais exigidos pelo fluxo de cada envio.

Endpoint e autenticação 

Os três passos abaixo são operações GraphQL enviadas para o mesmo endpoint. O que passa 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 exemplo para copiar e adaptar que abre uma consolidação — a mutation, as respetivas variáveis e a resposta. Esta é a chamada específica do lote que inicia o fluxo; a associação de envios (passo 2) reutiliza o exemplo de envio único e o fecho do lote (passo 3) devolve o documento de manifesto. Cada campo é detalhado nos passos abaixo.

Passo 1: shipmentConsolidationCreate 

Abre a consolidação. O código da transportadora vincula o lote à Japan Post; todos os envios membros têm de utilizar níveis de serviço da Japan Post. Se já tiver envios com etiqueta prontos, inicie o lote com os respetivos IDs através de shipmentIds — caso contrário, crie-o vazio e associe os envios no passo 2.

Mutation:

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

Resposta:

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

Guarde o id (por exemplo, shco_01HJK...) — vai utilizá-lo em todos os passos seguintes. O status mantém-se OPEN até ao passo 3.

Passo 2: Associar envios 

Para cada encomenda que tem de enviar hoje, execute o fluxo de envio único completo e encadeado para criar o envio e a respetiva etiqueta. Em seguida, associe o envio ao lote através de um dos métodos abaixo.

Opção A: Associar no momento da criação da etiqueta

Passe o ID da consolidação no passo final shipmentCreateWorkflow da cadeia. Todas as mutations anteriores da cadeia são idênticas às do fluxo de envio único.

Os campos relevantes de shipmentCreateWorkflow:

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

Opção B: Associar envios existentes por ID

Se os seus envios já estiverem criados e com etiqueta, adicione-os ao lote aberto com shipmentIds em shipmentConsolidationUpdate:

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

Não inclua status no input enquanto ainda estiver a adicionar envios — o lote mantém-se OPEN. Cada envio tem de utilizar um nível de serviço da Japan Post e ter a respetiva etiqueta (número de seguimento) antes de o lote ser fechado no passo 3.

O que a associação significa para a etiqueta

Seja qual for a opção utilizada, quando um envio Japan Post faz parte de uma consolidação:

• O envio tem um número de seguimento, como habitualmente.
• O PDF da etiqueta de envio não inclui as vias de recibo do cliente/da estação de correios. Esses recibos passam para o passo 3, onde são agrupados no documento da guia de expedição de todo o lote.
• O envio fica associado à consolidação; pode consultá-la novamente através de shipmentConsolidation(id: ...) para ver os respetivos membros.

Repita este passo para cada encomenda do lote do dia. Cada consolidação admite até 250 envios; tentar fechar um lote maior falha com um erro de validação claro antes de ser feita qualquer chamada à Japan Post.

Também pode verificar o conteúdo do lote antes de o fechar:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

Todos os envios devem apresentar aqui um número de seguimento. Se algum não o apresentar, a respetiva etiqueta nunca foi criada — resolva essa situação antes de fechar o lote. O status mantém-se OPEN até a consolidação ser fechada no passo 3.

Passo 3: shipmentConsolidationUpdate(status: CLOSED) 

Fecha o lote. É esta a chamada que pede à Japan Post para gerar a guia de expedição com pagamento diferido que abrange o número de seguimento de cada membro e que associa o PDF resultante à consolidação.

A operação GraphQL chama-se CloseConsolidation para descrever a sua finalidade: fechar o lote. Executa a mutation shipmentConsolidationUpdate com status: CLOSED.

Mutation:

mutation CloseConsolidation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

Num pedido CLOSED:

1. A consolidação é validada: ≤250 envios, e todos os membros têm de ter um número de seguimento. Se faltar o número de seguimento a um envio (a respetiva etiqueta nunca foi criada), a chamada é rejeitada.
2. É pedido à Japan Post que gere uma guia de expedição com pagamento diferido que abrange o número de seguimento de cada membro.
3. O estado passa brevemente para MANIFEST_CREATED enquanto o PDF da guia é obtido e, depois, para CLOSED quando o documento tiver sido associado.
4. O PDF da guia de expedição (um único ficheiro com a guia e todos os recibos do cliente/da estação de correios de cada membro) é associado à consolidação como um CustomsDocument com documentType: MANIFEST_DOCUMENT.

Resposta:

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

Obter os documentos

A guia de expedição é associada diretamente à consolidação como um CustomsDocument com documentType: MANIFEST_DOCUMENT — obtenha o fileUrl a partir da resposta de fecho acima ou consulte-o mais tarde, em qualquer momento:

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

Imprima o PDF disponível em fileUrl. Contém:

• Página 1: A guia de expedição com pagamento diferido (後納差出票) — entregue-a na estação de correios. Todos os envios do lote são listados aqui, independentemente do nível de serviço utilizado.
• Páginas 2+: Os recibos do cliente/da estação de correios — um é agrafado a cada encomenda e o outro fica na estação de correios. Estas páginas são geradas apenas para envios EMS e International Parcel, porque estão associadas a um número de seguimento.

Depois de imprimir, leve as encomendas, a guia de expedição e os recibos à estação de correios numa única deslocação. A Japan Post fatura o seu Later Pay Number no final do período de faturação.

Um envio na página 1 sem página de recibo não é um envio em falta. O Small Packet (小形包装物) não é um serviço da Japan Post com seguimento, pelo que é listado na página 1 e não tem recibo nas páginas 2+. Um lote de cinco encomendas pode legitimamente gerar uma página 1 com as cinco listadas e páginas de recibo apenas para as EMS e Parcel, e um lote composto apenas por Small Packets gera uma página 1 e mais nenhuma página. Este é o comportamento esperado da Japan Post, e não uma etiqueta falhada nem uma chamada de manifesto falhada. Não precisa de abrir uma consolidação separada por nível de serviço. Confirmado com a Japan Post em agosto de 2026.

Juntar tudo 

Um dia típico de um comerciante que envia 50 encomendas Japan Post é o seguinte:

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print PDF

Prefere agrupar no final do dia? Crie as etiquetas do dia sem ID de consolidação e, depois, abra a consolidação uma única vez com todos os valores de shipmentIds (ou adicione-os por partes através de shipmentConsolidationUpdate) e feche-a na mesma chamada ou numa chamada posterior.

Se envia a partir de várias unidades de negócio / contas de faturação, crie uma consolidação separada por conta — passe um accountNumber diferente em cada shipmentConsolidationCreate e encaminhe os envios em conformidade. Envia mais de 250 encomendas por dia? Abra uma segunda consolidação.

Tratamento de erros 

Erros de validação (detetados antes de qualquer chamada à Japan Post)

• accountNumber mal formatado — rejeitado no passo 1 (shipmentConsolidationCreate), antes de a consolidação ser sequer guardada. A mensagem de erro identifica o segmento problemático.
• >250 envios — rejeitado no passo 3, antes de ser feita a chamada à Japan Post.
• Envio membro sem número de seguimento — rejeitado no passo 3. Significa que a criação de uma etiqueta falhou anteriormente sem aviso; investigue o envio afetado através de shipment(id: ...) { trackingDetails }.
• Nenhum número de pagamento diferido definido na consolidação — rejeitado no passo 3. Passe accountNumber em shipmentConsolidationCreate ou guarde um número de conta predefinido na sua conta de transportadora Japan Post.

Erros da API da Japan Post

Se a Japan Post rejeitar o pedido da guia de expedição, a mutation de fecho devolve o código e a mensagem de erro da transportadora como um erro GraphQL. Os mais comuns:

Novas tentativas

Se a chamada de fecho falhar depois de a Japan Post ter aceitado o pedido da guia de expedição (ou seja, durante a obtenção do PDF), é seguro repetir shipmentConsolidationUpdate(status: CLOSED) — a plataforma ignora a chamada à transportadora e volta apenas a tentar obter e associar o documento.

Se o fecho falhar antes de a Japan Post ter aceitado o pedido (erro de validação, E0xx, tempo limite de rede), nenhum estado foi alterado — corrija a causa e tente novamente.