Aller au contenu principal

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 la livraison de produits Ă  vos entrepĂŽts (entrants) ou leur expĂ©dition (sortants). L’API des bons de commande vous permet de crĂ©er, suivre et gĂ©rer ces documents essentiels de façon programmatique, en connectant directement vos systĂšmes de la chaĂźne d’approvisionnement Ă  vos opĂ©rations d’entrepĂŽt.

ProblĂšmes rĂ©solus par cette API​

  • Rationaliser le traitement des commandes : CrĂ©ez et mettez Ă  jour automatiquement des bons de commande Ă  partir de votre ERP ou systĂšme de gestion des commandes
  • AmĂ©liorer la visibilitĂ© sur les stocks : Suivez les arrivĂ©es et dĂ©parts prĂ©vus avec des informations dĂ©taillĂ©es sur les produits
  • Simplifier la gestion des transporteurs : Associez des transporteurs aux bons de commande pour simplifier la logistique
  • Optimiser la planification : DĂ©finissez les Ă©chĂ©anciers prĂ©vus pour mieux gĂ©rer les ressources de l’entrepĂŽt
  • Permettre l’analyse avancĂ©e : AccĂ©dez Ă  des donnĂ©es structurĂ©es sur les bons de commande pour le reporting 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 :

  1. Obtenez votre jeton API auprĂšs du support
  2. Identifiez votre sous-domaine d’emplacement (ex. : votre-entrepot.datadocks.com)
  3. 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
        }
      ]
    }
  }'
  1. C’est fait ! Votre bon de commande est maintenant dans DataDocks. VĂ©rifiez votre tableau de bord pour le consulter.

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

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Votre systĂšme  │──────▶│    API DataDocks│──────▶│  Ops EntrepĂŽt   │
│ (ERP/OMS/TMS)   │◀───────   (REST/JSON)   │◀─────── (BC/Articles)   │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  â–Č
                                  │  │
                                  â–Œ  │
                           ┌─────────────────┐
                           │   Rendez-vous   │
                           │   & horaires    │
                           │                 │
                           └─────────────────┘

Authentification​

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

Authorization: Token YOUR_API_TOKEN

Liste des bons de commande​

Objectif​

RĂ©cupĂšre une liste paginĂ©e des bons de commande, avec possibilitĂ© de filtrer par numĂ©ro de bon. Utilisez ce point d’accĂšs pour synchroniser vos bons de commande avec vos systĂšmes, vĂ©rifier l’état des livraisons attendues ou prĂ©parer vos rapports d’activitĂ© d’entrepĂŽt.

Cas d’utilisation mĂ©tier​

  • Synchroniser les bons de commande avec votre ERP ou systĂšme de gestion de commandes
  • GĂ©nĂ©rer des rapports sur les mouvements de stocks attendus
  • Surveiller les livraisons ou expĂ©ditions Ă  venir
  • 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ĂštreTypeObligatoireDescriptionExemple
pageEntierNonN° de page pour la pagination (par défaut à 1)page=2
po_numberTexteNonFiltrer par le numéro exact de bon (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 :

ChampTypeDescription
idEntierIdentifiant unique du bon de commande
po_numberTexteNuméro du bon de commande
nameTexteNom auto-généré basé sur les détails du bon
carrier_nameTexteNom du transporteur affecté au bon
location_nameTexteNom du site/entrepĂŽt
outboundBooléenSortant (true) ou entrant (false)
expected_starts_atTexteHorodatage ISO8601 du début prévu
expected_ends_atTexteHorodatage ISO8601 de la fin prévue
custom_valuesObjetPaires clé/valeur de champs personnalisés
purchase_order_itemsTableauListe des articles associés à ce bon

Chaque item dans purchase_order_items contient :

ChampTypeDescription
idEntierIdentifiant unique de l’article
customer_nameTexteNom du client associĂ© Ă  l’article
product_nameTexteNom du produit
unit_nameTexteUnitĂ© de mesure (ex. : « Palette », « BoĂźte »)
quantityNombreQuantité du produit
weightNombrePoids de l’article
custom_valuesObjetChamps 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
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/purchase_orders?po_number=A-1000"

JavaScript​

Voir exemple JavaScript
// Utiliser fetch API avec filtre sur le numéro de bon
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 l’obtention 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": {}
      }
    ]
  }
]

Obtenir un bon de commande spĂ©cifique​

Objectif​

RĂ©cupĂšre l’information dĂ©taillĂ©e sur un bon de commande Ă  partir de son identifiant. Utilisez ce point d'accĂšs lorsque vous avez besoin de toutes les donnĂ©es relatives Ă  une commande particuliĂšre, y compris tous ses articles et champs personnalisĂ©s.

