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 coût au débarquement nécessite les objets + les parties ; le label 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 coût au débarquement.

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 coût au débarquement 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 :

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 en ligne, vous n'avez donc pas besoin d'un deuxième aller-retour pour la récupérer. L'exemple ci-dessus demande url.

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.

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.