Aperçu
Le moteur OneRail Delivery API représente les bases de l’envoi de commandes avec la plateforme, sans la complexité supplémentaire du moteur d’API central complet. En plus d’accepter dynamiquement des commandes depuis l’application choisie par votre organisation, il est également capable de générer des requêtes webhook qui peuvent fournir automatiquement des alertes pour les livraisons aux applications connectées.
L’intégration des opérations de votre organisation via l’API permet un traitement et des mises à jour immédiats sans nécessiter d’intervention ou de surveillance manuelle.
Remarque :
De manière générale, nous souhaitons d’abord tester notre intégration d’une façon qui nous permettra de vérifier diverses fonctionnalités sans impacter les opérations de production. Assurez-vous que tous les processus susceptibles de déclencher l’envoi ou le traitement d’une commande soient désactivés pendant toute procédure de test.
Authentification
L’authentification client avec le moteur OneRail API peut être classée en deux méthodes distinctes : basée sur l’utilisateur et basée sur l’organisation. Le processus d’établissement de l’authentification entre votre application et l’API OR dépendra de la méthode d’authentification souhaitée. Les sous-sections suivantes décrivent les étapes à suivre pour implémenter chacune des méthodes d’authentification disponibles :
Authentification basée sur l’utilisateur
Dans cette méthode, les identifiants utilisateur individuels configurés pour votre compte sont présentés à la plateforme par votre application cliente. Après une authentification réussie, votre application cliente agira alors au nom des identifiants de l’utilisateur qui ont servi à l’authentification.
Pour effectuer l’authentification avec cette méthode, votre application cliente devra envoyer une requête POST à l’endpoint « user/authenticate ». Cet endpoint requiert le nom d’utilisateur souhaité ainsi que le mot de passe associé.
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Authentification basée sur l’organisation
L’authentification basée sur l’organisation utilise une paire de valeurs (App ID et clé d’API) qui sont ajoutées à l’en-tête des requêtes destinées au moteur OneRail API. L’App ID et la clé d’API sont créées pour chaque expéditeur de manière individuelle par notre équipe produit, puis distribuées pour une utilisation en production. En utilisant cette méthode, n’importe quelle application de votre organisation qui se connecte à l’API utilisera un ensemble d’identifiants d’authentification représentant chaque expéditeur individuel.
Pour obtenir l’App ID et la clé d’API d’un expéditeur, vous devez d’abord contacter l’équipe de la réussite client OneRail. Ils fourniront une réponse obtenue à partir des ressources produit, contenant les valeurs/identifiants de l’App ID et de la clé d’API générés spécialement pour l’organisation de votre expéditeur. Chaque expéditeur défini pour votre compte aura besoin d’un ensemble d’identifiants d’API permettant d’identifier les commandes associées à un expéditeur en particulier. Assurez-vous que les requêtes envoyées à l’API de livraison par votre application utilisent les identifiants appropriés lors de l’envoi de la commande d’un expéditeur.
Ces identifiants peuvent désormais être utilisés pour authentifier toute requête destinée au compte OneRail de votre organisation. Pour implémenter ces identifiants, leurs valeurs doivent être ajoutées à l’en-tête de toute requête destinée au moteur OneRail API. Les blocs de code suivants indiquent les en-têtes et leurs valeurs associées :
X-ONERAIL-APP-ID: App ID fourni par votre responsable de mise en œuvre X-ONERAIL-API-KEY: Clé d’API fournie par votre responsable de mise en œuvre
Livraisons vs Commandes
Avant de planifier toute implémentation de l’API de livraison, il convient de déterminer si l’on utilisera principalement des fonctions de commande ou de livraison. Une livraison représente une seule commande de livraison sur la plateforme OneRail, tandis qu’une commande représente plusieurs livraisons sur la plateforme OneRail.
Fonctions de livraison
Après l’authentification, votre application peut désormais envoyer des requêtes fonctionnelles au moteur OneRail API au nom de votre organisation ou de l’utilisateur (selon la méthode d’authentification utilisée). Dans ce guide, nous mettrons en œuvre les capacités de l’API de livraison.
Nous allons maintenant montrer comment utiliser certaines des requêtes/endpoints les plus essentielles, mais l’API de livraison peut effectuer une variété de tâches liées à l’interaction avec les commandes de livraison.
Création d’une livraison
L’endpoint /delivery/create a pour but de créer de nouvelles livraisons pour le compte OneRail de votre organisation. Cet endpoint accepte les requêtes POST des clients, contenant un corps de requête (JSON) avec les métadonnées importantes de la livraison.
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Création d’une commande
L’endpoint /order/create a pour but de créer de nouvelles commandes pour le compte OneRail de votre organisation. Les commandes diffèrent des livraisons, car une seule commande peut contenir plusieurs livraisons. Cet endpoint accepte les requêtes POST des clients, avec un corps de requête (JSON) contenant les détails de chaque livraison individuelle, ainsi que les informations décrivant la commande globale dans son ensemble.
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Mise à jour partielle de commande
La fonction de cet endpoint permet une mise à jour partielle des détails d’une commande spécifique. Cette fonctionnalité peut également ajouter ou remplacer des articles et des conteneurs dans une commande existante (si cette mise à jour est nécessaire).
Cet endpoint ajoutera des articles et des conteneurs à une commande existante lorsque les requêtes sont effectuées avec la méthode PATCH . Cet endpoint remplacera les articles et les conteneurs d’une commande existante lorsque les requêtes sont effectuées avec la méthode PUT .
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Ajouter une livraison à une commande existante
La fonctionnalité de cet endpoint crée une nouvelle livraison individuelle (ou plusieurs livraisons) pour une commande existante.
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Annulation d’une commande de livraison
Une commande de livraison envoyée à ORD peut être annulée avant que la commande ne soit expédiée. Cela peut être déterminé par votre organisation ou l’organisation qui envoie la commande (selon votre configuration).
Remarque : Cette fonction n’est applicable qu’aux annulations par l’expéditeur.
Pour annuler une commande, une requête POST peut être envoyée à l’endpoint « /delivery/{id}/cancel » . Le « {id} » dans l’URL doit être remplacé par l’ID de la livraison à annuler.
Pour plus de détails sur cet endpoint, consultez la référence Swagger suivante :
Obtenir les tarifs de livraison
Avant d’envoyer une requête pour créer une livraison spécifique, il est possible de recueillir le tarif pour envoyer cette livraison à l’instant présent sans avoir à envoyer/traiter la livraison en question. L’endpoint "Get Rates" obtiendra les tarifs de tous les transporteurs admissibles pour la livraison.
Pour obtenir les tarifs pour une livraison spécifique, une requête GET est envoyée à l'endpoint /delivery/get-rates qui contient des métadonnées importantes pour la livraison. La réponse de l'endpoint décrira le prix pour envoyer la livraison.
Pour plus de détails sur cet endpoint, reportez-vous à la référence Swagger suivante :
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.