Cas d’utilisation mĂ©tier​

  • Afficher les dĂ©tails d’un bon de commande dans votre application
  • VĂ©rifier les donnĂ©es avant traitement
  • AccĂ©der Ă  la liste complĂšte des articles d’une commande donnĂ©e
  • VĂ©rifier des champs personnalisĂ©s pour intĂ©gration avec d’autres systĂšmes

RequĂȘte HTTP​

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

Paramùtres de chemin​

ParamĂštreTypeObligatoireDescription
idEntierOuiID unique du bon de commande

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne un code 200 OK et l’objet complet du bon de commande, 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/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Ă©ation d’un bon de commande​

Objectif​

CrĂ©er un nouveau bon de commande dans DataDocks. Ce point d’accĂšs vous permet d’ajouter de nouveaux bons et leurs lignes d’articles de façon programmatique, en intĂ©grant votre systĂšme de gestion des commandes Ă  vos opĂ©rations d’entrepĂŽt.

Arbre de dĂ©cision : Quand crĂ©er un BC via API ?​

┌─────────────────┐
│ Faut-il ajouter │
│ un bon de       │
│ commande ?      │
└────────┬────────┘
         │
         ▌
┌─────────────────┐     Oui      ┌─────────────────┐
│ IntĂ©gration     │────────────▶│ Parfait pour    │
│ avec votre ERP/ │             │ l’API !         │
│ systùme de com. │             │                 │
└────────┬────────┘             └─────────────────┘
         │ Non
         ▌
┌─────────────────┐     Oui      ┌─────────────────┐
│ Plusieurs bons  │────────────▶│ Utiliser l’      │
│ à traiter ?     │             │ importation      │
└────────┬────────┘             └ en vrac          ┘
         │ Non
         ▌
┌─────────────────┐
│ Utiliser l’     │
│ interface web   │
└─────────────────┘

Cas d’utilisation mĂ©tier​

  • IntĂ©gration systĂšme : CrĂ©ez des bons de commande directement Ă  partir de votre ERP
  • Traitement automatisé : Transformez automatiquement des commandes de vente en BCs
  • IntĂ©gration EDI : Convertissez des EDI 850 en bons de commande DataDocks
  • IntĂ©gration fournisseur : Permettez Ă  vos fournisseurs de soumettre des bons depuis leurs systĂšmes

RequĂȘte HTTP​

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

Corps de la requĂȘte​

ParamÚtreTypeObligatoireDescriptionContraintesValeur par défautExemple
po_numberTexteOuiNumĂ©ro du bon de commandeDoit ĂȘtre uniqueAucune"PO-2023-001"
carrier_nameTexteNon *Nom du transporteurAucuneAucune"Express Logistics"
carrier_numberTexteNonNuméro de société du transporteurDoit exister dans le systÚmeAucune"EXP-001"
location_nameTexteNonNom du siteDoit exister déjàSite courant"Toronto Warehouse"
outboundBooléenNonBon sortant ou entrantAucunefalsetrue
expected_starts_atTexteNonHoraire prévu de début (ISO8601)Format ISO8601 valideAucune"2023-06-01T08:00:00-04:00"
expected_ends_atTexteNonHoraire prévu de fin (ISO8601)Format ISO8601 valideAucune"2023-06-01T16:00:00-04:00"
alternate_reference_numberTexteNonNuméro de référence alternatifAucuneAucune"REF-123"
closedBooléenNonSi le bon est closAucunefalsetrue
custom_valuesObjetNon *Champs personnalisĂ©s (clĂ© en minuscules, espace par _).Selon configuration de l’emplacement{}{"department": "Produce"}
purchase_order_itemsTableauNonLignes de commandeAu moins un article recommandé[]Voir ci-dessous

Chaque article dans purchase_order_items peut inclure :

ParamĂštreTypeObligatoireDescriptionContraintesExemple
customer_nameTexteNon *Nom du clientAucune"Acme Corp"
customer_numberTexteNon *Numéro de société du clientDoit exister déjà"ACME-001"
product_nameTexteNon *Nom du produitAucune"Widgets"
unit_nameTexteNon *Unité de mesureAucune"Pallet"
quantityNombreNon *QuantitĂ©Doit ĂȘtre positif10
weightNombreNon *PoidsDoit ĂȘtre positif500
custom_valuesObjetNon *Champs personnalisĂ©s (clĂ© = lowercase, espace = _).Selon configuration de l’emplacement{"color": "Blue"}

* Certaines zones peuvent devenir obligatoires selon la configuration du site

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne un code 200 OK ainsi que l’objet du bon de commande complet (avec l’id gĂ©nĂ©rĂ© et autres valeurs 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;
  }
};

Mise à jour d’un bon de commande​

Objectif​

