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 les accords concernant la livraison de produits Ă  vos entrepĂŽts (entrants) ou leur expĂ©dition depuis ceux-ci (sortants). L’API des bons de commande vous permet de crĂ©er, suivre et gĂ©rer ces documents essentiels de maniĂšre programmatique, reliant ainsi vos systĂšmes de chaĂźne d’approvisionnement directement Ă  vos opĂ©rations d’entrepĂŽt.

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

  • Rationalisation du traitement des commandes : CrĂ©ez et mettez Ă  jour automatiquement les bons de commande Ă  partir de votre systĂšme ERP ou de gestion des commandes
  • AmĂ©lioration de la visibilitĂ© des stocks : Suivez les arrivĂ©es et dĂ©parts prĂ©vus avec des informations dĂ©taillĂ©es sur les produits
  • Simplification de la gestion des transporteurs : Associez des transporteurs aux bons de commande pour simplifier la logistique
  • Optimisation de la planification : DĂ©finissez des Ă©chĂ©anciers pour mieux gĂ©rer les ressources d’entrepĂŽt
  • Analyse avancĂ©e : AccĂ©dez Ă  des donnĂ©es structurĂ©es sur les bons de commande, Ă  des fins de reporting et d’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 basique 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 tout! Votre bon de commande est maintenant dans DataDocks. VĂ©rifiez votre tableau de bord pour le voir.

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

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Your System    │──────▶│  DataDocks API  │──────▶│  Warehouse Ops  │
│  (ERP/OMS/TMS)  │◀───────   (REST/JSON)   │◀───────  (POs/Items)    │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  â–Č
                                  │  │
                                  â–Œ  │
                           ┌─────────────────┐
                           │  Appointments   │
                           │  & Scheduling   │
                           │                 │
                           └─────────────────┘

Authentification​

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

Authorization: Token YOUR_API_TOKEN

Lister les bons de commande​

Objectif​

RĂ©cupĂšre une liste paginĂ©e de bons de commande avec possibilitĂ© de filtrer par numĂ©ro de BC. Utilisez cet endpoint pour synchroniser les bons de commande avec vos systĂšmes, vĂ©rifier le statut des livraisons prĂ©vues ou prĂ©parer des rapports sur l’activitĂ© de l’entrepĂŽt.

Cas d’utilisation mĂ©tiers​

  • 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 prĂ©vus
  • Surveiller les livraisons ou expĂ©ditions Ă  venir
  • Suivre la performance des transporteurs sur les bons de commande

RequĂȘte HTTP​

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

ParamĂštres de requĂȘte​

