Constituez le catalogue de votre compte vérifié par programmation, directement depuis votre propre système.
L'API Catalog est l'une des trois façons de constituer le catalogue de votre compte vérifié. C'est l'option destinée aux expéditeurs qui disposent de ressources de développement et d'un système qui contient déjà leurs données produit : un ERP, un WMS, un PIM ou une plateforme d'expédition. Ce système reste la source de référence et transmet directement les produits à Zonos, au lieu de les synchroniser depuis une intégration de canal ou de les importer via un fichier CSV. Si vous vendez via un canal pris en charge, ou si vous préférez ne pas écrire de code, ces deux options permettent de constituer le même catalogue avec moins d'efforts.
Les articles créés via l'API sont traités exactement comme les articles provenant de toute autre source : une fois qu'un article figure dans votre catalogue, sa provenance n'a aucune importance pour Zonos. Chaque article est classé à des fins douanières si vous n'avez pas fourni de code SH, contrôlé au regard des exigences des agences gouvernementales partenaires (PGA) des États-Unis, et utilisé pour calculer les droits et taxes des expéditions dans lesquelles il figure.
Une partie de ce processus échappe toutefois à l'API. Lorsque le contrôle PGA signale un article comme Nécessite une attention, le questionnaire de conformité associé à ce signalement doit être rempli et confirmé dans Dashboard : aucune API n'existe pour cette étape, et Zonos pré-remplit tout ce qu'il peut, si bien que l'essentiel du travail consiste à vérifier et à confirmer. La personne qui développe cette intégration n'est généralement pas celle qui traite ces signalements : prévoyez donc qu'une personne de votre organisation s'en charge dans Dashboard une fois votre catalogue chargé. Les articles signalés ne sont pas bloqués à l'expédition, mais les traiter avant d'expédier permet d'éviter qu'une expédition soit retenue à la frontière américaine.
Créez un article de catalogue pour chaque produit que vous expédiez.
Assurez-vous que chaque article comporte un identifiant que votre transporteur postal transmettra.
Lorsque les données de votre expédition parviennent à Zonos, chaque ligne est rapprochée de l'article de catalogue correspondant, dont les données produit sont appliquées au calcul.
Créer des articles de catalogue
catalogItemCreate accepte une liste, ce qui vous permet d'envoyer de nombreux produits en une seule requête.
Si vous envoyez un produit dont le SKU ou l'ID produit existe déjà, Zonos met à jour ce produit au lieu d'en ajouter un second. Les nouvelles tentatives et les exécutions répétées sont donc sans risque.
En contrepartie, deux produits différents partageant le même SKU ou le même ID produit seront fusionnés en un seul. Vérifiez l'absence de doublons dans vos données avant un chargement en masse.
Votre identifiant unique pour le produit. *Chaque produit doit avoir un SKU, un ID produit, ou les deux.
productId
Oui*
L'identifiant du produit sur votre plateforme. *Chaque produit doit avoir un SKU, un ID produit, ou les deux.
manufacturerProductId
UE uniquement
L'identifiant produit non standardisé du fabricant (NS-PID). Obligatoire pour les envois B2C à destination de l'UE d'une valeur inférieure ou égale à 150 €.
gtin
UE uniquement
L'identifiant produit standardisé du fabricant (S-PID), en chiffres uniquement. Obligatoire pour les envois B2C à destination de l'UE d'une valeur inférieure ou égale à 150 €, si le produit possède un code-barres.
name
Oui
Le nom du produit.
customsDescription
Recommandé
La nature du produit, en termes simples, pour la déclaration en douane. Utilisez « T-shirt en coton », et non « Tee Summer Vibes ».
countryOfOrigin
Recommandé
Le code ISO à 2 lettres du pays de fabrication du produit. Nécessaire pour calculer précisément les droits de douane.
measurements
Recommandé
Poids et dimensions, utilisés pour la tarification et la déclaration en douane.
hsCode
Non
Le code SH universel à 6 chiffres. Si vous l'omettez, Zonos classe le produit à partir de son nom et de sa description.
amount
Non
Le prix du produit, sous forme numérique.
currencyCode
Non
Le code ISO à 3 lettres de la devise du prix. Obligatoire lorsque vous fournissez amount.
itemType
Non
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE ou PARTIAL_ITEM. Évite que des articles non physiques soient déclarés comme marchandises.
provinceOfOrigin
Non
L'État ou la province d'origine du produit. Exigé par certains pays de destination.
productComposition
Non
Une liste de {material, percentage}. Sans cette information, les textiles ne peuvent pas être classés au-delà de 6 chiffres.
catalogItemUrl
Non
Un lien vers la page du produit sur votre site. Améliore la précision de la classification.
imageUrl
Non
Une URL publiquement accessible de l'image du produit. Améliore la précision de la classification.
Ajouter les identifiants produit de l'UE (PID)
Si vous expédiez vers l'UE avec votre compte vérifié, l'UE exige, à compter du 1er novembre 2026, des identifiants produit (PID) pour les envois entre entreprises et consommateurs (B2C) d'une valeur inférieure ou égale à 150 €. Enregistrez-les sur vos articles de catalogue. Pour la plupart des comptes vérifiés, votre opérateur postal transmet les données d'expédition à Zonos, et Zonos rapproche chaque article de l'expédition de votre catalogue et applique les identifiants que vous avez enregistrés : vous n'avez donc rien de plus à envoyer au moment de l'expédition.
Identifiant↕
Description↕
Champ de l'API↕
Obligatoire ?↕
Identifiant produit du marchand (M-PID)
Votre SKU ou code article
sku
Toujours
Identifiant produit non standardisé du fabricant (NS-PID)
La référence de modèle ou de pièce du fabricant. Si vous fabriquez vous-même le produit, utilisez votre propre numéro de modèle ou de pièce.
manufacturerProductId
Toujours
Identifiant produit standardisé du fabricant (S-PID)
Le code-barres (UPC, EAN ou ISBN)
gtin
Seulement si le produit en a un
Envoyez les identifiants avec catalogItemCreate pour les nouveaux produits. Pour les produits déjà présents dans votre catalogue, envoyez-les avec catalogItemUpdate, qui accepte les mêmes champs. Faites correspondre le sku de chaque article au SKU que vous utilisez partout ailleurs, afin que Zonos puisse relier les deux.
Envoyez le gtin en chiffres uniquement, sans tirets ni espaces. Les valeurs UPC, EAN, JAN et ISBN à 13 chiffres vont toutes dans ce seul champ. Si vous disposez d'un ISBN à 10 chiffres, envoyez plutôt sa version à 13 chiffres.
Si un produit n'a pas de code-barres, omettez gtin plutôt que d'envoyer une chaîne vide, de réutiliser votre SKU ou d'y saisir un texte de substitution tel que N/A.
Si vous appelez vous-même l'API Landed Cost, vous pouvez également inclure ces identifiants dans votre requête Landed Cost. La plupart des comptes vérifiés ne le font pas, car c'est l'opérateur postal qui transmet les données d'expédition à Zonos.
Zonos rattache chaque ligne d'expédition à un article de catalogue à l'aide de vos identifiants, dans cet ordre : ID produit, puis SKU, puis nom. Veillez à ce que les identifiants que vous utilisez soient exacts et cohérents entre votre catalogue et les données que vous envoyez à votre transporteur.
Les envois postaux comportent une contrainte supplémentaire. Zonos reçoit un ensemble de champs limité de la part des transporteurs postaux et, sur de nombreux axes, la description douanière est le seul champ qui contient une information propre au produit. Une description identique pour l'ensemble de votre catalogue ne permet à elle seule d'identifier aucun produit.
La façon de formater l'identifiant dans les données d'expédition que vous envoyez à votre transporteur dépend de votre opérateur postal, car chacun rapproche les expéditions de votre catalogue différemment. Rendez-vous sur tous les opérateurs postaux et sélectionnez le vôtre. Sa page indique comment fonctionne le rapprochement pour cet opérateur et précisément ce qu'il faut envoyer.
Il n'est pas obligatoire de définir le customsDescription de l'article avec la même chaîne que celle envoyée à votre transporteur, mais cela permet de comparer directement les deux lorsqu'une ligne n'est pas rapprochée et que vous devez en déterminer la raison.
Le rapprochement échoue généralement lorsque :
L'identifiant utilisé par votre opérateur postal pour le rapprochement est absent des données d'expédition.
L'identifiant ne correspond exactement à aucun élément de votre catalogue.
L'identifiant est tronqué par la limite de caractères du transporteur.
La mise en forme varie d'une expédition à l'autre.
Ce comportement est encore en cours de finalisation et pourrait évoluer avant le lancement.
Mettre à jour des articles de catalogue
catalogItemUpdate utilise le même type d'entrée que la création. Envoyez uniquement les champs que vous souhaitez modifier.
Remarque : les champs omis restent inchangés, ce qui rend les mises à jour partielles sans risque. Envoyer null n'efface pas une valeur : il est ignoré. Vous pouvez remplacer une valeur par une autre, mais vous ne pouvez pas la vider via l'API. Contactez votre représentant Zonos si vous devez effacer un champ.
Relire vos articles
La requête catalogItem accepte id, productId ou sku. Utilisez-la pour vérifier les données que Zonos détient pour un produit.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Supprimer des articles de catalogue
catalogItemDelete prend en entrée des ID d'articles de catalogue Zonos, et non vos SKU ou ID produit. Récupérez d'abord l'ID à l'aide de la requête catalogItem.
API Catalog
API Catalog
Constituez le catalogue de votre compte vérifié par programmation, directement depuis votre propre système.
L'API Catalog est l'une des trois façons de constituer le catalogue de votre compte vérifié. C'est l'option destinée aux expéditeurs qui disposent de ressources de développement et d'un système qui contient déjà leurs données produit : un ERP, un WMS, un PIM ou une plateforme d'expédition. Ce système reste la source de référence et transmet directement les produits à Zonos, au lieu de les synchroniser depuis une intégration de canal ou de les importer via un fichier CSV. Si vous vendez via un canal pris en charge, ou si vous préférez ne pas écrire de code, ces deux options permettent de constituer le même catalogue avec moins d'efforts.
Les articles créés via l'API sont traités exactement comme les articles provenant de toute autre source : une fois qu'un article figure dans votre catalogue, sa provenance n'a aucune importance pour Zonos. Chaque article est classé à des fins douanières si vous n'avez pas fourni de code SH, contrôlé au regard des exigences des agences gouvernementales partenaires (PGA) des États-Unis, et utilisé pour calculer les droits et taxes des expéditions dans lesquelles il figure.
Une partie de ce processus échappe toutefois à l'API. Lorsque le contrôle PGA signale un article comme Nécessite une attention, le questionnaire de conformité associé à ce signalement doit être rempli et confirmé dans Dashboard : aucune API n'existe pour cette étape, et Zonos pré-remplit tout ce qu'il peut, si bien que l'essentiel du travail consiste à vérifier et à confirmer. La personne qui développe cette intégration n'est généralement pas celle qui traite ces signalements : prévoyez donc qu'une personne de votre organisation s'en charge dans Dashboard une fois votre catalogue chargé. Les articles signalés ne sont pas bloqués à l'expédition, mais les traiter avant d'expédier permet d'éviter qu'une expédition soit retenue à la frontière américaine.
Fonctionnement
Créez un article de catalogue pour chaque produit que vous expédiez.
Assurez-vous que chaque article comporte un identifiant que votre transporteur postal transmettra.
Lorsque les données de votre expédition parviennent à Zonos, chaque ligne est rapprochée de l'article de catalogue correspondant, dont les données produit sont appliquées au calcul.
Créer des articles de catalogue
catalogItemCreateaccepte une liste, ce qui vous permet d'envoyer de nombreux produits en une seule requête.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Envoyer deux fois le même produit
Si vous envoyez un produit dont le SKU ou l'ID produit existe déjà, Zonos met à jour ce produit au lieu d'en ajouter un second. Les nouvelles tentatives et les exécutions répétées sont donc sans risque.
En contrepartie, deux produits différents partageant le même SKU ou le même ID produit seront fusionnés en un seul. Vérifiez l'absence de doublons dans vos données avant un chargement en masse.
Champs
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEouPARTIAL_ITEM. Évite que des articles non physiques soient déclarés comme marchandises.provinceOfOriginproductComposition{material, percentage}. Sans cette information, les textiles ne peuvent pas être classés au-delà de 6 chiffres.catalogItemUrlimageUrlAjouter les identifiants produit de l'UE (PID)
Si vous expédiez vers l'UE avec votre compte vérifié, l'UE exige, à compter du 1er novembre 2026, des identifiants produit (PID) pour les envois entre entreprises et consommateurs (B2C) d'une valeur inférieure ou égale à 150 €. Enregistrez-les sur vos articles de catalogue. Pour la plupart des comptes vérifiés, votre opérateur postal transmet les données d'expédition à Zonos, et Zonos rapproche chaque article de l'expédition de votre catalogue et applique les identifiants que vous avez enregistrés : vous n'avez donc rien de plus à envoyer au moment de l'expédition.
skumanufacturerProductIdgtinEnvoyez les identifiants avec
catalogItemCreatepour les nouveaux produits. Pour les produits déjà présents dans votre catalogue, envoyez-les aveccatalogItemUpdate, qui accepte les mêmes champs. Faites correspondre leskude chaque article au SKU que vous utilisez partout ailleurs, afin que Zonos puisse relier les deux.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input)idskumanufacturerProductIdgtinEnvoyez le
gtinen chiffres uniquement, sans tirets ni espaces. Les valeurs UPC, EAN, JAN et ISBN à 13 chiffres vont toutes dans ce seul champ. Si vous disposez d'un ISBN à 10 chiffres, envoyez plutôt sa version à 13 chiffres.Si un produit n'a pas de code-barres, omettez
gtinplutôt que d'envoyer une chaîne vide, de réutiliser votre SKU ou d'y saisir un texte de substitution tel queN/A.Si vous appelez vous-même l'API Landed Cost, vous pouvez également inclure ces identifiants dans votre requête Landed Cost. La plupart des comptes vérifiés ne le font pas, car c'est l'opérateur postal qui transmet les données d'expédition à Zonos.
Pour connaître les exigences de la réglementation, consultez le guide des identifiants produit de l'UE.
Rendre vos articles identifiables
Zonos rattache chaque ligne d'expédition à un article de catalogue à l'aide de vos identifiants, dans cet ordre : ID produit, puis SKU, puis nom. Veillez à ce que les identifiants que vous utilisez soient exacts et cohérents entre votre catalogue et les données que vous envoyez à votre transporteur.
Les envois postaux comportent une contrainte supplémentaire. Zonos reçoit un ensemble de champs limité de la part des transporteurs postaux et, sur de nombreux axes, la description douanière est le seul champ qui contient une information propre au produit. Une description identique pour l'ensemble de votre catalogue ne permet à elle seule d'identifier aucun produit.
La façon de formater l'identifiant dans les données d'expédition que vous envoyez à votre transporteur dépend de votre opérateur postal, car chacun rapproche les expéditions de votre catalogue différemment. Rendez-vous sur tous les opérateurs postaux et sélectionnez le vôtre. Sa page indique comment fonctionne le rapprochement pour cet opérateur et précisément ce qu'il faut envoyer.
Il n'est pas obligatoire de définir le
customsDescriptionde l'article avec la même chaîne que celle envoyée à votre transporteur, mais cela permet de comparer directement les deux lorsqu'une ligne n'est pas rapprochée et que vous devez en déterminer la raison.Le rapprochement échoue généralement lorsque :
Mettre à jour des articles de catalogue
catalogItemUpdateutilise le même type d'entrée que la création. Envoyez uniquement les champs que vous souhaitez modifier.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Relire vos articles
La requête
catalogItemaccepteid,productIdousku. Utilisez-la pour vérifier les données que Zonos détient pour un produit.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Supprimer des articles de catalogue
catalogItemDeleteprend en entrée des ID d'articles de catalogue Zonos, et non vos SKU ou ID produit. Récupérez d'abord l'ID à l'aide de la requêtecatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Ressources associées
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Cette page a-t-elle été utile?