Commandes d’achat de l’API Organisation

Pourquoi utiliser l’API des bons de commande ?

Créez et gérez vos bons de commande pour tous vos entrepôts via une seule intégration. Vous pouvez attribuer une commande à un entrepôt lors de sa création ou la laisser non attribuée jusqu’à ce que vous sachiez où elle sera traitée.

Synchronisez les commandes depuis votre ERP — Créez des bons de commande et des lignes d’articles directement à partir de votre système de commande.
Attribuez les entrepôts plus tard — Importez les commandes avant de choisir le lieu de réception ou d’expédition.
Suivez les commandes planifiées — Récupérez les bons de commande qui ont des rendez-vous réservés.

Utilisez le sous-domaine de votre organisation dans chaque requête, tel que acme.datadocks.com. Votre utilisateur API doit avoir accès aux emplacements souhaités. Consultez Authentification et accès pour les détails de configuration.

Démarrage rapide en 5 minutes

Créez un bon de commande pour votre entrepôt de Toronto :

Obtenez votre jeton API et le sous-domaine de l’organisation auprès du support DataDocks.
Confirmez le nom de l’entrepôt à l’aide de la section Lister les emplacements.
Envoyez la requête suivante, en remplaçant les valeurs d’exemple par les détails de votre commande.

Voir l’exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2026-001",
         "location_name": "Toronto",
         "expected_starts_at": "2026-10-01T09:00:00-04:00",
         "purchase_order_items": [
           {
             "product_name": "Widgets",
             "quantity": 10
           }
         ]
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders

Une requête réussie retourne 200 OK avec les détails du bon de commande. Sauvegardez son id pour récupérer ou mettre à jour la commande ultérieurement. Les paramètres de votre entrepôt peuvent exiger des champs supplémentaires.

Lister les bons de commande

Objectif

Récupérez les commandes sur tous les emplacements auxquels votre utilisateur API a accès, ou filtrez la liste à un entrepôt. Les commandes non attribuées sont incluses dans les deux cas.

Requête HTTP

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

Paramètres de requête

Paramètre	Type	Obligatoire	Description	Exemple
`location_name`	String	Non	Inclure les commandes de cet emplacement et les non attribuées	`Toronto`
`po_number`	String	Non	Filtrer par numéro de bon de commande	`PO-2026-001`
`page`	Integer	Non	Numéro de page	`2`

Sans location_name, la liste inclut les commandes pour tous les emplacements accessibles par votre utilisateur API, plus les commandes non attribuées de votre organisation.

Exemples de code

Voir les exemples cURL

# Lister les commandes sur tous les emplacements accessibles
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://acme.datadocks.com/api/v1/purchase_orders

# Lister les commandes de Toronto et les commandes non attribuées
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/purchase_orders?location_name=Toronto"

Format de la réponse

Une requête réussie retourne 200 OK avec un tableau de bons de commande. Consultez la section API Bons de commande pour le détail complet des champs de réponse. Utilisez l’en-tête Link de la réponse pour récupérer les pages supplémentaires.

Visualiser une commande individuelle

Ajoutez l’ID de la commande à l’URL :

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

Vous pouvez inclure ?location_name=Toronto pour rechercher la commande à cet emplacement ou parmi les commandes non attribuées. Une commande en dehors des emplacements auxquels vous avez accès retourne 404 Not Found.

Création d’un bon de commande

Requête HTTP

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

Corps de la requête

Envoyez les champs de la commande à l’intérieur d’un objet purchase_order.

Paramètre	Type	Obligatoire	Description	Exemple
`po_number`	String	Oui	Numéro du bon de commande	`PO-2026-001`
`location_name`	String	Non	Entrepôt à assigner ; omettre pour créer une commande non attribuée	`Toronto`
`expected_starts_at`	String	Non	Heure de début prévue ; inclure un décalage UTC si possible	`2026-10-01T09:00:00-04:00`
`expected_ends_at`	String	Non	Heure de fin prévue	`2026-10-01T17:00:00-04:00`
`purchase_order_items`	Array	Non	Lignes de commande	Voir l’exemple ci-dessous
`custom_values`	Object	Non	Valeurs de vos champs personnalisés configurés	`{"department":"Produce"}`

D’autres champs, dont les informations sur le transporteur, numéros de référence et attributs de lignes, sont décrits dans la documentation API Bons de commande. Les champs requis dépendent des paramètres de votre entrepôt.

Exemple de code : Créer une commande non attribuée

Omettre location_name si l’entrepôt n’est pas encore connu :