ParamĂštreTypeObligatoireDescriptionExemple
pageIntegerNonNuméro de page pour la pagination (1 par défaut)page=2
po_numberStringNonFiltrer par numéro exact de bon de commande (non sensible à 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
idIntegerIdentifiant unique du bon de commande
po_numberStringNuméro du bon de commande
nameStringNom auto-généré à partir des informations du BC
carrier_nameStringNom du transporteur assigné au bon de commande
location_nameStringNom de l’emplacement d’entrepît
outboundBooleanCommande sortante (true) ou entrante (false)
expected_starts_atStringHorodatage ISO8601 du début prévu
expected_ends_atStringHorodatage ISO8601 de fin prévu
custom_valuesObjectPaires clé/valeur des champs personnalisés
purchase_order_itemsArrayListe des articles associés à ce bon de commande

Chaque article dans purchase_order_items contient :

ChampTypeDescription
idIntegerIdentifiant unique de l’article
customer_nameStringNom du client associĂ© Ă  l’article
product_nameStringNom du produit
unit_nameStringUnité de mesure (ex. : « Palette », « Boßte »)
quantityNumberQuantité du produit
weightNumberPoids de l’article
custom_valuesObjectPaires clĂ©/valeur des champs personnalisĂ©s de l’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

# Filtrage par numéro de BC
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 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 lors de la 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​

Obtenez les informations dĂ©taillĂ©es d’un bon de commande spĂ©cifique par son identifiant. Utilisez cet endpoint si vous avez besoin des donnĂ©es complĂštes sur une commande prĂ©cise, y compris tous ses articles et champs personnalisĂ©s.

Cas d’utilisation mĂ©tiers​

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

RequĂȘte HTTP​

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

Paramùtres d’URL​

ParamĂštreTypeObligatoireDescription
idIntegerOuiIdentifiant unique du bon de commande

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne une rĂ©ponse 200 OK avec l’objet complet du bon de commande, dans le mĂȘme format que pour 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 lors de la 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 nouveau bon de commande dans DataDocks. Cet endpoint vous permet d’ajouter de nouveaux bons de commande et leurs articles de maniĂšre programmatique, intĂ©grant directement votre systĂšme de gestion des commandes Ă  vos opĂ©rations d’entrepĂŽt.

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

┌─────────────────┐
│ Ajouter un bon  │
│ de commande ?   │
└────────┬────────┘
         │
         ▌
┌─────────────────┐     Oui     ┌─────────────────┐
│  IntĂ©gration    │────────────▶│   Parfait pour  │
│  ERP/commande ? │             │   l’API !       │
└────────┬────────┘             └─────────────────┘
         │ Non
         ▌
┌─────────────────┐     Oui     ┌─────────────────┐
│CrĂ©ation BC en   │────────────▶│ Importation en  │
│masse à faire ?  │             │    vrac         │
└────────┬────────┘             └─────────────────┘
         │ Non
         ▌
┌─────────────────┐
│  Utilisez       │
│  l’interface    │
│  web            │
└─────────────────┘

Cas d’utilisation mĂ©tiers​

  • IntĂ©gration systĂšme : CrĂ©ez des BC directement Ă  partir de votre ERP ou votre systĂšme de gestion de commandes
  • Automatisation du traitement : Convertissez des commandes de vente en BC de maniĂšre automatique
  • IntĂ©gration EDI : Transformez les documents EDI 850 en BC DataDocks
  • IntĂ©gration fournisseur : Permettez aux fournisseurs de soumettre des BC via vos systĂšmes

RequĂȘte HTTP​

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

Corps de la requĂȘte​

ParamĂštreTypeObligatoireDescriptionContraintesDĂ©fautExemple
po_numberStringOuiNumĂ©ro du bon de commandeDoit ĂȘtre uniqueAucun"PO-2023-001"
carrier_nameStringNon *Nom du transporteurAucunAucun"Express Logistics"
carrier_numberStringNonNuméro de société du transporteurDoit existerAucun"EXP-001"
location_nameStringNonNom de l’emplacementDoit existerEmplacement actuel"Toronto Warehouse"
outboundBooleanNonCommande sortanteAucunfalsetrue
expected_starts_atStringNonHorodatage ISO8601 de début prévuFormat ISO8601 valideAucun"2023-06-01T08:00:00-04:00"
expected_ends_atStringNonHorodatage ISO8601 de fin prévueFormat ISO8601 valideAucun"2023-06-01T16:00:00-04:00"
alternate_reference_numberStringNonRéférence alternativeAucunAucun"REF-123"
closedBooleanNonLe BC est-il fermé ?Aucunfalsetrue
custom_valuesObjectNon *Valeurs des champs personnalisĂ©sSelon l’emplacement{}{"department": "Produce"}
purchase_order_itemsArrayNonArticles/options du BCAu moins un recommandé[]Voir ci-dessous

Chaque article dans purchase_order_items peut inclure :

ParamĂštreTypeObligatoireDescriptionContraintesExemple
customer_nameStringNon *Nom du clientAucun"Acme Corp"
customer_numberStringNon *Numéro de société du clientDoit exister"ACME-001"
product_nameStringNon *Nom du produitAucun"Widgets"
unit_nameStringNon *Unité de mesureAucun"Pallet"
quantityNumberNon *QuantitĂ© du produitDoit ĂȘtre positive10
weightNumberNon *Poids de l’articleDoit ĂȘtre positif500
custom_valuesObjectNon *Champs personnalisĂ©s de l’articleSelon l’emplacement{"color": "Blue"}

* Champs susceptibles d’ĂȘtre requis selon la configuration de l’emplacement

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne une rĂ©ponse 200 OK avec l’objet complet du bon de commande, incluant l’id gĂ©nĂ©rĂ© et les 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 lors de la 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​

Met Ă  jour les dĂ©tails d’un bon de commande existant. Cet endpoint vous permet de modifier n’importe quel aspect d’un BC, y compris ses articles, dates, informations sur le transporteur et champs personnalisĂ©s.

Cas d’utilisation mĂ©tiers​

  • Mise Ă  jour des donnĂ©es : Modifiez les dates de livraison ou les informations sur le transporteur
  • Modifier le contenu d’un BC : Ajoutez, supprimez ou modifiez les articles selon les besoins
  • Changer le statut : Marquez un BC comme fermĂ© lorsqu’il est complĂ©tĂ©
  • Ajouter des informations de suivi : Mettez Ă  jour les champs personnalisĂ©s avec des donnĂ©es de suivi ou de livraison

RequĂȘte HTTP​

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

Paramùtres d’URL​

ParamĂštreTypeObligatoireDescription
idIntegerOuiIdentifiant unique du bon de commande

Corps de la requĂȘte​

Le corps de la requĂȘte accepte les mĂȘmes paramĂštres que la crĂ©ation. Seuls les champs Ă  modifier doivent ĂȘtre inclus.

ScĂ©narios de mise Ă  jour courants​

Mise à jour des dates​

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

Changement de transporteur​

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

Fermeture d’un bon de commande​

{
  "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 lors de la 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
  }
}

