API des bons de commande

🚀 Pourquoi utiliser l’API des bons de commande?

Les bons de commande sont des éléments essentiels de la gestion des stocks et de la logistique dans DataDocks. Ils représentent des ententes pour des produits devant être livrés dans vos entrepôts (entrant) ou expédiés à partir de ceux-ci (sortant). L’API des bons de commande vous permet de créer, suivre et gérer ces documents essentiels de façon automatisée, connectant ainsi directement vos systèmes de chaîne d’approvisionnement à vos opérations d’entrepôt.

Problèmes réels résolus par cette API

Rationaliser le traitement des commandes : Créez et mettez à jour automatiquement des bons de commande depuis votre ERP ou votre système de gestion des commandes
Améliorer la visibilité sur les stocks : Suivez les arrivées et départs prévues avec des informations détaillées sur les produits
Simplifier la gestion des transporteurs : Associez des transporteurs aux bons de commande pour optimiser la logistique
Améliorer la planification : Définissez des horaires prévus pour mieux gérer les ressources de l’entrepôt
Activer l’analyse avancée : Accédez à des données structurées de bons de commande pour le suivi et l’analyse

Démarrage rapide en 5 minutes

Prêt à créer votre premier bon de commande via l’API? Suivez ces étapes simples :

Obtenez votre jeton API auprès du support
Identifiez le sous-domaine de votre emplacement (ex. : your-warehouse.datadocks.com)
Créez un bon de commande de base avec cette commande :

Voir exemple cURL

curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/purchase_orders \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "purchase_order": {
      "po_number": "PO-2023-001",
      "carrier_name": "Express Logistics",
      "outbound": false,
      "expected_starts_at": "2023-06-01T08:00:00-04:00",
      "expected_ends_at": "2023-06-01T16:00:00-04:00",
      "purchase_order_items": [
        {
          "product_name": "Widgets",
          "unit_name": "Pallet",
          "quantity": 10,
          "weight": 500
        }
      ]
    }
  }'

C’est fait ! Votre bon de commande est maintenant dans DataDocks. Vérifiez votre tableau de bord pour le voir.

Architecture générale de l’API

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Votre système  │──────▶│   API DataDocks │──────▶│  Opérations     │
│ (ERP/OMS/TMS)   │◀──────┤  (REST/JSON)    │◀──────┤  d’entrepôt     │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                 │  ▲
                                 │  │
                                 ▼  │
                          ┌─────────────────┐
                          │ Rendez-vous &   │
                          │ planification   │
                          │                 │
                          └─────────────────┘

Authentification

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

Authorization: Token YOUR_API_TOKEN

Lister les bons de commande

Objectif

Récupérer une liste paginée de bons de commande avec filtrage optionnel par numéro de BC. Utilisez ce point de terminaison pour synchroniser les bons de commande avec vos systèmes, vérifier le statut des livraisons attendues ou préparer des rapports d’activités de l’entrepôt.

Cas d’usages métier

Synchroniser les bons de commande avec votre ERP ou système de gestion des commandes
Générer des rapports sur les mouvements d’inventaire attendus
Surveiller les prochaines livraisons ou expéditions
Suivre la performance des transporteurs à travers les bons de commande

Requête HTTP

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

Paramètres de requête

Paramètre	Type	Obligatoire	Description	Exemple
`page`	Integer	Non	Numéro de page pour la pagination (1 par défaut)	`page=2`
`po_number`	String	Non	Filtrer par le numéro de BC (insensible à la casse)	`po_number=A-1000`

Format de la réponse

La réponse contient un tableau d’objets bon de commande, chacun avec les champs suivants :

Champ	Type	Description
`id`	Integer	Identifiant unique du bon de commande
`po_number`	String	Numéro du bon de commande
`name`	String	Nom généré automatiquement selon les détails du BC
`carrier_name`	String	Nom du transporteur assigné
`location_name`	String	Nom de l’emplacement d’entrepôt
`outbound`	Boolean	S’il s’agit d’une commande sortante (true) ou entrante (false)
`expected_starts_at`	String	Horodatage ISO8601 de début prévu
`expected_ends_at`	String	Horodatage ISO8601 de fin prévu
`custom_values`	Objet	Paires clé-valeur de champs personnalisés
`purchase_order_items`	Tableau	Liste des articles associés à ce bon de commande

