DOCS

Informez Zonos de vos envois postaux

Envoyez les données des colis et du moyen de transport pour les envois à destination des États-Unis et de l’Union européenne.

Deux appels, identiques pour toutes les destinations.

Appel↕Envoie↕Quand↕
brokerageManifestLinesCreateColis : marchandises, parties, références. 100 maximum par requêteÀ l’acceptation du colis
brokerageManifestCreateLe moyen de transport, en citant les identifiants de colis de l’appel 1À la remise au transporteur

Aucun des deux appels ne bloque l’autre. Utilisez manifestLinesLink pour les colis acceptés après la création du moyen de transport.

Conservez l’id renvoyé par l’appel 1; il est requis pour l’appel 2.

Le landed cost est calculé de manière asynchrone. Une réponse de succès confirme l’acceptation, pas l’établissement de la soumission. Les données des articles et des parties sont validées pendant le calcul : envoyez donc les champs ci-dessous même lorsque l’API accepte leur absence.

Certaines destinations ajoutent un supplément PDDP. Consultez Suppléments PDDP par destination.

Les destinations hors États-Unis disposent d’une alternative en un seul appel.

Légende des champs 

Libellé↕Signification↕
ObligatoireL’API rejette la requête sans ce champ.
Obligatoire pour l’UEDoit être envoyé pour chaque colis à destination de l’UE. L’API peut accepter un colis sans ce champ, mais la soumission peut être erronée ou échouer, et l’envoi n’est pas conforme.
Obligatoire pour les É.-U.Doit être envoyé pour chaque colis à destination des États-Unis. Une déclaration en douane ne peut pas être déposée sans ce champ.
RecommandéNon nécessaire pour établir la soumission, mais utilisé par les postes et les douanes de destination. Envoyez-le chaque fois que vous en disposez.
FacultatifEnvoyez-le lorsqu’il s’applique.

Étape 1 : Informez-nous des colis 

Champs du colis

Champ↕Exigence↕Remarques↕
trackingNumberObligatoireNuméro de suivi de l’envoi.
currencyCodeObligatoireDevise de toutes les valeurs d’articles du colis.
endUseObligatoireDOCUMENTS, GIFT, FOR_RESALE, NOT_FOR_RESALE ou RETURN.
itemsObligatoireAu moins un article. Consultez les champs d’article.
partiesObligatoireUne partie ORIGIN et une partie DESTINATION. Consultez les champs de partie.
shippingCostObligatoire pour l’UEFrais d’expédition du colis. Les droits et la TVA de l’UE sont calculés sur la valeur CAF : un coût d’expédition manquant est donc traité comme nul.
shippingCostCurrencyObligatoire pour l’UEDevise de shippingCost. Vaut USD par défaut s’il est omis.
taxIdNumberFacultatifLe numéro IOSS, lorsque la vente a été effectuée sous le régime IOSS. Consultez IOSS.
consignmentWeightRecommandéPoids brut du colis en kilogrammes. Envoyez la même valeur sur chaque ligne partageant un numéro de suivi. Non utilisé pour calculer les droits.
referenceNumberRecommandéVotre référence unique pour le colis, utilisée pour éviter les doublons. Consultez Colis en double.
shipperAccountIdRecommandéL’ID d’organisation Zonos ou votre ID externe pour le compte vérifié de l’expéditeur. Sans lui, le colis vous est attribué plutôt qu’au commerçant qui en est à l’origine.
postalOperatorCodeFacultatifRemplace la valeur par défaut définie au niveau de la requête sur le chemin court. Ignoré ailleurs.
declarationIdFacultatifUne déclaration Zonos déjà créée pour ce colis. Normalement résolue à partir de la commande.

Champs d’article

Une entrée par ligne de marchandises. Un colis contenant trois classifications est un seul colis avec trois entrées.

Champ↕Exigence↕Remarques↕
quantityObligatoireNombre d’unités.
countryOfOriginObligatoireCode pays ISO à 2 lettres. Le pays de fabrication, et non celui de dépôt.
amountObligatoireValeur unitaire. Envoyez exactement l’un des champs amount ou totalAmount.
totalAmountObligatoireValeur totale pour toutes les unités. Lorsqu’il est envoyé à la place de amount, la valeur unitaire est totalAmount / quantity.
descriptionObligatoireDescription simple des marchandises.
measurementsObligatoireIncluez une entrée de poids net (WEIGHT par unité, ou TOTAL_WEIGHT pour toutes les unités, pas les deux). Voir ci-dessous.
hsCodeObligatoire pour les É.-U.Code SH ou code tarifaire, par ligne de marchandises. 10 chiffres de préférence, 6 au minimum.
customsDescriptionFacultatifDescription propre à la douane, lorsqu’elle diffère de description.
provinceOfOriginFacultatifProvince ou État d’origine, lorsqu’un pays l’exige.
skuRecommandéVotre SKU. Consultez les identifiants de produit.
productIdRecommandéVotre identifiant de produit.
gtinRecommandéGlobal Trade Item Number, chiffres uniquement.
upcFacultatifUtilisé comme gtin lorsqu’aucun gtin n’est envoyé.
nameFacultatifNom court du produit.
documentIdFacultatifAssocie un document que vous avez déjà téléversé.
productCompositionFacultatifMatériaux qui composent le produit. Chaque entrée nécessite material et percentage.
marketplaceFacultatifPlace de marché sur laquelle l’article a été vendu, sous forme de name et url.