Suppression de tous les articles​

Si vous devez supprimer tous les articles d’un bon de commande, incluez le paramùtre clear_po_items à la valeur true :

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

Ceci supprimera tous les articles existants et les remplacera par ceux fournis (le cas échéant).

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

Objectif​

RĂ©cupĂ©rez les bons de commande qui sont associĂ©s Ă  des rendez-vous rĂ©servĂ©s, ainsi que le dĂ©tail de leurs rendez-vous. Cet endpoint est destinĂ© aux clients qui prĂ©fĂšrent l’interrogation rĂ©guliĂšre (polling) aux webhooks pour surveiller la rĂ©servation et l’évolution des rendez-vous.

Cas d’utilisation mĂ©tiers​

  • Alternatif aux webhooks : Surveillez la rĂ©servation de rendez-vous sans infrastructure webhook
  • Suivi de statut de rendez-vous : VĂ©rifiez quels bons de commande sont rĂ©servĂ©s avec succĂšs
  • Synchronisation incrĂ©mentale : Utilisez updated_since pour ne rĂ©cupĂ©rer que les donnĂ©es modifiĂ©es
  • Suivi des livraisons planifiĂ©es : Surveillez quand les bons de commande sont vĂ©ritablement prĂ©vus
  • Reporting par site : Surveillez l’activitĂ© de rendez-vous sur vos emplacements

RequĂȘte HTTP​

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

ParamĂštres de requĂȘte​

ParamĂštreTypeObligatoireDescriptionExemple
start_timeStringNonHorodatage ISO8601 - retour Ă  partir de ce momentstart_time=2023-06-01T08:00:00-04:00
end_timeStringNonHorodatage ISO8601 - retour jusqu’à ce momentend_time=2023-06-30T17:00:00-04:00
limitIntegerNonNombre max. de résultats (défaut : 100, max : 250)limit=50
offsetIntegerNonNombre de résultats à ignorer (défaut : 0)offset=100
updated_sinceStringNonHorodatage ISO8601 - retour des BC créés/modifiés depuisupdated_since=2023-06-01T00:00:00-04:00

Format de la rĂ©ponse​

La rĂ©ponse contient un tableau d’objets bon de commande, chacun ayant au moins un rendez-vous rĂ©servĂ©. Chaque objet inclut :

ChampTypeDescription
po_numberStringNuméro du bon de commande
appointmentsArrayListe des rendez-vous associés à ce BC

Chaque rendez-vous dans le tableau appointments comprend :

ChampTypeDescription
appointment_idStringIdentifiant unique du rendez-vous
appointment_numberStringNuméro lisible du rendez-vous
scheduled_atStringHorodatage ISO8601 de planification
locationStringNom de l’emplacement du rendez-vous

À noter​

  • RĂ©sultats filtrĂ©s : Seuls les BC ayant au moins un rendez-vous rĂ©servĂ© sont retournĂ©s
  • DonnĂ©es en temps rĂ©el : Les rĂ©sultats reflĂštent le statut actuel
  • Fuseau horaire : Tous les horodatages sont dans le fuseau de l’emplacement
  • Pagination : Utilisez limit et offset pour gĂ©rer de grands jeux de 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 filtrage temporel 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 depuis la derniÚre mise à jour
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()

  // Ajoute les 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 lors de la 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
  }
}