Chaque article dans purchase_order_items comprend :

Champ	Type	Description
`id`	Integer	Identifiant unique de l’article
`customer_name`	String	Nom du client associé à l’article
`product_name`	String	Nom du produit
`unit_name`	String	Unité de mesure (ex. : « Palette », « Boîte »)
`quantity`	Number	Quantité de produit
`weight`	Number	Poids de l’article
`custom_values`	Objet	Champs personnalisés pour cet article

Exemples de code

cURL

Voir exemple cURL

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

# Filtré par numéro de bon de commande
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders?po_number=A-1000"

JavaScript

Voir exemple JavaScript

// Utilisation de fetch API avec filtre sur le numéro de BC
const getPurchaseOrders = async (poNumber) => {
  const params = new URLSearchParams();
  if (poNumber) params.append("po_number", poNumber);

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

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(
      `Échec de récupération des bons de commande : ${JSON.stringify(errorData)}`
    );
  }

  return response.json();
};

Exemple de réponse

Voir exemple de réponse

[
  {
    "id": 1,
    "po_number": "A-1000",
    "name": "A-1000-FastCo-Cereal",
    "carrier_name": "FastCo",
    "location_name": "Toronto",
    "outbound": false,
    "expected_starts_at": "2020-10-09T13:35:00-04:00",
    "expected_ends_at": "2020-10-15T13:35:00-04:00",
    "custom_values": {
      "expected_at": "2020-10-09",
      "travel_type": "Plane",
      "forklift_operator": "Joe"
    },
    "purchase_order_items": [
      {
        "id": 2,
        "customer_name": "FishCo",
        "product_name": "Trout",
        "unit_name": "Skid",
        "quantity": 16,
        "weight": 102,
        "custom_values": {}
      },
      {
        "id": 1,
        "customer_name": "FishCo",
        "product_name": "Cereal",
        "unit_name": "Skid",
        "quantity": 33,
        "weight": 581,
        "custom_values": {}
      }
    ]
  }
]

Récupérer un bon de commande unique

Objectif

Obtenir l’information détaillée pour un bon de commande spécifique par identifiant. Utilisez ce point de terminaison lorsque vous avez besoin de toutes les données d’un bon de commande, y compris tous ses articles et champs personnalisés.

Cas d’usages métier

Afficher les détails d’un bon de commande dans votre application
Vérifier un bon de commande avant traitement/livraison/réception
Accéder à la liste complète des articles d’une commande spécifique
Vérifier les valeurs de champs personnalisés pour l’intégration avec d’autres systèmes

Requête HTTP

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

Paramètres d’URL

Paramètre	Type	Obligatoire	Description
`id`	Integer	Oui	Identifiant unique du bon de commande

Réponse

Une requête réussie retourne un 200 OK avec l’objet complet du bon de commande (même format que la réponse de liste).

Exemples de code

cURL

Voir exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript

Voir exemple JavaScript

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

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Bon de commande #${purchaseOrderId} introuvable`);
      }

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

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

Créer un bon de commande

Objectif

Créer un nouvel enregistrement de bon de commande dans DataDocks. Ce point de terminaison vous permet d’ajouter de nouveaux bons de commande et leurs articles de ligne de façon automatisée, en intégrant votre système de gestion de commandes directement à vos opérations d’entrepôt.

Arbre de décision : Quand créer un BC via API

┌─────────────────┐
│ Ajouter un bon  │
│ de commande ?   │
└────────┬────────┘
         │
         ▼
┌─────────────────────┐    Oui    ┌──────────────┐
│ Intégration avec    │──────────▶│   Idéal API  │
│ votre ERP/Système ? │           │              │
└────────┬────────────┘           └──────────────┘
         │ Non
         ▼
┌────────────────────┐    Oui      ┌────────────────┐
│ En créer plusieurs │────────────▶│ Utiliser import│
│ d’un coup ?        │            │ en lot         │
└────────┬───────────┘            └────────────────┘
         │ Non
         ▼