Le code SH et le pays d’origine sont indiqués par ligne de marchandises. Un colis contenant des marchandises de classifications différentes nécessite un code et une origine pour chacune. Un code unique pour un colis mixte ne peut pas être déclaré aux États-Unis.

Mesures. Chaque entrée nécessite un type, une unitOfMeasure et une value. Le poids est net et couvre toutes les unités de la ligne : ne le multipliez donc pas par la quantité. C’est sur ce poids que les droits sont calculés.

  • type : WEIGHT, TOTAL_WEIGHT, VOLUME, LENGTH, WIDTH, HEIGHT ou ALCOHOL_BY_VOLUME
  • unitOfMeasure : GRAM, KILOGRAM, OUNCE, POUND, LITER, MILLILITER, CENTIMETER, METER, MILLIMETER, INCH, FOOT, YARD ou PERCENTAGE

Composition du produit. Chaque entrée accepte material et percentage, ainsi que les champs facultatifs countryOfMeltAndPour, countryOfCast, primaryCountryOfSmelt et secondaryCountryOfSmelt.

Champs de partie

Chaque partie a un type (ORIGIN pour l’expéditeur, DESTINATION pour le destinataire), une person et une location.

Champ↕Origine (expéditeur)↕Destination (destinataire)↕
location.countryCodeObligatoireObligatoire
location.line1ObligatoireObligatoire
location.locality (ville)ObligatoireObligatoire
location.postalCodeRecommandéObligatoire (sauf en Irlande)
location.administrativeAreaCodeFacultatifObligatoire pour les É.-U. et le Canada
person.firstNameObligatoireObligatoire
person.lastNameObligatoireObligatoire
person.emailObligatoire pour l’UEObligatoire pour l’UE
person.companyNameFacultatifFacultatif
person.phoneFacultatifFacultatif

Les deux parties figurent sur la déclaration en douane. Des parties incomplètes sont la cause la plus fréquente d’échec du dédouanement.

Les codes postaux d’origine sont recommandés, et non obligatoires : Hong Kong, les Émirats arabes unis et le Qatar n’en ont pas. Les codes postaux des destinataires dans l’UE sont obligatoires, sauf en Irlande.

administrativeAreaCode accepte le code à deux lettres : TX, et non TEXAS.

Exemple

1mutation BrokerageManifestLinesCreate($input: [ManifestLineInput!]!) {
2 brokerageManifestLinesCreate(input: $input) {
3 id
4 trackingNumber
5 referenceNumber
6 taxIdNumber
7 }
8}

RÉPONSE

json

{
  "data": {
    "brokerageManifestLinesCreate": [
      {
        "id": "line_abc123def456",
        "trackingNumber": "RB123456799GB",
        "referenceNumber": "ITM-00184413",
        "taxIdNumber": "IM5281234567"
      }
    ]
  }
}

Identifiants de produit 

Quatre champs sur chaque ligne de marchandises.

À envoyer sur l’article↕Ce que c’est↕
productIdVotre propre identifiant de produit
skuVotre unité de gestion des stocks
gtinLe GTIN canonique
manufacturerProductIdLa référence pièce du fabricant

Ce que l’Europe en fait

Le PDDP de l’UE comporte sept champs d’identifiant de produit. Trois sont alimentés directement par ce que vous envoyez sur l’article : plus vous en envoyez ici, plus la déclaration est complète.

Champ PDDP↕Alimenté par↕Limite↕
merchantProductIdentifier (MPID)productId, à défaut sku50
manufacturerStandardizedProductIdentifier (S PID)gtinchiffres uniquement
manufacturerNonStandardizedProductIdentifier (NS PID)manufacturerProductId70

lccProviderProductIdentifier est défini à partir de notre identifiant d’article. manufacturerIdentifier n’est pas envoyé.

Contraintes :

  • gtin ne contient que des chiffres. 05012345678900, et non 0-50123-45678-9.
  • Envoyez gtin ou upc, pas les deux. Un UPC est un GTIN-12; upc est normalisé en gtin.
  • manufacturerProductId accepte 70 caractères. Tous les autres champs d’identifiant sont tronqués à 50.
  • Omettez les champs dont vous ne disposez pas. Les chaînes vides sont rejetées. Les sept champs ont une longueur minimale d’un caractère.

Étape 2 : Informez-nous du moyen de transport 

Envoyé à la remise au transporteur, en citant les identifiants de colis de l’étape 1.