// Exemple d’utilisation pour une synchronisation incrĂ©mentale
const syncAppointments = async (lastSyncTime) => {
  const data = await getPurchaseOrdersWithAppointments({
    updatedSince: lastSyncTime,
    limit: 100,
  })

  // Traitez les 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​

Supprimer un bon de commande du systĂšme. Cet endpoint vous permet de supprimer des BC devenus inutiles.

Points importants​

Avant de supprimer un bon de commande, considérez :

  • Un BC ne doit ĂȘtre associĂ© Ă  aucun rendez-vous actif
  • La suppression est dĂ©finitive et irrĂ©versible
  • Dans bien des cas, il est prĂ©fĂ©rable de marquer le BC comme fermĂ© plutĂŽt que de le supprimer

Cas d’utilisation mĂ©tiers​

  • Nettoyer les donnĂ©es tests : Supprimez des BC de test ou fictifs
  • Supprimer les doublons : Nettoyez la base aprĂšs dĂ©duplication
  • Maintenance du systĂšme : Supprimez les bons de commande obsolĂštes

RequĂȘte HTTP​

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

Paramùtres d’URL​

ParamĂštreTypeObligatoireDescription
idIntegerOuiIdentifiant unique du bon de commande

RĂ©ponse​

Une requĂȘte rĂ©ussie retourne une rĂ©ponse 204 No Content, indiquant que le bon de commande 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/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 lors de la suppression du bon de commande : ${JSON.stringify(errorData)}`)
    }

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

RĂ©solution automatique des entitĂ©s​

Appariement du 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 retrouver un transporteur correspondant avec ce numĂ©ro
  • S’il y a correspondance, le nom et l’ID du transporteur seront associĂ©s automatiquement au bon de commande
  • Sinon, le systĂšme utilisera le numĂ©ro fourni comme nom de transporteur

Appariement du produit​

Pour les articles des bons de commande :

  • Si le nom du produit correspond Ă  un produit existant (non sensible Ă  la casse), il sera utilisĂ©
  • Sinon, l’article sera crĂ©Ă© sans liaison Ă  un produit enregistrĂ©
  • Contactez le support si vous devez crĂ©er un produit inexistant

Appariement de l’unité​

MĂȘme principe :

  • Si le nom de l’unitĂ© correspond Ă  une unitĂ© connue (non sensible Ă  la casse), elle sera utilisĂ©e
  • Sinon, l’article n’aura pas d’unitĂ© associĂ©e proprement
  • Contactez le support si vous devez crĂ©er une unitĂ© absente

Bonnes pratiques​

Gestion des donnĂ©es​

  • Utiliser des numĂ©ros de BC uniques : chaque BC doit avoir un identifiant propre
  • Fournir le numĂ©ro du transporteur : lorsque c’est possible, pour l’association correcte
  • Valider cĂŽtĂ© client : vĂ©rifiez la validitĂ© des donnĂ©es avant envoi
  • Utiliser le drapeau "fermĂ©" : privilĂ©giez la fermeture Ă  la suppression dĂ©finitive
  • GĂ©rer correctement les champs personnalisĂ©s : n’utilisez que ceux prĂ©vus pour votre site

Optimisation des performances​

  • Inclure toutes les donnĂ©es pertinentes : dans la mesure du possible, regroupez les informations en un seul appel
  • Faire des opĂ©rations par lot : regroupez les modifications liĂ©es
  • Filtrer prĂ©cisĂ©ment les requĂȘtes : utilisez les filtres disponibles pour limiter la charge

Erreurs courantes et dĂ©pannage​

  • UnicitĂ© du numĂ©ro de BC : chaque numĂ©ro doit ĂȘtre unique dans un emplacement
  • Format de date : doit respecter ISO8601 (ex. "2023-06-01T08:00:00-04:00")
  • Association transporteur : utilisez bien le numĂ©ro de sociĂ©tĂ© du transporteur
  • Types de champs personnalisĂ©s : Les champs JSON sont conservĂ©s tels quels ; les autres convertis en chaĂźne de caractĂšres
  • Effacement des articles : pour remplacer intĂ©gralement, utilisez le paramĂštre clear_po_items

Gestion des erreurs​

Code d’erreurDescriptionCause possible
400RequĂȘte invalideValeurs ou format non valides
404IntrouvableL’ID du BC n’existe pas
422Entité non traitableValidation échouée (ex. : champ requis absent)
401Non autoriséJeton API invalide ou absent
403InterditPermissions insuffisantes

Exemple de rĂ©ponse d’erreur​

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

Aide et support​

En cas de problÚme non couvert par cette documentation :

  1. Consultez la rĂ©ponse d’erreur : La plupart des erreurs API incluent une explication dĂ©taillĂ©e
  2. Vérifiez vos droits : Assurez-vous que votre jeton API a les bonnes permissions
  3. Testez étape par étape : Décomposez les opérations complexes pour isoler le problÚme