┌────────────────────┐
│   Utiliser l’UI    │
│   web              │
└────────────────────┘

Cas d’usages métier

Intégration système : Créez des bons de commande directement depuis votre ERP ou gestion de commandes
Traitement automatisé : Convertissez automatiquement des commandes clients en bons de commande
Intégration EDI : Transformez des documents EDI 850 en BC DataDocks
Intégration fournisseurs : Permettez à vos fournisseurs de soumettre des bons via vos systèmes

Requête HTTP

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

Corps de la requête

Paramètre	Type	Obligatoire	Description	Contraintes	Par défaut	Exemple
`po_number`	String	Oui	Numéro de bon de commande	Doit être unique	Aucun	`"PO-2023-001"`
`carrier_name`	String	Non *	Nom du transporteur	Aucun	Aucun	`"Express Logistics"`
`carrier_number`	String	Non	Numéro de société du transporteur	Doit correspondre à un transporteur existant	Aucun	`"EXP-001"`
`location_name`	String	Non	Nom de l’emplacement	Doit correspondre à un emplacement existant	Emplacement actuel	`"Toronto Warehouse"`
`outbound`	Boolean	Non	Commande sortante ou non	Aucun	`false`	`true`
`expected_starts_at`	String	Non	Horodatage ISO8601 du début prévu	Format ISO8601 valide	Aucun	`"2023-06-01T08:00:00-04:00"`
`expected_ends_at`	String	Non	Horodatage ISO8601 de fin prévue	Format ISO8601 valide	Aucun	`"2023-06-01T16:00:00-04:00"`
`alternate_reference_number`	String	Non	Numéro de référence alternatif	Doit être unique	Aucun	`"REF-123"`
`reference_numbers`	Tableau	Non	Autres numéros de référence	Aucun	Aucun	`["BOL-123", "SHIP-456"]`
`closed`	Boolean	Non	Si le BC est fermé	Aucun	`false`	`true`
`custom_values`	Objet	Non *	Valeurs de champs personnalisés. La clé est en minuscules, les espaces remplacés par des tirets bas.	Selon la configuration de l’emplacement	`{}`	`{"department": "Produce"}`
`purchase_order_items`	Tableau	Non	Articles pour le BC	Au moins un fortement recommandé	`[]`	Voir ci-dessous

Chaque article dans purchase_order_items peut inclure :

Paramètre	Type	Obligatoire	Description	Contraintes	Exemple
`customer_name`	String	Non *	Nom du client	Aucun	`"Acme Corp"`
`customer_number`	String	Non *	Numéro de société du client	Doit correspondre à un client existant	`"ACME-001"`
`product_name`	String	Non *	Nom du produit	Aucun	`"Widgets"`
`unit_name`	String	Non *	Unité de mesure	Aucun	`"Pallet"`
`quantity`	Number	Non *	Quantité du produit	Doit être positif	`10`
`weight`	Number	Non *	Poids de l’article	Doit être positif	`500`
`custom_values`	Objet	Non *	Champs personnalisés pour cet article. Même convention que ci-dessus.	Selon emplacement	`{"color": "Blue"}`

* Certains champs peuvent être obligatoires selon la configuration de l’emplacement

Réponse

Une requête réussie retourne un 200 OK avec l’objet complet du bon de commande, incluant l’id généré et autres valeurs attribuées par le système.

Exemples de code

cURL

Voir exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2023-001",
         "carrier_name": "Express Logistics",
         "outbound": false,
         "expected_starts_at": "2023-06-01T08:00:00-04:00",
         "expected_ends_at": "2023-06-01T16:00:00-04:00",
         "custom_values": {
           "department": "Electronics",
           "priority": "High"
         },
         "purchase_order_items": [
           {
             "product_name": "Laptops",
             "unit_name": "Box",
             "quantity": 50,
             "weight": 250,
             "custom_values": {
               "model": "XPS 13"
             }
           },
           {
             "product_name": "Monitors",
             "unit_name": "Pallet",
             "quantity": 10,
             "weight": 500,
             "custom_values": {
               "size": "27-inch"
             }
           }
         ]
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders

JavaScript

Voir exemple JavaScript

const createPurchaseOrder = async (purchaseOrderData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders`,
      {
        method: "POST",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ purchase_order: purchaseOrderData }),
      }
    );

    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 création du bon de commande :\n${errorMessages}`);
    }

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

Mettre à jour un bon de commande

Objectif

Mettre à jour les détails d’un bon de commande existant. Ce point de terminaison vous permet de modifier tout aspect d’un bon de commande, y compris ses articles, dates, information transporteur et champs personnalisés.

Cas d’usages métier

Données à jour : Mettez à jour les dates de livraison ou l’information sur le transporteur si nécessaire
Modifier le contenu : Ajoutez, retirez ou changez des articles selon les besoins
Changer le statut : Marquez les bons de commande comme fermés une fois traités
Ajouter de l’information : Mettez à jour les champs personnalisés avec les numéros de suivi ou données de livraison

Requête HTTP

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

Paramètres d’URL

Paramètre	Type	Obligatoire	Description
`id`	Integer	Oui	Identifiant unique du bon de commande

Corps de la requête

Le corps accepte les mêmes paramètres que la création. Seuls les champs à modifier doivent être inclus.

Scénarios communs de mise à jour

Mettre à jour les dates

{
  "purchase_order": {
    "expected_starts_at": "2023-06-05T08:00:00-04:00",
    "expected_ends_at": "2023-06-05T16:00:00-04:00"
  }
}

Changer le transporteur

{
  "purchase_order": {
    "carrier_name": "Fast Transit Inc",
    "carrier_number": "FTI-001"
  }
}

Fermer un bon de commande

{
  "purchase_order": {
    "closed": true
  }
}

Mettre à jour les articles

{
  "purchase_order": {
    "purchase_order_items": [
      {
        "id": 123,
        "quantity": 15
      },
      {
        "product_name": "New Product",
        "unit_name": "Box",
        "quantity": 5,
        "weight": 25
      }
    ]
  }
}

Exemples de code

cURL

