Aller au contenu principal

API Produits

🚀 Pourquoi utiliser l’API Produits ?​

Les produits sont des éléments essentiels d’inventaire dans DataDocks que vous gérez à travers vos entrepôts. L’API Produits vous permet de synchroniser de façon programmatique votre catalogue de produits avec DataDocks, assurant ainsi une exactitude et une cohérence en temps réel entre vos systèmes de gestion d’inventaire et vos opérations d’entreposage.

Problématiques réelles résolues par cette API​

  • Maintenir l’exactitude de l’inventaire : Gardez les donnĂ©es produits synchronisĂ©es entre votre ERP et DataDocks
  • Optimiser la rĂ©ception des marchandises : Assurez-vous que les produits soient bien identifiĂ©s lors de la rĂ©ception
  • Faciliter la crĂ©ation de listes d’emballage : Ajoutez rapidement des produits valides dans les listes d’emballage
  • AmĂ©liorer le reporting : Suivez le mouvement des produits Ă  travers les entrepĂ´ts avec des donnĂ©es de produit cohĂ©rentes
  • Éliminer la double saisie : Mettez Ă  jour les produits une seule fois dans votre système et synchronisez automatiquement avec DataDocks

Démarrage rapide en 5 minutes​

Vous souhaitez voir l’API en action immédiatement ? Suivez ces étapes pour créer votre premier produit :

  1. Obtenez votre jeton API auprès du support
  2. Trouvez votre sous-domaine d’emplacement (ex. : votre-entrepot.datadocks.com)
  3. Créez un produit de base avec cette commande :
Voir exemple cURL
curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/products \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "product": {
      "name": "Premium Widget",
      "sku": "WIDGET-001"
    }
  }'
  1. Voilà ! Vous avez créé votre premier produit. Vérifiez sur votre tableau de bord DataDocks.

Aperçu de l’architecture de l’API​

Authentification​

Toutes les requêtes API doivent inclure votre jeton API dans l’en-tête Authorization :

Authorization: Token YOUR_API_TOKEN

Liste des produits​

Objectif​

Obtenez une liste paginée de produits avec possibilité de filtrer par nom ou SKU. Utilisez ce point de terminaison pour rechercher dans votre catalogue de produits, synchroniser avec des systèmes externes, ou alimenter des listes déroulantes dans vos applications.

Cas d’usage métier​

  • Synchroniser les produits avec votre ERP ou WMS
  • Alimenter des interfaces de sĂ©lection de produits dans vos applications
  • GĂ©nĂ©rer des rapports d’inventaire
  • VĂ©rifier les informations produits lors du traitement des commandes

Requête HTTP​

GET https://[location_subdomain].datadocks.com/api/v1/products

Paramètres de requête​

ParamètreTypeObligatoireDescriptionExemple
pageEntierNonNuméro de page pour la pagination (par défaut 1)page=2
nameChaîneNonFiltrer par nom de produit (insensible à la casse, commence par)name=widget
skuChaîneNonFiltrer par SKU (insensible à la casse, correspondance exacte)sku=ABC123

Format de réponse​

La réponse contient un tableau paginé d’objets produits, chacun avec les champs suivants :

ChampTypeDescription
idEntierIdentifiant unique du produit
nameChaîneNom du produit
skuChaîneCode SKU (Stock Keeping Unit) du produit

Exemples de code​

cURL​

Voir exemple cURL
# Liste de base
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/products

# Filtrer par nom
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/products?name=premium"

# Filtrer par SKU
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/products?sku=WIDGET-001"

JavaScript​

Voir exemple JavaScript
// Utilise fetch API avec filtres
const getProducts = async (nameFilter, skuFilter) => {
  const params = new URLSearchParams();
  if (nameFilter) params.append("name", nameFilter);
  if (skuFilter) params.append("sku", skuFilter);

  const response = await fetch(
    `https://YOUR_LOCATION.datadocks.com/api/v1/products?${params.toString()}`,
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  // GĂ©rer les erreurs potentielles
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Échec de la récupération des produits : ${JSON.stringify(errorData)}`);
  }

  return response.json();
};

Exemple de réponse​

Voir exemple de réponse
[
  {
    "id": 1,
    "name": "Premium Widget",
    "sku": "WIDGET-001"
  },
  {
    "id": 2,
    "name": "Standard Widget",
    "sku": "WIDGET-002"
  },
  {
    "id": 3,
    "name": "Widget Accessories",
    "sku": "WIDGET-ACC-001"
  }
]

Pagination​

La réponse est paginée pour gérer le volume de données. Pour les détails sur les en-têtes de pagination et la navigation, veuillez consulter la documentation Pagination.

Récupérer un produit spécifique​

Objectif​

Obtenir l’information détaillée d’un produit spécifique par identifiant. Utilisez ce point de terminaison lorsque vous avez besoin de données complètes sur un produit particulier.

Cas d’usage métier​

  • Afficher les dĂ©tails complets d’un produit dans votre application
  • VĂ©rifier les dĂ©tails du produit avant d’ajouter Ă  une liste d’emballage
  • RĂ©cupĂ©rer les informations actuelles d’un produit pour la gestion d’inventaire

Requête HTTP​

GET https://[location_subdomain].datadocks.com/api/v1/products/:id

Paramètres de chemin​

ParamètreTypeObligatoireDescription
idEntierOuiIdentifiant unique du produit

Réponse​

Une requête réussie retourne un code 200 OK avec l’objet produit complet, au même format que la réponse de la liste.

Exemples de code​

cURL​

Voir exemple cURL
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript​

Voir exemple JavaScript
const getProduct = async (productId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "GET",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Produit #${productId} introuvable`);
      }

      const errorData = await response.json();
      throw new Error(
        `Échec de la récupération du produit : ${JSON.stringify(errorData)}`
      );
    }

    return await response.json();
  } catch (error) {
    console.error("Erreur lors de la récupération du produit :", error);
    throw error;
  }
};

