Expédition par lots (consolidation)

Ce document présente le flux en trois étapes de création d'un lot d'expédition à paiement différé de Japan Post via l'API Zonos GraphQL : ouvrez une consolidation, joignez-y les envois n, puis fermez-la pour recevoir le bordereau d'expédition de Japan Post (document manifeste).

Quand utiliser ce flux 

Le programme de paiement différé (後納) de Japan Post permet à un commerçant de régler sa facture d'expédition quotidienne en une seule transaction à la fin de la journée, plutôt que par colis au dépôt. Le commerçant apporte au bureau de poste tous les colis de la journée accompagnés d'un bon de livraison (差出票) couvrant jusqu'à 250 envois. Les frais de port sont facturés sur le numéro de paiement ultérieur pré-enregistré du commerçant.

Si vous expédiez des étiquettes Japan Post individuelles et payez colis par colis au comptoir, vous n'avez pas besoin de ce flux : appelez la chaîne d'envoi unique directement sans consolidation.

Aperçu 

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)

Il existe deux manières de joindre des expéditions au lot : utilisez celle qui correspond à votre intégration (ou mélangez-les) :

• Joindre au moment de la création de l'étiquette : insérez l'ID de consolidation de l'étape 1 dans chaque appel shipmentCreateWorkflow via le champ shipmentConsolidationId.
• Joindre les expéditions existantes par ID — transmettez shipmentIds sur shipmentConsolidationCreate (pour amorcer le lot) ou sur shipmentConsolidationUpdate (pour ajouter à un lot ouvert). Chaque envoi doit déjà avoir son étiquette Japan Post.

Dans tous les cas, chaque étiquette est créée avec votre numéro de paiement ultérieur intégré afin que Japan Post l'accepte sur le bordereau d'expédition lorsque l'étape 3 clôture le lot.

Pourquoi des appels séparés au lieu d'une mutation ? Les étapes 2.1, 2.2, ..., 2.n se déroulent tout au long de la journée du commerçant : les étiquettes sont imprimées et les colis sont scellés au fur et à mesure que les commandes arrivent. Le lot ne peut pas être un seul aller-retour comme le fait la chaîne d'expédition unique : il y a un intervalle de plusieurs heures entre l'ouverture de la consolidation et sa fermeture.

Prérequis 

Avant que ce flux ne fonctionne pour un compte vérifié donné :

• Votre compte doit avoir un numéro de paiement différé de Japan Post (後納お客様番号) enregistré dessus — une valeur au format trait d'union comme 1111111111-222222-3333333333-444444. Transmettez-le sur shipmentConsolidationCreate via accountNumber (étape 1).
• Votre clé API doit contenir SHIPMENT_WRITE, ainsi que les étendues standard dont le flux de travail par expédition a besoin.

Point de terminaison et authentification 

Les trois étapes ci-dessous sont des opérations GraphQL envoyées au même point de terminaison. Ce que vous transmettez dans les en-têtes dépend de votre configuration : choisissez votre onglet.

URL :

https://api.zonos.com/graphql

En-têtes :

credentialToken: {{YOUR_API_TOKEN}}

Exemple de requête 

Un exemple de copie et d'adaptation d'ouverture d'une consolidation : la mutation, ses variables et la réponse. Il s'agit de l'appel spécifique au lot qui démarre le flux ; la pièce jointe des expéditions (étape 2) réutilise l'exemple d'expédition unique et la fermeture du lot (étape 3) renvoie le document manifeste. Chaque champ est décomposé selon les étapes ci-dessous.

Étape 1 : shipmentConsolidationCreate 

Ouvre la consolidation. Le code du transporteur verrouille le lot sur Japan Post ; tous les envois des membres doivent utiliser les niveaux de service de Japan Post. Si vous avez déjà des envois étiquetés prêts, amorcez le lot avec leurs identifiants via shipmentIds — sinon créez-le vide et joignez les envois à l'étape 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
    }
  }
}

Réponse :

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