Voir exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "purchase_order": {
         "carrier_name": "Updated Logistics Co",
         "expected_starts_at": "2023-06-02T08:00:00-04:00",
         "custom_values": {
           "tracking_number": "TRK12345"
         }
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript

Voir exemple JavaScript

const updatePurchaseOrder = async (purchaseOrderId, updateData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/${purchaseOrderId}`,
      {
        method: "PUT",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ purchase_order: updateData }),
      }
    );

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

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

Retirer tous les articles du bon de commande

Pour supprimer tous les articles d’un bon de commande, incluez le paramètre clear_po_items avec la valeur true :

{
  "purchase_order": {
    "clear_po_items": "true",
    "purchase_order_items": [
      {
        "product_name": "New Product",
        "unit_name": "Box",
        "quantity": 10
      }
    ]
  }
}

Cela supprime tous les articles existants et les remplace par ceux précisés (le cas échéant).

Lister les bons de commande avec rendez-vous réservés

Objectif

Récupérer les bons de commande liés à des rendez-vous réservés, avec leurs détails. Ce point de terminaison est conçu pour les clients qui préfèrent l’interrogation périodique (polling) aux webhooks pour surveiller les modifications et réservations.

Cas d’usages métier

Alternative aux webhooks : Surveillez les réservations de rendez-vous sans webhook
Suivi de statut de rendez-vous : Vérifiez quels BC sont associés à des réservations confirmées
Synchronisation incrémentale : Utilisez updated_since pour ne récupérer que les changements
Suivi de la livraison prévue : Voyez quand les BC sont prévus pour livraison/ramassage réelle
Rapports par emplacement : Obtenez l’activité de rendez-vous par site d’entrepôt

Requête HTTP

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

Paramètres de requête

Paramètre	Type	Obligatoire	Description	Exemple
`start_time`	String	Non	Horodatage ISO8601 – rendez-vous après ou égal à cette date	`start_time=2023-06-01T08:00:00-04:00`
`end_time`	String	Non	Horodatage ISO8601 – rendez-vous avant ou égal à cette date	`end_time=2023-06-30T17:00:00-04:00`
`limit`	Integer	Non	Nombre max de résultats (défaut : 100, max : 250)	`limit=50`
`offset`	Integer	Non	Nombre de résultats à ignorer (pagination, défaut : 0)	`offset=100`
`updated_since`	String	Non	ISO8601 – POs créés/mis à jour depuis cette date	`updated_since=2023-06-01T00:00:00-04:00`

Format de la réponse

La réponse est un tableau de BC ayant au moins un rendez-vous réservé. Chaque objet inclut :

Champ	Type	Description
`po_number`	String	Numéro du bon de commande
`appointments`	Tableau	Liste des rendez-vous liés à ce BC

Chaque rendez-vous dans appointments contient :

Champ	Type	Description
`appointment_id`	String	Identifiant unique du rendez-vous
`appointment_number`	String	Numéro humainement lisible du rendez-vous
`scheduled_at`	String	Horodatage ISO8601 de réservation du rendez-vous
`location`	String	Nom du site où le rendez-vous est réservé

Remarques importantes

Résultats filtrés : Seuls les BC avec au moins un rendez-vous réservé sont retournés
Données en temps réel : Les rendez-vous reflètent le statut actuel
Fuseau horaire : Les dates sont retournées selon le fuseau de l’emplacement
Pagination : Utilisez limit et offset pour gérer les grands résultats

Exemples de code

cURL

Voir exemple cURL

# Requête de base
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/with_booked_appointments"

# Avec filtres temporels et pagination
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/with_booked_appointments?start_time=2023-06-01T08:00:00-04:00&end_time=2023-06-30T17:00:00-04:00&limit=50&offset=0"

# Synchronisation incrémentale
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/with_booked_appointments?updated_since=2023-06-15T12:00:00-04:00"

JavaScript

Voir exemple JavaScript

const getPurchaseOrdersWithAppointments = async (filters = {}) => {
  const params = new URLSearchParams()

  // Ajout des filtres optionnels
  if (filters.startTime) params.append('start_time', filters.startTime)
  if (filters.endTime) params.append('end_time', filters.endTime)
  if (filters.limit) params.append('limit', filters.limit)
  if (filters.offset) params.append('offset', filters.offset)
  if (filters.updatedSince) params.append('updated_since', filters.updatedSince)

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

    if (!response.ok) {
      const errorData = await response.json()
      throw new Error(
        `Échec de récupération des bons de commande avec rendez-vous : ${JSON.stringify(errorData)}`,
      )
    }

    return await response.json()
  } catch (error) {
    console.error('Erreur lors de la récupération des bons de commande avec rendez-vous :', error)
    throw error
  }
}

// Exemple de synchronisation incrémentale
const syncAppointments = async (lastSyncTime) => {
  const data = await getPurchaseOrdersWithAppointments({
    updatedSince: lastSyncTime,
    limit: 100,
  })

  // Traitement des données de rendez-vous
  data.forEach((po) => {
    console.log(`BC ${po.po_number} a ${po.appointments.length} rendez-vous`)
    po.appointments.forEach((appointment) => {
      console.log(`  - ${appointment.appointment_number} prévu pour ${appointment.scheduled_at}`)
    })
  })

  return data
}

Exemple de réponse

Voir exemple de réponse

[
  {
    "po_number": "PO123456",
    "appointments": [
      {
        "appointment_id": "appt_001",
        "appointment_number": "A123",
        "scheduled_at": "2025-06-24T14:00:00-04:00",
        "location": "Toronto DC"
      },
      {
        "appointment_id": "appt_002",
        "appointment_number": "A124",
        "scheduled_at": "2025-06-25T09:00:00-04:00",
        "location": "Toronto DC"
      }
    ]
  },
  {
    "po_number": "PO789012",
    "appointments": [
      {
        "appointment_id": "appt_003",
        "appointment_number": "A125",
        "scheduled_at": "2025-06-26T11:30:00-04:00",
        "location": "Toronto DC"
      }
    ]
  }
]

Supprimer un bon de commande

Objectif

Retirer un bon de commande du système. Ce point de terminaison vous permet de supprimer des bons de commande devenus inutiles.

Points importants à considérer

Avant de supprimer un BC, tenez compte des points suivants :

Le BC ne doit pas être associé à des rendez-vous actifs
La suppression est permanente et irréversible
Dans bien des cas, il vaut mieux marquer un BC comme « fermé » plutôt que de le supprimer

Cas d’usages métier

Nettoyer des données de test : Retirer des BC de test ou fictifs
Enlever des doublons : Nettoyer après déduplication des données
Maintenance du système : Retirer d’anciens BC inutilisés

Requête HTTP

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

Paramètres d’URL

Paramètre	Type	Obligatoire	Description
`id`	Integer	Oui	Identifiant unique du bon de commande

Réponse

Une requête réussie retourne un 204 No Content, indiquant que le BC a bien été supprimé.

Exemples de code

cURL

Voir exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -X DELETE \
     https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/1

JavaScript

Voir exemple JavaScript

const deletePurchaseOrder = async (purchaseOrderId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders/${purchaseOrderId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Bon de commande #${purchaseOrderId} introuvable`);
      }

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

    return true; // Succès
  } catch (error) {
    console.error("Erreur lors de la suppression du bon de commande :", error);
    throw error;
  }
};

