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 :

Obtenez votre jeton API auprès du support
Trouvez votre sous-domaine d’emplacement (ex. : votre-entrepot.datadocks.com)
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"
    }
  }'

Voilà ! Vous avez créé votre premier produit. Vérifiez sur votre tableau de bord DataDocks.

Aperçu de l’architecture de l’API

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   Votre système │──────▶│   API DataDocks │──────▶│  Ops d’entrepôt │
│ (ERP/WMS)       │◀──────┤   (REST/JSON)   │◀──────┤   (Produits)    │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  ▲
                                  │  │
                                  ▼  │
                           ┌─────────────────┐
                           │ Listes          │
                           │ d’emballage &   │
                           │ Rendez-vous     │
                           └─────────────────┘

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ètre	Type	Obligatoire	Description	Exemple
`page`	Entier	Non	Numéro de page pour la pagination (par défaut 1)	`page=2`
`name`	Chaîne	Non	Filtrer par nom de produit (insensible à la casse, commence par)	`name=widget`
`sku`	Chaîne	Non	Filtrer 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 :

Champ	Type	Description
`id`	Entier	Identifiant unique du produit
`name`	Chaîne	Nom du produit
`sku`	Chaîne	Code 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ètre	Type	Obligatoire	Description
`id`	Entier	Oui	Identifiant 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 ?

┌─────────────────┐
│  Besoin d’ajouter│
│    un produit ? │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     Oui      ┌──────────────────┐
│ Plusieurs       │────────────▶│  Songez à         │
│ produits à la   │             │  l’importation    │
│ fois ?          │             │  en vrac          │
└────────┬────────┘             └───────────────────┘
         │ Non
         ▼
┌─────────────────┐     Oui      ┌─────────────────┐
│ Addition        │────────────▶│ Utiliser         │
│ unique ?        │             │ l’interface Web  │
└────────┬────────┘             └─────────────────┘
         │ Non
         ▼
┌─────────────────┐
│    Parfait      │
│    pour 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ètre	Type	Obligatoire	Description	Contraintes	Exemple
`name`	Chaîne	Oui	Nom du produit	Ne doit pas être vide	`"Premium Widget"`
`sku`	Chaîne	Oui	SKU du produit	Doit ê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ètre	Type	Obligatoire	Description
`id`	Entier	Oui	Identifiant 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’erreur	Description	Cause possible
400	Requête invalide	Valeurs ou format non valides
404	Introuvable	L’ID du produit n’existe pas
422	Entité non traitable	Validation échouée (ex. SKU en doublon)
401	Non autorisé	Jeton API invalide ou manquant
403	Interdit	Permissions 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ètre	Type	Obligatoire	Description
`id`	Entier	Oui	Identifiant 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’erreur	Description	Cause possible
404	Introuvable	L’ID du produit n’existe pas
401	Non autorisé	Jeton API invalide ou manquant
403	Interdit	Permissions insuffisantes pour la suppression
422	Entité non traitable	Suppression 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 :

Champ	Règles de validation
`name`	Obligatoire, ne doit pas être vide
`sku`	Obligatoire, 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 :

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

🚀 Pourquoi utiliser l’API Produits ?​

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

Démarrage rapide en 5 minutes​

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

Authentification​

Liste des produits​

Objectif​

Cas d’usage métier​

Requête HTTP​

Paramètres de requête​

Format de réponse​

Exemples de code​

cURL​

JavaScript​

Exemple de réponse​

Pagination​

Récupérer un produit spécifique​

Objectif​

Cas d’usage métier​

Requête HTTP​

Paramètres de chemin​

Réponse​

Exemples de code​

cURL​

JavaScript​

Création d’un produit​

Objectif​

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

Cas d’usage métier​

Requête HTTP​

Corps de la requête​

Réponse​

Exemples de code​

cURL​

JavaScript​

Mise à jour d’un produit​

Objectif​

Cas d’usage métier​

Requête HTTP​

Paramètres de chemin​

Corps de la requête​

Scénarios courants de mise à jour​

Mettre à jour le nom du produit​

Mettre à jour tous les champs​

Exemples de code​

cURL​

JavaScript​

Gestion des erreurs​

Suppression d’un produit​

Objectif​

Points importants à considérer​

Cas d’usage métier​

Requête HTTP​

Paramètres de chemin​

Réponse​

Exemples de code​

cURL​

JavaScript​

Gestion des erreurs​

Règles de validation des champs​

Bonnes pratiques​

Gestion des données​

Optimisation des performances​

Pièges fréquents et Dépannage​

Aide et support​

🚀 Pourquoi utiliser l’API Produits ?

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

Démarrage rapide en 5 minutes

Aperçu de l’architecture de l’API

Authentification

Liste des produits

Objectif

Cas d’usage métier

Requête HTTP

Paramètres de requête

Format de réponse

Exemples de code

cURL

JavaScript

Exemple de réponse

Pagination

Récupérer un produit spécifique

Objectif

Cas d’usage métier

Requête HTTP

Paramètres de chemin

Réponse

Exemples de code

cURL

JavaScript

Création d’un produit

Objectif

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

Cas d’usage métier

Requête HTTP

Corps de la requête

Réponse

Exemples de code

cURL

JavaScript

Mise à jour d’un produit

Objectif

Cas d’usage métier

Requête HTTP

Paramètres de chemin

Corps de la requête

Scénarios courants de mise à jour

Mettre à jour le nom du produit

Mettre à jour tous les champs

Exemples de code

cURL

JavaScript

Gestion des erreurs

Suppression d’un produit

Objectif

Points importants à considérer

Cas d’usage métier

Requête HTTP

Paramètres de chemin

Réponse

Exemples de code

cURL

JavaScript

Gestion des erreurs

Règles de validation des champs

Bonnes pratiques

Gestion des données

Optimisation des performances

Pièges fréquents et Dépannage

Aide et support