Créer un seul envoi

CreateDeclarationShipment enchaîne six mutations *Workflow en une seule requête GraphQL. Chaque étape s'appuie sur les données fournies par les étapes précédentes, et toutes sont soumises ensemble afin qu'un envoi complet puisse être créé en un seul aller-retour :

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

Les mutations Workflow sont conçues pour être chaînées : vous n'avez pas besoin de transmettre les identifiants d'une étape à l'autre, et vous n'avez pas besoin d'envoyer une requête distincte par étape. Soumettez l'intégralité du document, récupérez le Shipment final.

Lorsque le serviceLevel de la dernière étape est un niveau de service Japan Post (japan_post.*), Zonos appelle l'API Japan Post Label (code 52) en votre nom à l'aide des numéros de paiement ultérieurs de votre compte vérifié, génère l'étiquette et le numéro de suivi, crée l'ID de déclaration et les relie, le tout dans cette dernière étape shipmentCreateWorkflow.

Pourquoi une mutation ? Chaque étape dépend de la précédente (le landed cost nécessite les articles + les parties ; l'étiquette a besoin de tout). Les regrouper dans un seul document GraphQL maintient les données cohérentes et évite cinq allers-retours supplémentaires.

Point de terminaison et authentification 

Les requêtes de cette chaîne utilisent toutes le 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 

Une requête CreateDeclarationShipment complète que vous pouvez copier et adapter (la mutation, ses variables et la réponse) pour un seul colis Japan Post expédié en DDP aux États-Unis. Chaque entrée est détaillée dans la section étape par étape ci-dessous.

Étape par étape 

La colonne Status de chaque tableau ci-dessous utilise ces termes :

• Obligatoire — la requête échoue sans cela.
• Obligatoire pour l'étiquette — facultatif dans le schéma GraphQL, mais nécessaire pour produire une étiquette Japan Post U.S. valide.
• Conditionnel — obligatoire en fonction d'un autre champ (noté en ligne).
• Recommandé — facultatif, mais génère des droits et taxes précis.
• Facultatif — pas nécessaire.

1. partyCreateWorkflow

Crée les parties impliquées dans l'envoi : au minimum un ORIGIN (d'où l'envoi est expédié) et un DESTINATION (l'acheteur/le destinataire).

Exemple de charge utile :

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

La réponse renvoie les ID Party créés et les champs d'adresse résolus.

2. itemCreateWorkflow

Crée les articles qui composent l'envoi. Ce sont les SKU qui apparaîtront sur la facture commerciale et qui déterminent le calcul du landed cost.

Le code SH, le pays d'origine et le montant sont les trois champs qui influencent le plus le résultat des droits/taxes à l'étape 5.

3. cartonsCreateWorkflow

Crée les colis physiques — les boîtes, sacs en polyéthylène ou lettres qui contiendront les articles.

Chaque carton devient un colis sur l'étiquette du transporteur à l'étape 6. Plusieurs cartons → envoi multi-pièces avec un numéro de suivi par carton.

4. shipmentRatingCreateWorkflow

Enregistre le devis tarifaire que le commerçant facture à l'acheteur pour l'expédition.

Il s'agit du tarif proposé à l'acheteur au paiement. Il alimente le calcul du landed cost comme sous-total « shipping » afin que les droits et taxes soient calculés sur la valeur CAF correcte.

5. landedCostCalculateWorkflow

Exécute le calcul des droits, taxes et frais pour le pays de destination. Utilise les articles, les parties et les frais d'expédition des étapes précédentes.

La réponse inclut amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — ce sont les montants affichés à l'acheteur au paiement et imprimés sur la facture commerciale.

6. shipmentCreateWorkflow

L'étape terminale — crée l'entité Shipment, génère l'étiquette du transporteur et (facultativement) la facture commerciale / le bordereau d'emballage.

Pour les comptes vérifiés Japan Post, c'est aussi là que Zonos appelle l'API Japan Post Label (code 52) en votre nom, injecte vos numéros de paiement ultérieur, crée l'ID de déclaration et le lie au numéro de suivi renvoyé par Japan Post.

Champs clés :

Concernant contentsType, les deux valeurs les plus courantes pour le trafic des comptes vérifiés sont ECOMMERCE_GOODS (vendu à un consommateur, BtoC) et COMMERCIAL_GOODS (vendu entre entreprises, BtoB). Ces valeurs déterminent le pkgType que Zonos envoie lors de l'appel à l'étiquette Japan Post ; ce choix modifie donc ce qui est imprimé sur la déclaration douanière — ce n'est pas qu'une simple étiquette.

Sous-entrée nonDelivery

Indique à Japan Post quoi faire du colis s'il ne peut pas être livré — refusé par le destinataire, rejeté à la frontière, ou impossible à livrer à l'adresse indiquée.

option accepte exactement ces quatre valeurs. Il n'existe pas de valeur RETURN — utilisez RETURN_AFTER_RETENTION ou RETURN_IMMEDIATELY pour choisir quand le colis revient.

L'API expose les deux variantes de retour séparément ; l'option Retour du Dashboard couvre les deux.

