API d’Organisation

Pourquoi utiliser l’API d’Organisation?

Connectez votre ERP, TMS ou WMS à plusieurs emplacements DataDocks via une seule URL d’organisation. Listez les enregistrements sur vos entrepôts accessibles, ou consultez et mettez à jour un enregistrement par identifiant sans indiquer le nom de l’entrepôt.

Gérez plusieurs entrepôts — Utilisez une seule URL de base pour les rendez-vous, les produits et les bons de commande sur tous vos sites.
Découvrez les emplacements disponibles — Récupérez la liste des emplacements auxquels votre utilisateur API peut accéder.
Créez des commandes avant d’assigner un entrepôt — Ajoutez un bon de commande maintenant et attribuez son emplacement plus tard.

Pour une organisation nommée Acme, l’URL de base est :

https://acme.datadocks.com/api/v1

Vous pouvez continuer d'utiliser l’API par emplacement à des URL comme https://toronto-acme.datadocks.com/api/v1.

Démarrage rapide en 5 minutes

Voici comment récupérer les produits dans un de vos entrepôts :

Obtenez votre jeton API

Contactez support@datadocks.com avec le nom de votre organisation et la liste des sites auxquels vous souhaitez accéder. Si vous avez déjà un jeton API, vous pouvez l’utiliser avec l’API d’organisation.
Trouvez vos emplacements

Voir exemple cURL

curl -H "Authorization: Token VOTRE_JETON_API" \
     https://acme.datadocks.com/api/v1/locations

Une réponse réussie retourne les emplacements disponibles :

[
  { "name": "Toronto", "url": "toronto-acme" },
  { "name": "Vancouver", "url": "vancouver-acme" }
]

Obtenez les produits d’un emplacement

Utilisez un name de la réponse comme location_name :

Voir exemple cURL

curl -H "Authorization: Token VOTRE_JETON_API" \
     "https://acme.datadocks.com/api/v1/products?location_name=Toronto"

Une requête réussie retourne un 200 OK avec les produits de l’emplacement. Voir Ressources de l’API d’Organisation pour des exemples de rendez-vous, produits, entreprises et limites produit.

Authentification et accès

Incluez votre jeton API dans chaque requête :

Authorization: Token VOTRE_JETON_API

Votre utilisateur API doit avoir :

Un accès administrateur à un emplacement de l’organisation.
Un accès à chaque emplacement sur lequel vous souhaitez agir, avec une permission pour l’action demandée.

Par exemple, un administrateur à Toronto doit également avoir accès à Vancouver pour gérer les rendez-vous de Vancouver. Si son rôle pour Vancouver est lecture seule, il peut consulter les rendez-vous mais ne peut pas les créer ou les modifier.

Contactez le support si vous devez ajouter un autre emplacement à votre intégration.

Au moins un emplacement dans votre organisation doit avoir un abonnement payant. Une fois cette exigence satisfaite, vous pouvez utiliser l’API d’organisation pour tout site auquel votre utilisateur API peut accéder, y compris les emplacements non payants.

Choisir un emplacement

Utilisez le nom d’affichage de l’emplacement affiché par GET /locations, comme Toronto. Les noms ne tiennent pas compte de la casse, et les espaces au début ou à la fin sont ignorés. Si un emplacement est renommé, mettez à jour le nom dans votre intégration.

Ressource	`location_name` requis ?	Plus d’information
Rendez-vous	Uniquement pour la création	Rendez-vous
Produits	Uniquement pour la création	Produits
Entreprises	Non	Entreprises
Limites produit	Non	Limites produit
Emplacements	Non	Liste des emplacements
Bons de commande	Non	Bons de commande

Lecture ou suppression d’enregistrements

Omettez location_name pour lister les enregistrements sur tous les emplacements accessibles. Les actions de consultation, modification et suppression (là où c’est pris en charge) déduisent l’emplacement à partir de l’ID de l’enregistrement. Ajoutez location_name pour limiter la recherche ; un ID hors de ce filtre retourne une 404. Utilisez --data-urlencode pour les noms contenant des espaces :

curl -G -H "Authorization: Token VOTRE_JETON_API" \
     --data-urlencode "location_name=Entrepôt Toronto" \
     https://acme.datadocks.com/api/v1/products

Création ou modification d’enregistrements

La création d’un rendez-vous ou d’un produit exige un location_name dans l’enregistrement ou dans l’URL. Les modifications déduisent l’emplacement existant et n’en nécessitent pas. Les entreprises ne requièrent jamais d’emplacement. Par exemple, pour créer un produit :

{
  "product": {
    "location_name": "Toronto",
    "name": "Premium Widget",
    "sku": "WIDGET-001"
  }
}

Vous pouvez également transmettre l’emplacement dans l’URL. Si vous l’indiquez aux deux endroits, les noms doivent correspondre. Les listes d’emballage et les items de bon de commande utilisent l’emplacement de la requête principale.

Changer le location_name ne déplace pas un rendez-vous ou un produit vers un autre entrepôt. Les bons de commande permettent de changer leur emplacement assigné.

Noms des emplacements dans les réponses