Résolution automatique des entités

Résolution de transporteur

Lors de la création ou mise à jour d’un bon de commande, vous pouvez fournir soit carrier_name soit carrier_number (ou les deux) :

Si vous fournissez carrier_number, le système tentera de trouver un transporteur correspondant par numéro de société
S’il y a une correspondance, le nom et l’ID du transporteur seront automatiquement associés au BC
Sinon, le système utilisera la valeur de carrier_number comme nom

Résolution des produits

Lors de la création ou modification d’articles de BC :

Si le nom du produit correspond (insensible à la casse) à un produit existant, il sera utilisé
Si non, l’article sera créé mais non lié à un enregistrement produit complet
Contactez le support si vous voulez créer un produit inexistant

Résolution de l’unité

Comme pour les produits :

Si le nom de l’unité correspond à une unité existante (insensible à la casse), elle sera utilisée
Sinon, l’article ne sera pas lié à une unité
Contactez le support pour créer une nouvelle unité si nécessaire

Bonnes pratiques

Gestion des données

Numéros de BC uniques : Assurez-vous que chaque bon de commande a un identifiant unique
Utilisez les numéros de société du transporteur : Quand c’est possible, privilégiez ce champ
Validez côté client : Assurez-vous de l’intégrité des données avant l’envoi
Utilisez le drapeau “fermé” plutôt que la suppression : Sceller les BC terminés au lieu de les effacer
Gérez bien vos champs personnalisés : Utilisez uniquement ceux configurés pour votre site

Optimisation des performances

Inclure toutes les données pertinentes : Privilégiez un seul appel API complet
Utilisez les opérations par lot : Groupez les synchronisations liées
Soyez précis dans vos requêtes : Utilisez les filtres pour réduire la volumétrie

Erreurs fréquentes et dépannage

Unicité du numéro de BC : Les numéros de commande doivent être exclusifs à chaque emplacement
Format de la date : Les dates doivent être au format ISO8601 (ex. : "2023-06-01T08:00:00-04:00")
Association du transporteur : En cas de souci d’association, vérifiez le numéro de société utilisé
Types de champs personnalisés : Les champs JSON resteront JSON, les autres seront convertis en texte
Nettoyer les articles : Utilisez bien le paramètre clear_po_items lors de la réécriture complète des lignes

Gestion des erreurs

Code d’erreur	Description	Cause possible
400	Mauvaise requête	Valeurs ou format invalides
404	Introuvable	L’ID du bon de commande n’existe pas
422	Entité non traitable	Validation non réussie (ex. : champ obligatoire absent)
401	Non autorisé	Jeton API invalide ou absent
403	Interdit	Permissions insuffisantes

Exemple de réponse en cas d’erreur

{
  "errors": {
    "po_number": ["ne peut pas être vide"],
    "purchase_order_items": ["doit inclure au moins un article"]
  }
}

Aide et support