transportMethod accepte AIR ou MOST_ECONOMICAL, et définit la façon dont un colis retourné revient. Cela s'applique uniquement aux deux options RETURN_* — le Dashboard n'affiche le champ Méthode de retour correspondant que lorsque Retour est sélectionné.

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

Le sélecteur Si non livrable dans la boîte de dialogue Créer une étiquette du Dashboard écrit ce même champ, de sorte qu'une étiquette créée dans le Dashboard et une étiquette créée via l'API se comportent de manière identique.

Sous-entrée references

Ces champs s'impriment sur l'étiquette du transporteur et/ou la facture commerciale. Utilisez-les pour faire apparaître les numéros de bon de commande, de licence et les remarques en texte libre dont le destinataire ou l'autorité douanière a besoin.

Réponse

Les champs utiles sur le Shipment renvoyé sont :

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number est le numéro de suivi de Japan Post.

L'objet label peut renvoyer l'étiquette de deux manières — demandez celle qui correspond à votre flux de travail (ou les deux) :

Sélectionnez uniquement les champs dont vous avez besoin. Demander url maintient la réponse petite ; demander labelImage renvoie l'étiquette complète directement dans la réponse, vous n'avez donc pas besoin d'un deuxième aller-retour pour la récupérer. L'exemple ci-dessus demande url.

Japan Post service levels 

Transmettez l'un de ces codes comme serviceLevelCode dans shipmentRatingCreateWorkflow.

Les codes de niveau de service utilisent des points, pas des underscores. Vous pouvez voir la forme avec underscore (japan_post_air_parcel) dans les messages d'erreur et les références internes, mais elle n'est pas une entrée valide.

Services aériens

Services de surface

Choisir entre des services similaires

Petit colis et International Air Packet. Les deux sont plafonnés à 2 kg. japan_post.air.packet est le service de petit colis suivi de Japan Post. japan_post.air.small_packet en est l'équivalent non suivi. Si vous avez besoin d'un suivi pour un colis léger, utilisez japan_post.air.packet.

Variantes recommandées. Pour les lettres et les imprimés, le suivi est ajouté par la version recommandée (書留) du service. japan_post.air.printed_matter et japan_post.air.letter ne l'incluent pas par eux-mêmes.

Codes obsolètes

japan_post.air.epacket_light correspondait à International e-Packet Light. Japan Post a renommé ce service International Air Packet le 1er juin 2026 et l'a étendu à tous les pays et régions. Le service lui-même reste inchangé.

L'ancien code reste résolu afin que les intégrations existantes continuent de fonctionner, mais utilisez japan_post.air.packet pour tout nouveau développement.

Codes de mode de transport

japan_post.air, japan_post.surface, japan_post.economy_air et japan_post.custom sont également résolus, mais ils identifient un mode de transport ou une solution de repli plutôt qu'un produit postal spécifique. Utilisez l'un des codes de service ci-dessus pour les envois normaux.

Validez le code que vous envoyez

Un serviceLevelCode non reconnu ne génère pas d'erreur. La requête renvoie un code HTTP 200 sans tableau errors, serviceLevel revient à null, et les frais d'expédition disparaissent du total du landed cost — la réponse paraît donc correcte alors que les montants sont faux.

Vérifiez toujours que shipmentRatingCreateWorkflow.serviceLevel n'est pas nul avant de vous fier aux totaux.

Pour récupérer la liste actuelle à tout moment :

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Cette requête prend l'ID du transporteur. Transmettre le code transporteur japan_post renvoie une liste vide sans erreur.

Gestion des erreurs 

• Les erreurs de validation (champs obligatoires manquants, codes de pays invalides, etc.) reviennent dans le tableau GraphQL errors standard et abandonnent le reste de la chaîne.
• Les erreurs Japan Post (échec de génération d'étiquette, adresse invalide, etc.) apparaissent sous forme d'erreurs GraphQL sur shipmentCreateWorkflow. Si une nouvelle tentative est nécessaire, contactez le support — le chemin recommandé consiste à soumettre à nouveau la mutation complète avec la saisie corrigée.

VALIDATION_INVALID_TYPE_VARIABLE

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

Cette erreur nomme la variable entière, et non le champ réellement fautif. Elle signifie presque toujours qu'une valeur d'énumération à l'intérieur de cette variable n'appartient pas à son énumération — le plus souvent nonDelivery.option, contentsType, ou serviceLevel.

Ce n'est pas un problème de typage JSON. Mettre ou retirer des guillemets autour de vos booléens et nombres ne changera rien, car la charge utile n'est jamais analysée jusque-là — l'énumération est rejetée en premier.

Pour trouver le champ fautif, vérifiez chaque champ à valeur d'énumération dans la variable par rapport à ses valeurs acceptées :

L'ensemble des valeurs d'énumération pour toute entrée est répertorié sur sa page de type dans la référence de l'API.

Autorisations 

Chaque étape est sécurisée indépendamment. Votre clé API doit contenir la portée d'écriture pour chaque entité de la chaîne (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Le rôle de commerçant standard sur un compte vérifié accorde tout cela.

Étapes suivantes 

• Envoi par lots (consolidation) — regroupez les colis de la journée dans un seul bordereau d'expédition à paiement différé Japan Post.