Voir l’exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "purchase_order": {
         "po_number": "PO-2026-002",
         "expected_starts_at": "2026-10-01T13:00:00Z",
         "purchase_order_items": [
           {
             "customer_name": "Acme Retail",
             "product_name": "Widgets",
             "quantity": 10
           }
         ]
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders

Réponse

Une requête réussie retourne 200 OK avec le nouveau bon, incluant son id. La commande demeure non attribuée jusqu’à ce que vous fournissiez un emplacement lors d’une mise à jour.

Mise à jour d’un bon de commande

Requête HTTP

PATCH https://[organization_subdomain].datadocks.com/api/v1/purchase_orders/[id]

PUT est également supporté. Incluez les champs à mettre à jour dans l’objet purchase_order. Pour la liste complète des champs modifiables, consultez la documentation API Bons de commande.

Modification de l’emplacement d’un bon de commande

Incluez location_name dans le corps de la requête pour assigner, déplacer ou désattribuer une commande :

`location_name` dans le corps	Résultat
Omission	Garde l’emplacement actuel
Un nom d’emplacement connu	Assigne ou déplace la commande à cet emplacement
`null`, chaîne vide ou espaces	Retire l’attribution d’emplacement
Nom inconnu	Retourne `404` ; garde l’emplacement actuel

Votre utilisateur API doit avoir la permission de modification à la fois sur l’emplacement actuel de la commande et sur l’emplacement de destination. Les commandes non attribuées exigent seulement l’accès sur la destination. Sélectionner une destination sans y avoir accès retourne 403 Forbidden.

Exemples de code

Voir les exemples cURL : assigner ou désattribuer une commande

# Assigner une commande à Vancouver
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{
       "purchase_order": {
         "location_name": "Vancouver"
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders/123

# Retirer l’attribution d’emplacement
curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PATCH \
     -d '{
       "purchase_order": {
         "location_name": null
       }
     }' \
     https://acme.datadocks.com/api/v1/purchase_orders/123

Une mise à jour réussie retourne 200 OK avec la commande mise à jour.

Utilisez le corps de la requête pour changer l’emplacement. Un emplacement dans l’URL limite les commandes trouvées, mais ne les réattribue pas. Pour déplacer une commande, indiquez la destination dans le corps et n’incluez pas location_name dans l’URL. Indiquer des noms différents dans l’URL et le corps retourne 400 Bad Request.

Lors de la mise à jour des lignes d’articles, utilisez les identifiants (id) de la commande concernée. Les lignes d’articles n’acceptent pas leur propre location_name.

Dates et fuseaux horaires

Incluez un décalage UTC, comme -04:00, ou utilisez Z pour UTC lors de l’envoi d’horodatages.

Requête	Comment les heures sans décalage sont interprétées
Création/mise à jour d’une commande attribuée	Utilise le fuseau de l’entrepôt assigné
Création d’une commande non attribuée ou retrait de l’attribution	Utilise l’UTC
Filtres de temps dans une collection	Utilise le fuseau de l’emplacement en requête, sinon UTC

La mise à jour d’une commande attribuée sans location_name conserve son entrepôt et utilise son fuseau horaire. Déplacer une commande utilise le fuseau horaire de destination ; retirer l’attribution utilise UTC. Les décalages explicites dans les horodatages ont toujours priorité.

Les dates retournées, y compris la création/mise à jour des commandes/lignes, utilisent le fuseau horaire assigné ou UTC si non attribué. Les rendez-vous réservés utilisent leurs propres fuseaux. Un emplacement en requête ne modifie jamais la sortie UTC d’une commande non attribuée. earliest_assignment_date suit aussi cette règle.

Produits et clients

Produits

Les noms de produits sont enregistrés comme texte, sans création ou attribution d’entités produit. Les commandes attribuées appliquent tout de même la validation des noms de produits et les paramètres de l’entrepôt, y compris lors de mises à jour sans sélecteur d’emplacement.

Clients

Les noms de clients sont comparés aux entreprises existantes dans votre organisation. Si aucune entreprise ne correspond, un nouveau client peut être créé si votre utilisateur API en a l’autorisation.

Pour les commandes non attribuées, de nouveaux noms de clients sont permis et la nouvelle entreprise aura ces paramètres par défaut :

Paramètre	Valeur par défaut
Approbation automatique des rendez-vous (`auto_approve_appointments`)	`false`
Autoriser le client à créer des transporteurs (`can_create_carriers`)	`false`

Les commandes attribuées utilisent les réglages de l’entrepôt pour la création de clients, même lors d’une mise à jour sans sélecteur. Le déplacement d’une commande utilise les paramètres de destination ; le retrait de l’attribution utilise les paramètres par défaut des commandes non attribuées.

Champs personnalisés

Envoyez les valeurs des champs personnalisés dans custom_values sur le bon de commande ou dans ses lignes.

Avec un sélecteur location_name explicite : Utilisez les champs activés à l’entrepôt sélectionné.
Sans sélecteur : Utilisez les champs activés à n’importe quel emplacement de votre organisation, y compris les emplacements non payés ou non accessibles par votre utilisateur API. Ceci s’applique également si vous mettez à jour une commande déjà attribuée.

Les champs JSON acceptent les objets et tableaux. Les autres valeurs sont enregistrées comme texte et doivent respecter les règles de validation configurées.

Un nom de champ inconnu retourne 422 Unprocessable Entity. Si un même nom de champ a des types différents selon l’emplacement, fournissez location_name ou rendez les types des champs cohérents avant soumission.

Recherche des commandes ayant un rendez-vous réservé

Objectif

Vérifiez quels bons de commande ont été planifiés. Utilisez ce point de terminaison pour mettre à jour le statut d’expédition dans votre ERP ou TMS.

Requête HTTP

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

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`location_name`	String	Non	Limiter les commandes à un emplacement accessible et aux commandes non attribuées
`start_time`	String	Non	Inclure les commandes avec un rendez-vous accessible commençant à ou après cette date
`end_time`	String	Non	Inclure les commandes avec un rendez-vous accessible commençant à ou avant cette date
`updated_since`	String	Non	Inclure les commandes créées ou mises à jour depuis cette date
`limit`	Integer	Non	Nombre de résultats par requête ; par défaut `100`, maximum `250`
`offset`	Integer	Non	Nombre de résultats à ignorer ; par défaut `0`

Exemple de code

Voir l’exemple cURL

curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://acme.datadocks.com/api/v1/purchase_orders/with_booked_appointments?location_name=Toronto&limit=100&offset=0"

La réponse inclut les bons et seulement les rendez-vous dans les emplacements accessibles à votre utilisateur API. Les rendez-vous inaccessibles n’affectent pas le filtrage temporel et ne font pas apparaître une commande. Consultez la documentation API Bons de commande pour le format de réponse complet.

Opérations supplémentaires

Opération	Méthode	Chemin
Supprimer une commande	`DELETE`	`/api/v1/purchase_orders/123`

Cette route accepte un location_name optionnel dans l’URL et applique les mêmes règles d’accès que les autres requêtes de bon de commande. Une suppression réussie retourne 204 No Content.

Traitement des erreurs

Code d’erreur	Cause possible	À vérifier
`400`	Différents noms d’emplacement dans l’URL et le corps	Indiquez la destination dans le corps lors d’un transfert
`403`	Aucun accès à l’entrepôt sélectionné	Vérifiez l’accès de votre utilisateur API avec le support
`404`	Emplacement inconnu, commande manquante, ou commande hors de vos accès	Vérifiez le nom d’emplacement et l’ID du bon de commande
`422`	Bon de commande, ligne ou champ personnalisé invalide	Vérifiez les `errors` dans la réponse et corrigez-les

Consultez le guide de l’API Organisation pour les erreurs d’authentification, de paiement et de limitation de débit.

Aide et support

Si vous avez besoin d’aide avec votre intégration, contactez support@datadocks.com avec l’URL de la requête, l’ID du bon de commande et la réponse d’erreur. N’incluez jamais votre jeton API dans le message.

Pourquoi utiliser l’API des bons de commande ?​

Démarrage rapide en 5 minutes​

Lister les bons de commande​

Objectif​

Requête HTTP​

Paramètres de requête​

Exemples de code​

Format de la réponse​

Visualiser une commande individuelle​

Création d’un bon de commande​

Requête HTTP​

Corps de la requête​

Exemple de code : Créer une commande non attribuée​

Réponse​

Mise à jour d’un bon de commande​

Requête HTTP​

Modification de l’emplacement d’un bon de commande​

Exemples de code​

Dates et fuseaux horaires​

Produits et clients​

Produits​

Clients​

Champs personnalisés​

Recherche des commandes ayant un rendez-vous réservé​

Objectif​

Requête HTTP​

Paramètres de requête​

Exemple de code​

Opérations supplémentaires​

Traitement des erreurs​

Aide et support​

Pourquoi utiliser l’API des bons de commande ?

Démarrage rapide en 5 minutes

Lister les bons de commande

Objectif

Requête HTTP

Paramètres de requête

Exemples de code

Format de la réponse

Visualiser une commande individuelle

Création d’un bon de commande

Requête HTTP

Corps de la requête

Exemple de code : Créer une commande non attribuée

Réponse

Mise à jour d’un bon de commande

Requête HTTP

Modification de l’emplacement d’un bon de commande

Exemples de code

Dates et fuseaux horaires

Produits et clients

Produits

Clients

Champs personnalisés

Recherche des commandes ayant un rendez-vous réservé

Objectif

Requête HTTP

Paramètres de requête

Exemple de code

Opérations supplémentaires

Traitement des erreurs

Aide et support