Champ↕Exigence↕Remarques↕
postalOperatorCodeObligatoireVotre code d’opérateur enregistré.
carrierCodeObligatoireCode IATA à 2 lettres (aérien) ou SCAC (routier, maritime).
serviceNumberObligatoireNuméro de vol, de voyage ou de trajet.
arrivalDateObligatoireDate et heure d’arrivée au format ISO 8601.
destinationCodeObligatoireLieu d’arrivée du moyen de transport. Code d’aéroport ou de port.
transportationModeRecommandéAIR, SEA, ROAD ou RAIL. Vaut AIR par défaut.
vesselNameObligatoire pour le maritimeLe navire. La douane identifie un navire à l’arrivée par son nom, et non par le code du transporteur.
originCodeRecommandéLieu de départ du moyen de transport.
awbPrefixFacultatifPréfixe de la lettre de transport aérien.
awbNumberFacultatifNuméro de la lettre de transport aérien.
weightFacultatifPoids total du moyen de transport.
weightUnitFacultatifUnité de weight.
amountFacultatifValeur totale du moyen de transport.

La lettre de transport aérien est facultative. La clé du moyen de transport est dérivée de carrierCode, serviceNumber et de la date.

Envoyez destinationCode et originCode dans votre format existant. Zonos gère la correspondance avec les listes de ports douaniers.

1mutation BrokerageManifestCreate($input: ManifestInput!, $lineIds: [ID!]!) {
2 brokerageManifestCreate(input: $input, lineIds: $lineIds) {
3 id
4 carrierCode
5 serviceNumber
6 destinationCode
7 arrivalDate
8 }
9}

Une expédition maritime utilise le même appel avec transportationMode: SEA, un SCAC dans carrierCode, le numéro de voyage dans serviceNumber, un vesselName et une date d’arrivée fixée à plusieurs semaines plutôt qu’à quelques heures.

Colis acceptés ultérieurement

Les colis acceptés après la création du moyen de transport y sont rattachés avec manifestLinesLink.

MUTATION

graphql

mutation ManifestLinesLink($manifestId: ID!, $lineIds: [ID!]!) {
  manifestLinesLink(manifestId: $manifestId, lineIds: $lineIds) {
    id
  }
}

Un chemin plus court pour l’Europe 

Les colis hors États-Unis peuvent se passer du moyen de transport. Transmettez le code d’opérateur avec le tableau.

1mutation BrokerageManifestLinesCreate(
2$postalOperatorCode: PostalOperatorCode
3$input: [ManifestLineInput!]!
4) {
5 brokerageManifestLinesCreate(
6 postalOperatorCode: $postalOperatorCode
7 input: $input
8 ) {
9 id
10 trackingNumber
11 }
12}

postalOperatorCode fournit ce que le moyen de transport porterait autrement. Un colis peut remplacer la valeur par défaut définie au niveau de la requête par sa propre valeur.

Les colis à destination des États-Unis nécessitent toujours un moyen de transport : la déclaration en douane mentionne le transporteur, le service et le port d’arrivée.

Remarques sur les données pour l’UE 

IOSS

Envoyez le numéro IOSS dans taxIdNumber lorsque la vente a été effectuée sous le régime IOSS.

Format : IM, un code d’État membre de l’UE à 3 chiffres, puis 7 chiffres. Exemple : IM5281234567.

  • Valide : soumission établie sans TVA à l’importation.
  • Mal formé ou absent : soumission établie avec TVA à l’importation. Envoyez le numéro d’enregistrement ou omettez le champ. N’envoyez pas de numéros de séquence ni de nombres de lignes.

Valeurs CAF

Les droits et la TVA de l’UE sont calculés sur la valeur CAF : marchandises plus frais d’expédition. Envoyez shippingCost et shippingCostCurrency sur chaque colis à destination de l’UE. Les omettre revient à traiter l’expédition comme nulle et sous-estime la soumission.

Partie destinataire

Une partie DESTINATION avec le code pays du destinataire est obligatoire. Elle détermine les règles applicables.

Remarques sur les données pour les États-Unis 

Parties complètes

Les deux parties nécessitent une adresse complète : nom, rue, localité, code postal, État, pays. administrativeAreaCode accepte le code d’État à deux lettres.

Classification

Un code tarifaire est obligatoire par ligne de marchandises : 10 chiffres de préférence, 6 au minimum. Les codes à six chiffres sont complétés et validés. Les lignes sans code ne peuvent pas être déclarées.

Ce que nous prenons en charge

Résolu par Zonos à partir de la configuration de votre compte et des marchandises du colis :

  • Importateur officiel
  • Caution douanière et garantie
  • Type de déclaration et code du déclarant
  • Droits, taxes et frais
  • Transmission à la douane

Remarques générales 

Colis en double

referenceNumber doit être unique parmi vos colis. Réutiliser une référence renvoie l’enregistrement existant et le déplace vers le nouveau moyen de transport; ses articles et ses parties ne sont pas mis à jour. Pour corriger un colis, contactez Zonos plutôt que de le renvoyer sous la même référence.

Valeurs

  • Envoyez exactement l’un des champs amount ou totalAmount par article. Envoyer les deux, ou aucun, fait échouer la soumission.
  • currencyCode est défini une seule fois par colis. Toutes les valeurs d’articles du colis l’utilisent.
  • Si vous envoyez upc sans gtin, l’UPC est utilisé comme GTIN.
  • Les valeurs d’énumération sont des chaînes simples, par exemple "KILOGRAM".
Réserver une démo

Cette page vous a-t-elle été utile?