Création d’un produit​

Objectif​

Ajouter un nouveau produit à votre catalogue DataDocks. Ce point de terminaison permet de créer des produits qui pourront ensuite être utilisés dans les listes d’emballage et le suivi de l’inventaire.

Arbre de décision : Quand créer un produit via l’API ?​

Cas d’usage métier​

  • IntĂ©gration système : CrĂ©ez des produits directement depuis votre ERP ou WMS
  • Mises Ă  jour automatisĂ©es du catalogue : Ajoutez des produits de façon automatique Ă  votre entrepĂ´t
  • Migration de donnĂ©es : TransfĂ©rez des enregistrements produit depuis des systèmes hĂ©ritĂ©s
  • IntĂ©gration des fournisseurs : Permettez aux fournisseurs d’enregistrer de nouveaux produits via vos systèmes

Requête HTTP​

POST https://[location_subdomain].datadocks.com/api/v1/products

Corps de la requête​

ParamètreTypeObligatoireDescriptionContraintesExemple
nameChaîneOuiNom du produitNe doit pas être vide"Premium Widget"
skuChaîneOuiSKU du produitDoit être unique pour l’emplacement"WIDGET-001"

Réponse​

Une requête réussie retourne un code 200 OK avec l’objet produit complet, incluant l’id généré.

Exemples de code​

cURL​

Voir exemple cURL
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "product": {
         "name": "Premium Widget",
         "sku": "WIDGET-001"
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/products

JavaScript​

Voir exemple JavaScript
const createProduct = async (productData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products`,
      {
        method: "POST",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ product: productData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      const errorMessages = Object.entries(errorData.errors || {})
        .map(([field, messages]) => `${field}: ${messages.join(", ")}`)
        .join("\n");

      throw new Error(`Échec de la création du produit :\n${errorMessages}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Erreur API :", error);
    throw error;
  }
};

// Exemple d’utilisation
const newProduct = {
  name: "Premium Widget",
  sku: "WIDGET-001",
};

createProduct(newProduct)
  .then((product) => console.log("Produit créé :", product))
  .catch((error) => console.error("Échec de la création du produit :", error));

Mise à jour d’un produit​

Objectif​

Mettre à jour les informations d’un produit existant. Ce point de terminaison vous permet de modifier n’importe quel attribut d’un produit.

Cas d’usage métier​

  • Garder vos donnĂ©es Ă  jour : Mettez Ă  jour le nom ou le SKU d’un produit lors de changements dans vos systèmes
  • Corriger les erreurs : Corrigez les fautes de frappe ou donnĂ©es erronĂ©es dans les produits
  • Standardiser les donnĂ©es produits : Mettez Ă  jour l’information selon de nouvelles conventions de nommage
  • Synchroniser vos systèmes : Gardez DataDocks alignĂ© avec votre gestion d’inventaire

Requête HTTP​

PUT https://[location_subdomain].datadocks.com/api/v1/products/:id

Paramètres de chemin​

ParamètreTypeObligatoireDescription
idEntierOuiIdentifiant unique du produit

Corps de la requête​

Le corps de la requête accepte les mêmes paramètres que le point de terminaison de création. Seuls les champs que vous souhaitez modifier doivent être inclus.

Scénarios courants de mise à jour​

Mettre à jour le nom du produit​

{
  "product": {
    "name": "Premium Widget XL"
  }
}

Mettre à jour tous les champs​

{
  "product": {
    "name": "Premium Widget XL",
    "sku": "WIDGET-XL-001"
  }
}

Exemples de code​

cURL​

Voir exemple cURL
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "product": {
         "name": "Premium Widget XL"
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript​

Voir exemple JavaScript
const updateProduct = async (productId, updateData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "PUT",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ product: updateData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Échec de la mise à jour du produit : ${JSON.stringify(errorData)}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Erreur lors de la mise Ă  jour du produit :", error);
    throw error;
  }
};