Conservez le id (e.g. shco_01HJK...) — vous l'utiliserez pour tout ce qui suit. Le status est OPEN jusqu'à l'étape 3.

Étape 2 : Joindre les envois 

Pour chaque colis que vous devez expédier aujourd'hui, exécutez le workflow d'envoi unique en chaîne complet pour créer l'envoi et son étiquette. Joignez ensuite l'envoi au lot en utilisant l'une des méthodes ci-dessous.

Option A : Joindre au moment de la création de l'étiquette

Transmettez l'ID de consolidation à la dernière étape shipmentCreateWorkflow de la chaîne. Toutes les mutations précédentes dans la chaîne sont identiques au flux de travail à expédition unique.

Les champs pertinents sur shipmentCreateWorkflow :

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

Option B : Joindre les envois existants par ID

Si vos envois sont déjà créés et étiquetés, ajoutez-les au lot ouvert avec shipmentIds sur shipmentConsolidationUpdate :

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

Laissez status hors de l'entrée pendant que vous ajoutez des expéditions : le lot reste OPEN. Chaque envoi doit utiliser un niveau de service Japan Post et avoir son étiquette (numéro de suivi) avant la fermeture du lot à l'étape 3.

Ce que signifie la pièce jointe pour l'étiquette

Quelle que soit l'option que vous utilisez, lorsqu'un envoi Japan Post fait partie d'une consolidation :

• L'envoi dispose d'un numéro de suivi, comme d'habitude.
• Le PDF de l'étiquette d'expédition n'inclut pas les copies des reçus client/bureau de poste. Ces reçus sont reportés à l'étape 3, où ils sont regroupés dans le document de bordereau d'expédition pour l'ensemble du lot.
• L'envoi est associé à la consolidation ; vous pouvez l'interroger à nouveau via shipmentConsolidation(id: ...) pour voir ses membres.

Répétez cette étape pour chaque colis du lot du jour. Jusqu'à 250 expéditions par consolidation ; la tentative de clôture d'un lot plus important échoue avec une erreur de validation claire avant tout appel de Japan Post.

Vous pouvez également vérifier le contenu du lot avant de le fermer :

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

Chaque envoi doit afficher ici un numéro de suivi. Si ce n'est pas le cas, son étiquette n'a jamais été créée — réglez cela avant de fermer. status est OPEN jusqu'à ce que la consolidation soit clôturée à l'étape 3.

Étape 3 : shipmentConsolidationUpdate(status: CLOSED) 

Ferme le lot. Il s'agit de l'appel qui demande à Japan Post de générer le bordereau d'envoi à paiement différé couvrant le numéro de suivi de chaque membre, et de joindre le PDF résultant à la consolidation.

L'opération GraphQL est nommée CloseConsolidation pour décrire son intention, fermant le lot. Il exécute la mutation shipmentConsolidationUpdate avec status: CLOSED.

Mutation :

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

Sur une requête CLOSED :

1. La consolidation est validée : ≤250 envois, et chaque membre doit disposer d'un numéro de suivi. Si un envoi n'a pas son numéro de suivi (son étiquette n'a jamais été créée), l'appel est rejeté.
2. Japan Post est invité à générer un bordereau d'expédition à paiement différé indiquant le numéro de suivi de chaque membre.
3. Le statut passe brièvement à MANIFEST_CREATED pendant la récupération du bordereau PDF, puis à CLOSED une fois le document joint.
4. Le PDF du bordereau d'expédition (un fichier contenant le bordereau ainsi que les reçus client/bureau de poste de chaque membre) est joint à la consolidation sous la forme CustomsDocument avec documentType: MANIFEST_DOCUMENT.

Réponse :

{
  "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"
        }
      ]
    }
  }
}

Récupération des documents

Le bordereau d'expédition est joint directement à la consolidation sous la forme d'un CustomsDocument avec documentType: MANIFEST_DOCUMENT — récupérez le fileUrl dans la réponse de clôture ci-dessus ou recherchez-le à tout moment plus tard :

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