Si vous rencontrez des problèmes non couverts ici :

Vérifiez la réponse d’erreur : La plupart des erreurs API détaillent le problème exact
Vérifiez les permissions : Assurez-vous que votre jeton API est autorisé
Testez par étapes : Découpez les appels complexes pour dépister la source du problème

🚀 Pourquoi utiliser l’API des bons de commande?​

Problèmes réels résolus par cette API​

Démarrage rapide en 5 minutes​

Architecture générale de l’API​

Authentification​

Lister les bons de commande​

Objectif​

Cas d’usages métier​

Requête HTTP​

Paramètres de requête​

Format de la réponse​

Exemples de code​

cURL​

JavaScript​

Exemple de réponse​

Récupérer un bon de commande unique​

Objectif​

Cas d’usages métier​

Requête HTTP​

Paramètres d’URL​

Réponse​

Exemples de code​

cURL​

JavaScript​

Créer un bon de commande​

Objectif​

Arbre de décision : Quand créer un BC via API​

Cas d’usages métier​

Requête HTTP​

Corps de la requête​

Réponse​

Exemples de code​

cURL​

JavaScript​

Mettre à jour un bon de commande​

Objectif​

Cas d’usages métier​

Requête HTTP​

Paramètres d’URL​

Corps de la requête​

Scénarios communs de mise à jour​

Mettre à jour les dates​

Changer le transporteur​

Fermer un bon de commande​

Mettre à jour les articles​

Exemples de code​

cURL​

JavaScript​

Retirer tous les articles du bon de commande​

Lister les bons de commande avec rendez-vous réservés​

Objectif​

Cas d’usages métier​

Requête HTTP​

Paramètres de requête​

Format de la réponse​

Remarques importantes​

Exemples de code​

cURL​

JavaScript​

Exemple de réponse​

Supprimer un bon de commande​

Objectif​

Points importants à considérer​

Cas d’usages métier​

Requête HTTP​

Paramètres d’URL​

Réponse​

Exemples de code​

cURL​

JavaScript​

Résolution automatique des entités​

Résolution de transporteur​

Résolution des produits​

Résolution de l’unité​

Bonnes pratiques​

Gestion des données​

Optimisation des performances​

Erreurs fréquentes et dépannage​

Gestion des erreurs​

Exemple de réponse en cas d’erreur​

🚀 Pourquoi utiliser l’API des bons de commande?

Problèmes réels résolus par cette API

Démarrage rapide en 5 minutes

Architecture générale de l’API

Authentification

Lister les bons de commande

Objectif

Cas d’usages métier

Requête HTTP

Paramètres de requête

Format de la réponse

Exemples de code

cURL

JavaScript

Exemple de réponse

Récupérer un bon de commande unique

Objectif

Cas d’usages métier

Requête HTTP

Paramètres d’URL

Réponse

Exemples de code

cURL

JavaScript

Créer un bon de commande

Objectif

Arbre de décision : Quand créer un BC via API

Cas d’usages métier

Requête HTTP

Corps de la requête

Réponse

Exemples de code

cURL

JavaScript

Mettre à jour un bon de commande

Objectif

Cas d’usages métier

Requête HTTP

Paramètres d’URL

Corps de la requête

Scénarios communs de mise à jour

Mettre à jour les dates

Changer le transporteur

Fermer un bon de commande

Mettre à jour les articles

Exemples de code

cURL

JavaScript

Retirer tous les articles du bon de commande

Lister les bons de commande avec rendez-vous réservés

Objectif

Cas d’usages métier

Requête HTTP

Paramètres de requête

Format de la réponse

Remarques importantes

Exemples de code

cURL

JavaScript

Exemple de réponse

Supprimer un bon de commande

Objectif

Points importants à considérer

Cas d’usages métier

Requête HTTP

Paramètres d’URL

Réponse

Exemples de code

cURL

JavaScript

Résolution automatique des entités

Résolution de transporteur

Résolution des produits

Résolution de l’unité

Bonnes pratiques

Gestion des données

Optimisation des performances

Erreurs fréquentes et dépannage

Gestion des erreurs

Exemple de réponse en cas d’erreur