Ressource	Champ de l’emplacement
Rendez-vous	`location_name`; `location` demeure en alias de compatibilité
Produits et limites de produit	`location_name`
Bons de commande	`location_name`, ou `null` s’il n’est pas attribué
Emplacements	`name`
Entreprises	Aucun ; les entreprises appartiennent à l’organisation

Les listes d’emballage et les items de bons de commande héritent de l’emplacement parent. Les rendez-vous imbriqués comprennent leur propre location_name et l’alias de compatibilité location. Utilisez location_name pour toute nouvelle intégration.

Estampilles temporelles et fuseaux horaires

Chaque date-heure retournée utilise la norme ISO 8601 avec un décalage UTC, y compris pour created_at, updated_at et les dates imbriquées. Chaque entité utilise le fuseau horaire de son entrepôt au moment donné. Une entité sans emplacement utilise l’UTC. Un filtre d’emplacement ne modifie pas cette règle.

Une liste de rendez-vous sur plusieurs emplacements peut inclure :

[
  { "id": 123, "location": "Toronto", "scheduled_at": "2026-10-01T12:00:00-04:00" },
  { "id": 456, "location": "Vancouver", "scheduled_at": "2026-10-01T09:00:00-07:00" }
]

Ces dates représentent le même instant. Les décalages tiennent compte de l’heure avancée. Les listes d’emballage et les items de commandes héritent de l’emplacement parent ; les rendez-vous imbriqués emploient leur propre emplacement. Les horaires absents restent à null.

Incluez un décalage dans vos dates lors de la saisie si possible. Sinon, lors de la création ou la modification, l’opération utilisera le fuseau horaire de l’emplacement de l’entité, ou l’UTC si non assigné. Les filtres de période pour les listes se servent du filtre d’emplacement (optionnel), ou de l’UTC pour des recherches tous emplacements. Un filtre de période invalide retourne 400.

Les champs de date seuls conservent le format AAAA-MM-JJ. Les heures de début/fin récurrentes pour les limites produit restent des horaires locaux sans date. Les valeurs arbitraires JSON et textes gardent leur signification.

Pagination

Utilisez le paramètre page pour consulter des résultats supplémentaires dans les rendez-vous, produits, entreprises, bons de commande et limites produit :

curl -H "Authorization: Token VOTRE_JETON_API" \
     "https://acme.datadocks.com/api/v1/products?location_name=Toronto&page=2"

Les en-têtes de réponse incluent Current-Page, Page-Items, Total-Pages, Total-Count et Link. Suivez les URL du champ Link pour naviguer entre les pages ; elles conservent un filtre d’emplacement seulement si vous en avez fourni un.

Les listes d’emplacements ne sont pas paginées. Le point de terminaison des bons de commande avec rendez-vous réservés utilise plutôt limit et offset.

Limites de requête

Les requêtes API d’organisation et par emplacement partagent les limites suivantes lorsque vous utilisez le même en-tête Authorization :

Limite	Nombre de requêtes
Par minute	120
Par heure	5 000

Si vous dépassez la limite, l’API retournera un 429 Too Many Requests avec un champ JSON error et les en-têtes suivants :

En-tête	Description
`X-RateLimit-Limit`	La limite dépassée
`X-RateLimit-Remaining`	`0`
`X-RateLimit-Reset`	Quand reprendre, au format ISO 8601 UTC

Attendez la fin du temps de réinitialisation avant de réessayer. Ces en-têtes sont fournis en cas de dépassement de limite ; l’en-tête Retry-After n’est pas fourni.

Gestion des erreurs

Code	Description	À vérifier
`400`	Requête invalide	Indiquez un nom d’emplacement valide lorsque nécessaire. Si présent dans l’URL et le corps, utilisez le même nom.
`401`	Non autorisé	Vérifiez votre jeton API et l’en-tête `Authorization`.
`402`	Paiement requis	Confirmez qu’au moins un de vos emplacements est payant.
`403`	Interdit	Vérifiez que votre utilisateur API a des droits d’administrateur dans l’organisation et l’accès requis sur l’emplacement choisi.
`404`	Introuvable	Vérifiez le nom de l’emplacement et l’ID de l’enregistrement. L’enregistrement doit être accessible à cet emplacement.
`422`	Entité non traitable	Consultez le champ `errors` de la réponse pour savoir quels champs corriger.
`429`	Trop de requêtes	Attendez la fin de la réinitialisation du quota avant de réessayer.

Par exemple, créer un produit sans emplacement retourne une 400 :

{
  "error": "location_name is required"
}

Prochaines étapes

Ressources de l’API d’Organisation — Gérer rendez-vous, produits, entreprises, limites produits et emplacements.
Bons de commande via l’API d’Organisation — Créez des commandes, assignez des entrepôts et suivez les rendez-vous réservés.
Authentification — Obtenez un jeton API et consultez les exemples d’authentification.

Pour obtenir de l’aide avec votre intégration, contactez support@datadocks.com.

Pourquoi utiliser l’API d’Organisation?​

Démarrage rapide en 5 minutes​

Authentification et accès​

Choisir un emplacement​

Lecture ou suppression d’enregistrements​

Création ou modification d’enregistrements​

Noms des emplacements dans les réponses​

Estampilles temporelles et fuseaux horaires​

Pagination​

Limites de requête​

Gestion des erreurs​

Prochaines étapes​