// Exemple : mise à jour du nom uniquement
const updateProductName = async (productId, newName) => {
  try {
    const updatedProduct = await updateProduct(productId, {
      name: newName,
    });

    console.log(`Nom du produit #${updatedProduct.id} mis à jour avec succès`);
    return updatedProduct;
  } catch (error) {
    console.error(`Échec de la mise à jour du produit #${productId} :`, error);
    throw error;
  }
};

Gestion des erreurs​

Code d’erreurDescriptionCause possible
400RequĂŞte invalideValeurs ou format non valides
404IntrouvableL’ID du produit n’existe pas
422Entité non traitableValidation échouée (ex. SKU en doublon)
401Non autoriséJeton API invalide ou manquant
403InterditPermissions insuffisantes pour la mise Ă  jour

Suppression d’un produit​

Objectif​

Retirer un produit du système. Ce point de terminaison vous permet de supprimer des produits qui ne sont plus nécessaires.

Points importants à considérer​

Avant de supprimer un produit, tenez compte des éléments suivants :

  • Le produit ne doit pas ĂŞtre rĂ©fĂ©rencĂ© dans une liste d’emballage ou un rendez-vous actif
  • La suppression est permanente et irrĂ©versible
  • Dans de nombreux cas, il est prĂ©fĂ©rable d’archiver ou de dĂ©sactiver un produit plutĂ´t que le supprimer

Cas d’usage métier​

  • Nettoyage des donnĂ©es de test : Supprimez des produits de test ou factices
  • Retrait des produits obsolètes : Supprimez les produits qui ne sont plus dans votre catalogue
  • Suppression des doublons : Nettoyez les enregistrements après dĂ©duplication
  • Maintenance système : Retirez les anciens produits inutilisĂ©s

Requête HTTP​

DELETE https://[location_subdomain].datadocks.com/api/v1/products/:id

Paramètres de chemin​

ParamètreTypeObligatoireDescription
idEntierOuiIdentifiant unique du produit

Réponse​

Une requête réussie retourne un code 204 No Content, indiquant que le produit a été supprimé avec succès.

Exemples de code​

cURL​

Voir exemple cURL
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -X DELETE \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript​

Voir exemple JavaScript
const deleteProduct = async (productId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Produit #${productId} introuvable`);
      }

      const errorData = await response.json();
      throw new Error(`Échec de la suppression du produit : ${JSON.stringify(errorData)}`);
    }

    return true; // Suppression réussie
  } catch (error) {
    console.error("Erreur lors de la suppression du produit :", error);
    throw error;
  }
};

Gestion des erreurs​

Code d’erreurDescriptionCause possible
404IntrouvableL’ID du produit n’existe pas
401Non autoriséJeton API invalide ou manquant
403InterditPermissions insuffisantes pour la suppression
422Entité non traitableSuppression impossible (ex. lié à une liste d’emballage)

Règles de validation des champs​

Lors de la création ou de la mise à jour des produits, les règles suivantes s’appliquent :

ChampRègles de validation
nameObligatoire, ne doit pas ĂŞtre vide
skuObligatoire, doit être unique dans l’emplacement

Bonnes pratiques​

Gestion des données​

  • Conservez des SKU cohĂ©rents : Utilisez des formats de SKU cohĂ©rents entre vos systèmes
  • Validez cĂ´tĂ© client : VĂ©rifiez que les donnĂ©es respectent les exigences avant l’envoi
  • Soyez prudent avec la suppression : Envisagez une modification du SKU plutĂ´t que la suppression quand possible
  • Regroupez vos opĂ©rations : Pour mettre Ă  jour plusieurs produits, envisagez l’importation en vrac

Optimisation des performances​

  • Groupez vos mises Ă  jour : Regroupez les mises Ă  jour produits connexes
  • Utilisez la pagination : Ne rĂ©cupĂ©rez que les produits nĂ©cessaires grâce Ă  la pagination
  • Filtrez efficacement : Utilisez les filtres Ă  disposition pour limiter le transfert de donnĂ©es
  • Mettez en cache les recherches courantes : Conservez localement les informations produit consultĂ©es frĂ©quemment

Pièges fréquents et Dépannage​

  • UnicitĂ© du SKU : Les SKU des produits doivent ĂŞtre uniques par emplacement. Veillez Ă  l’unicitĂ© du SKU Ă  la crĂ©ation.
  • RĂ©fĂ©rences produits : Un produit ne peut ĂŞtre supprimĂ© s’il est utilisĂ© dans des listes d’emballage ou des rendez-vous actifs.
  • SensibilitĂ© Ă  la casse : Pour les recherches par nom, l’API fait une correspondance « commence par » insensible Ă  la casse.
  • Recherche SKU : Pour les recherches par SKU, l’API exige une correspondance exacte, insensible Ă  la casse.

Aide et support​

Si vous rencontrez des problèmes non couverts par cette documentation :

  1. Consultez la réponse d’erreur : La majorité des erreurs API incluent des informations spécifiques sur le problème rencontré
  2. Vérifiez les permissions : Assurez-vous que votre jeton API a les permissions nécessaires
  3. Testez par étapes : Décomposez les opérations complexes pour identifier précisément le problème