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'un regroupement :

• 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é au groupage ; 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. Le regroupement est validé : ≤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 proche 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'envoi en paiement différé : remettez-le à la Poste.
• Pages 2+ : Les reçus client/poste de chaque colis — l'un agrafé sur chaque colis, l'autre conservé par la poste.

Une fois imprimés, apportez les colis + le bordereau d'expédition + les récépissés 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.

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 proche fait apparaître le code d'erreur et le message du transporteur comme une erreur GraphQL. Les plus courants :

Nouvelles tentatives

Si l'appel rapproché é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.