Despacho em lote (consolidação)

Este documento descreve o fluxo em três etapas para criar um lote de despacho de pagamento diferido Japan Post via Zonos GraphQL API: abrir uma consolidação, anexar n envios a ela e fechá-la para receber o dispatch slip (documento de manifest) do Japan Post.

Quando usar este fluxo 

O programa de pagamento diferido (後納) do Japan Post permite que o comerciante liquide a fatura diária de envio em uma transação no fim do dia, em vez de pagar pacote a pacote no balcão. O comerciante leva todos os pacotes do dia aos correios junto com um dispatch slip (差出票) cobrindo até 250 envios. O frete é faturado ao Later Pay Number pré-registrado do comerciante.

Se você envia etiquetas Japan Post individuais e paga pacote a pacote no balcão, não precisa deste fluxo — chame a cadeia de envio único diretamente, 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)

Há duas formas de anexar envios ao lote — use a que se adaptar à sua integração (ou combine ambas):

• Anexar no momento da criação da etiqueta — passe o ID de consolidação da etapa 1 em cada chamada shipmentCreateWorkflow via o campo shipmentConsolidationId.
• Anexar envios existentes por ID — passe shipmentIds em shipmentConsolidationCreate (para iniciar o lote) ou em shipmentConsolidationUpdate (para adicionar a um lote aberto). Cada envio já deve ter sua etiqueta Japan Post.

De qualquer forma, cada etiqueta é criada com seu Later Pay Number incorporado para que o Japan Post a aceite no dispatch slip quando a etapa 3 fechar o lote.

Por que chamadas separadas em vez de uma mutation? As etapas 2.1, 2.2, ..., 2.n ocorrem ao longo do dia do comerciante — etiquetas são impressas e pacotes selados conforme os pedidos chegam. O lote não pode ser uma única ida e volta como a cadeia de envio único: há um intervalo de várias horas entre abrir a consolidação e fechá-la.

Pré-requisitos 

Antes que este fluxo funcione para uma Verified Account:

• Sua conta deve ter um Japan Post Later Pay Number de pagamento diferido (後納お客様番号) salvo — um valor com hífens como 1111111111-222222-3333333333-444444. Passe-o em shipmentConsolidationCreate via accountNumber (Etapa 1).
• Sua API key deve ter SHIPMENT_WRITE, além dos escopos padrão exigidos pelo fluxo por envio.

Endpoint e autenticação 

As três etapas abaixo são operações GraphQL enviadas ao 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 

Um exemplo para copiar e adaptar ao abrir uma consolidação — a mutation, variáveis e resposta. Esta é a chamada específica do lote que inicia o fluxo; anexar envios (Etapa 2) reutiliza o exemplo de envio único, e fechar o lote (Etapa 3) retorna o documento de manifest. Cada campo é detalhado nas etapas abaixo.

Etapa 1: shipmentConsolidationCreate 

Abre a consolidação. O carrier code fixa o lote ao Japan Post; todos os envios membros devem usar níveis de serviço Japan Post. Se já tiver envios etiquetados prontos, inicie o lote com os IDs via shipmentIds — caso contrário, crie vazio e anexe envios na etapa 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 (ex.: shco_01HJK...) — você o usará em tudo abaixo. O status é OPEN até a etapa 3.

Etapa 2: Anexar envios 

Para cada pacote que precisa enviar hoje, execute o fluxo encadeado completo de envio único para criar o envio e sua etiqueta. Depois anexe o envio ao lote usando um dos métodos abaixo.

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

Passe o ID de consolidação na etapa final shipmentCreateWorkflow da cadeia. Todas as mutations anteriores são idênticas ao fluxo de envio único.

Os campos relevantes em shipmentCreateWorkflow:

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

Opção B: Anexar envios existentes por ID

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

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

Deixe status fora do input enquanto ainda adiciona envios — o lote permanece OPEN. Cada envio deve usar nível de serviço Japan Post e ter etiqueta (número de rastreamento) antes de fechar o lote na Etapa 3.

O que a anexação significa para a etiqueta

Qualquer opção que use, quando um envio Japan Post faz parte de uma consolidação:

• O envio tem número de rastreamento, como de costume.
• O PDF da etiqueta não inclui as vias de recibo do cliente/correios. Esses recibos ficam para a Etapa 3, onde são agrupados no documento de dispatch slip de todo o lote.
• O envio fica associado à consolidação; você pode consultá-lo via shipmentConsolidation(id: ...) para ver os membros.

Repita esta etapa para cada pacote do lote do dia. Até 250 envios por consolidação; tentar fechar um lote maior falha com erro de validação claro antes de qualquer chamada ao Japan Post.

Você também pode verificar o conteúdo do lote antes de fechar:

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

Todo envio deve mostrar um número de rastreamento aqui. Se algum não mostrar, a etiqueta nunca foi criada — resolva isso antes de fechar. status é OPEN até a consolidação ser fechada na Etapa 3.

Etapa 3: shipmentConsolidationUpdate(status: CLOSED) 

Fecha o lote. Esta chamada solicita ao Japan Post gerar o dispatch slip de pagamento diferido cobrindo o número de rastreamento de cada membro e anexa o PDF resultante à consolidação.

A operação GraphQL se chama CloseConsolidation para descrever sua intenção de fechar o lote. Ela 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
    }
  }
}

Em uma requisição CLOSED:

1. A consolidação é validada: ≤250 envios, e todo membro deve ter número de rastreamento. Se um envio não tiver rastreamento (etiqueta nunca criada), a chamada é rejeitada.
2. O Japan Post é solicitado a gerar um dispatch slip de pagamento diferido cobrindo o rastreamento de cada membro.
3. O status passa brevemente para MANIFEST_CREATED enquanto o PDF do slip é obtido, depois para CLOSED quando o documento é anexado.
4. O PDF do dispatch slip (um arquivo com o slip e os recibos de cliente/correios de cada membro) é anexado à consolidação como 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"
        }
      ]
    }
  }
}

Recuperando os documentos

O dispatch slip é anexado diretamente à consolidação como CustomsDocument com documentType: MANIFEST_DOCUMENT — obtenha o fileUrl da resposta de fechamento acima ou consulte depois:

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

Imprima o PDF em fileUrl. Ele contém:

• Página 1: O dispatch slip de pagamento diferido — entregue aos correios.
• Páginas 2+: Recibos de cliente/correios de cada pacote — um grampeado em cada pacote, o outro retido pelos correios.

Depois de imprimir, leve pacotes + dispatch slip + recibos aos correios em uma única visita. O Japan Post fatura seu Later Pay Number no fim do período de cobrança.

Juntando tudo 

Um dia representativo para um comerciante enviando 50 pacotes Japan Post:

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 fim do dia? Crie as etiquetas do dia sem ID de consolidação, abra a consolidação uma vez com todos os shipmentIds (ou adicione em partes via shipmentConsolidationUpdate) e feche na mesma chamada ou em uma posterior.

Se envia por várias unidades de negócio / contas de faturamento, execute uma consolidação separada por conta — passe accountNumber diferente em cada shipmentConsolidationCreate e roteie envios de acordo. Mais de 250 pacotes por dia? Abra uma segunda consolidação.

Tratamento de erros 

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

• accountNumber malformado — rejeitado na Etapa 1 (shipmentConsolidationCreate) antes de salvar a consolidação. A mensagem identifica o segmento problemático.
• >250 envios — rejeitado na Etapa 3, antes da chamada ao Japan Post.
• Envio membro sem número de rastreamento — rejeitado na Etapa 3. Indica falha silenciosa na criação da etiqueta; investigue via shipment(id: ...) { trackingDetails }.
• Nenhum número de pagamento diferido na consolidação — rejeitado na Etapa 3. Passe accountNumber em shipmentConsolidationCreate ou salve um número padrão na conta Japan Post.

Erros da Japan Post API

Se o Japan Post rejeitar a solicitação de dispatch slip, a mutation de fechamento expõe o código e mensagem do carrier como erro GraphQL. Os mais comuns:

Tentativas novamente

Se a chamada de fechamento falhar depois que o Japan Post aceitar o dispatch slip (ou seja, durante a obtenção do PDF), repetir shipmentConsolidationUpdate(status: CLOSED) é seguro — a plataforma pula a chamada ao carrier e tenta novamente obter e anexar o documento.

Se o fechamento falhar antes da aceitação pelo Japan Post (erro de validação, E0xx, timeout de rede), nenhum estado mudou — corrija a causa e tente novamente.