Met Ă  jour les dĂ©tails d’un bon de commande existant. Ce point d’accĂšs vous permet de modifier tout aspect d’un BC, notamment ses articles, dates, transporteur ou champs personnalisĂ©s.

Cas d’utilisation mĂ©tier​

  • Tenir l’information Ă  jour : Modifier des dates de livraison ou transporteur au besoin
  • Modifier le contenu : Ajouter, retirer ou modifier des lignes comme nĂ©cessaire
  • Changer le statut : Marquer des bons comme fermĂ©s Ă  l’exĂ©cution
  • Ajouter info de suivi : Mettre Ă  jour champs personnalisĂ©s (suivi, livraison, etc.)

RequĂȘte HTTP​

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

Paramùtres de chemin​

ParamĂštreTypeObligatoireDescription
idEntierOuiIdentifiant unique du BC

Corps de la requĂȘte​

Le corps accepte les mĂȘmes champs que pour la crĂ©ation. Ne transmettez que les champs Ă  modifier.

ScĂ©narios frĂ©quents de mise Ă  jour​

Mise à jour de 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"
  }
}

Fermeture d’un bon​

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

Mise à jour des 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 :", error);
    throw error;
  }
};

Supprimer tous les articles d’un bon de commande​

Pour retirer tous les articles du bon, inclure le paramùtre clear_po_items à true :

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

Cela supprimera tous les articles existants et les remplacera par ceux fournis (s’il y a lieu).

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

Objectif​

RĂ©cupĂ©rer les bons de commande qui sont associĂ©s Ă  des rendez-vous rĂ©servĂ©s, ainsi que le dĂ©tail de ces rendez-vous. Cette requĂȘte est conçue pour les clients qui prĂ©fĂšrent l’interrogation pĂ©riodique (polling) plutĂŽt que les webhooks.

Cas d’utilisation mĂ©tier​

  • Alternative au webhook : Suivre les prises de rendez-vous sans infrastructure webhook
  • Suivi d’état : VĂ©rifier quels BCs sont associĂ©s Ă  des rendez-vous
  • Synchronisation incrĂ©mentale : Utiliser updated_since pour ne recevoir que les changements depuis la derniĂšre requĂȘte
  • Suivi de la livraison planifiĂ©e : Voir quand les BCs sont horaires pour une livraison ou un ramassage exacts
  • Rapports par site : Suivre l’activitĂ© des rendez-vous par emplacement

RequĂȘte HTTP​

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

ParamĂštres de requĂȘte​

ParamĂštreTypeObligatoireDescriptionExemple
start_timeTexteNonISO8601 - Rendez-vous Ă  partir de ce momentstart_time=2023-06-01T08:00:00-04:00
end_timeTexteNonISO8601 - Rendez-vous jusqu’à ce momentend_time=2023-06-30T17:00:00-04:00
limitEntierNonNb maximum d’enregistrements (defaut : 100, max : 250)limit=50
offsetEntierNonNb à ignorer pour pagination (défaut : 0)offset=100
updated_sinceTexteNonISO8601 : BC crĂ©Ă©s / maj. depuis ce momentupdated_since=2023-06-01T00:00:00-04:00

Format de la rĂ©ponse​

La rĂ©ponse contient un tableau de bons ayant au moins un rendez-vous rĂ©servĂ©. Chaque objet inclut :

ChampTypeDescription
po_numberTexteNuméro du bon de commande
appointmentsTableauListe des rendez-vous associés à ce bon

Chaque rendez-vous dans appointments contient :

ChampTypeDescription
appointment_idTexteIdentifiant unique du rendez-vous
appointment_numberTexteNuméro humain du rendez-vous
scheduled_atTexteHorodatage ISO8601 prévu du rendez-vous
locationTexteNom du site oĂč le rendez-vous est pris