Imprimez le PDF à fileUrl. Il contient :

• Page 1 : Le bordereau d'expédition à paiement différé (後納差出票) — remettez-le au bureau de poste. Chaque envoi du lot y est répertorié, quel que soit le niveau de service utilisé.
• Pages 2 et suivantes : Les reçus client/bureau de poste — l'un agrafé à chaque colis, l'autre conservé par le bureau de poste. Ces pages ne sont générées que pour les envois EMS et Colis international, car elles sont associées à un numéro de suivi.

Une fois imprimés, apportez les colis, le bordereau d'expédition et les reçus au bureau de poste en un seul déplacement. Japan Post facture votre numéro de paiement ultérieur à la fin de la période de facturation.

Un envoi figurant en page 1 sans page de reçu n'est pas un envoi manquant. Le Petit Paquet (小形包装物) n'est pas un service Japan Post suivi ; il est donc répertorié en page 1 sans recevoir de page de reçu en pages 2 et suivantes. Un lot de cinq colis peut légitimement produire une page 1 les répertoriant tous les cinq, avec des pages de reçu uniquement pour les envois EMS et Colis, tandis qu'un lot composé uniquement de Petits Paquets produit une page 1 sans aucune page supplémentaire. Il s'agit d'un comportement normal de Japan Post, et non d'une étiquette ou d'un appel de manifeste ayant échoué. Vous n'avez pas besoin d'ouvrir une consolidation distincte par niveau de service. Confirmé auprès de Japan Post, août 2026.

L'assembler 

Un jour représentatif pour un commerçant expédiant 50 colis Japan Post ressemble à :

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

Vous préférez plutôt effectuer un lot en fin de journée ? Créez les étiquettes du jour sans ID de consolidation, puis ouvrez la consolidation une fois avec chaque valeur shipmentIds (ou ajoutez-les en morceaux via shipmentConsolidationUpdate) et fermez-la dans le même appel ou lors d'un appel de suivi.

Si vous expédiez sur plusieurs unités commerciales/comptes de facturation, effectuez une consolidation distincte par compte : transmettez un accountNumber différent sur chaque shipmentConsolidationCreate et acheminez les expéditions en conséquence. Expédier plus de 250 colis par jour ? Ouvrez une deuxième consolidation.

Gestion des erreurs 

Erreurs de validation (détectées avant tout appel de Japan Post)

• accountNumber mal formé — rejeté à l'étape 1 (shipmentConsolidationCreate) avant même que la consolidation ne soit enregistrée. Le message d'erreur identifie le segment incriminé.
• >250 envois — rejetés à l'étape 3, avant l'appel de Japan Post.
• Envoi membre sans numéro de suivi — rejeté à l'étape 3. Cela signifie qu'une création d'étiquette a échoué silencieusement plus tôt ; enquêtez sur l'envoi concerné via shipment(id: ...) { trackingDetails }.
• Aucun numéro de paiement différé défini sur la consolidation — rejeté à l'étape 3. Transmettez accountNumber sur shipmentConsolidationCreate ou enregistrez un numéro de compte par défaut sur votre compte de transporteur Japan Post.

Erreurs de l'API Japan Post

Si Japan Post rejette la demande de bordereau d'expédition, la mutation de clôture fait apparaître le code d'erreur et le message du transporteur comme une erreur GraphQL. Les plus courants :

Nouvelles tentatives

Si l'appel de clôture échoue après que Japan Post a accepté la demande de bordereau d'expédition (i.e. lors de la récupération du PDF), réessayer shipmentConsolidationUpdate(status: CLOSED) est sûr : la plate-forme ignorera l'appel du transporteur et tentera à nouveau de récupérer et de joindre le document.

Si la fermeture échoue avant que Japan Post n'ait accepté la demande (erreur de validation, E0xx, délai d'expiration du réseau), aucun état n'a changé : corrigez la cause première et réessayez.