Notes importantes​

  • RĂ©sultats filtrĂ©s : Ne retourne que les bons associĂ©s Ă  au moins un rendez-vous pris
  • DonnĂ©es en temps rĂ©el : La rĂ©ponse reflĂšte l’état courant
  • Fuseau horaire : Les horodatages sont retournĂ©s selon le site
  • Pagination : Utilisez limit et offset pour de grands ensembles

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 plages horaires 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()

  // Ajouter les filtres
  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 BC avec rendez-vous : ${JSON.stringify(errorData)}`,
      )
    }

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

// Ex utilisation pour synchronisation
const syncAppointments = async (lastSyncTime) => {
  const data = await getPurchaseOrdersWithAppointments({
    updatedSince: lastSyncTime,
    limit: 100,
  })

  // Traiter les données
  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"
      }
    ]
  }
]

Suppression d’un bon de commande​

Objectif​

Supprimez un bon de commande du systĂšme. Cette opĂ©ration permet d’éliminer un bon qui n’est plus requis.

Points Ă  considĂ©rer​

Avant suppression, considérez :

  • Le bon ne doit pas ĂȘtre liĂ© Ă  un rendez-vous actif
  • L’opĂ©ration est irrĂ©versible
  • Dans bien des cas, fermez le bon au lieu de le supprimer

Cas d’utilisation mĂ©tier​

  • Effacer des donnĂ©es de tests : Supprimer des BC de test/dĂ©mo
  • Supprimer des doublons : Nettoyer aprĂšs une dĂ©duplication
  • Maintenance des donnĂ©es : Supprimer des anciens bons inutiles

RequĂȘte HTTP​

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

Paramùtres​

ParamĂštreTypeObligatoireDescription
idEntierOuiIdentifiant unique du bon

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne un code 204 No Content, indiquant la suppression rĂ©ussie.

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; // Supprimé avec succÚs
  } catch (error) {
    console.error("Erreur lors de la suppression du bon de commande :", error);
    throw error;
  }
};

RĂ©solution automatique d’entitĂ©s​

RĂ©solution du transporteur​

Lors de la crĂ©ation ou mise Ă  jour d’un bon, vous pouvez donner soit carrier_name soit carrier_number (ou les deux) :

  • Si vous donnez carrier_number, le systĂšme cherche le transporteur correspondant
  • Si une correspondance est trouvĂ©e, le nom et l’ID seront associĂ©s au bon
  • Sinon, la valeur de carrier_number sera utilisĂ©e comme nom

RĂ©solution produit​

Lors de création ou MAJ des articles :

  • Si le nom du produit correspond (insensible Ă  la casse), il sera utilisĂ©
  • Si aucun produit ne correspond, l’article sera crĂ©Ă© mais sans association exacte
  • Contactez le support pour crĂ©er un produit qui n’existerait pas encore

RĂ©solution unité​

Idem produits :

  • Si le nom de l’unitĂ© correspond (insensible Ă  la casse), il sera utilisĂ©
  • Sinon, l’article n’aura pas de liaison d’unitĂ© exacte
  • Contactez le support pour ajouter une nouvelle unitĂ© si nĂ©cessaire

Bonnes pratiques​

Gestion de donnĂ©es​

  • NumĂ©ros uniques : Chaque bon de commande doit avoir un identifiant unique
  • PrivilĂ©gier les numĂ©ros de transporteurs : Pour une association fiable des transporteurs
  • Valider cĂŽtĂ© client : VĂ©rifiez les donnĂ©es cĂŽtĂ© client avant la requĂȘte
  • Utiliser le statut « fermé » : Fermez plutĂŽt que supprimer un bon si possible
  • GĂ©rer les champs personnalisĂ©s : N’utiliser que ceux configurĂ©s pour votre site

Optimisation de performance​

  • Inclure toutes les donnĂ©es nĂ©cessaires dans un seul appel lorsque possible
  • Utiliser les opĂ©rations de lot : Groupez les mises Ă  jour connexes
  • Être prĂ©cis dans les filtres : Limitez les transferts en Ă©tant prĂ©cis

ProblĂšmes frĂ©quents et dĂ©pannage​

  • UnicitĂ© des numĂ©ros : Veillez Ă  l’unicitĂ© des BC par site
  • Format des dates : Les dates doivent ĂȘtre en ISO8601 (ex. « 2023-06-01T08:00:00-04:00 »)
  • Association des transporteurs : Confirmez l’exactitude du numĂ©ro de sociĂ©tĂ©
  • Types de champs personnalisĂ©s : Les champs JSON sont prĂ©servĂ©s, le reste converti en texte
  • Vider les articles : Utilisez clear_po_items pour remplacer tous les articles

Gestion des erreurs​

CodeDescriptionCause possible
400RequĂȘte invalideValeur ou format invalide
404IntrouvableL’ID du bon n’existe pas
422Entité non traitableValidation échouée (ex. : champ requis manquant)
401Non autoriséJeton API invalide ou manquant
403InterditPermissions insuffisantes

Exemple de rĂ©ponse d’erreur​

{
  "errors": {
    "po_number": ["ne peut ĂȘtre vide"],
    "purchase_order_items": ["doit avoir au moins un article"]
  }
}

Aide et support​

Si vous avez des difficultĂ©s non couvertes ci-dessus :

  1. Consultez la rĂ©ponse d’erreur : La plupart des erreurs API sont prĂ©cises
  2. VĂ©rifiez les permissions : Votre jeton API a-t-il les droits suffisants ?
  3. ProcĂ©dez par Ă©tapes : DĂ©composez les opĂ©rations complexes pour cibler l’origine du problĂšme