DRIVOO REST API v1

Drivoo propose une API simple pour créer des demandes de courses

Vous pouvez vous servir de cette API pour utiliser les fonctionnalités de Drivoo en plus des interfaces fournies par Drivoo.

Les utilisations les plus fréquentes de l'API concernent :

• Création de course
• Récupérer l'état d'une course
• Annuler une course

Une de demande de course est une requête permattant de signifier une livraison d'un point physique vers un client final à une heure définie à l'avance.

A propos de l'API Drivoo

Drivoo met à disposition une API HTTP RESTful, ce qui signifie que le traitement d'une requête sera dépendant de l'ensemble des éléments suivants :

• l'URL de la requête,
• la méthode HTTP (GET, POST, PUT, DELETE) utilisée lors de la requête,
• les paramètres passés lors de la requête :
  • via le body de la requête pour les requêtes POST et PUT,
  • et via l'URL de la requête dans tous les cas.

Les API HTTP RESTful donnent un sens très précis à chaque méthode HTTP, comme expliqué sur cette page wikipedia.

Documentation des appels API

Dans la suite de cette documentation, les appels à l'API seront toujours présentés de la façon suivante :

POST /api/v1/ressource.format?x=y&w=z

                                        {
                                        "clé": "valeur"
                                        ...
                                        }
                                    

1 La première ligne indique la méthode HTTP utilisée (dans l'exemple POST), suivie d'un espace, puis de l'URL appelée sur l'API (dans l'exemple /api/ressource?x=y&w=z).

Pour la clarté de la présentation, l'URL est volontairement raccourcie. Elle contient :

• le "path", dans l'exemple /api/ressource,
• et, optionnellement, des paramètres, dans l'exemple ?x=y&w=z.

Lors de votre utilisation de l'API vous devrez compléter cette URL, selon le cas, avec l'URL de base de production ou bien de test/recette (voir rubriques ci-dessous).

Ex: /course deviendra https://api.drivoo.com/course en production.

Vous devrez également veiller à passer en paramètre toutes les informations utiles concernant l'authentification (clé API), la pagination, lesformats, etc.

Note Lorsque l'URL contient des mots clés précédés d'un caractère :, ils sont à remplacer par des valeurs correspondant à votre cas d'utilisation. Par exemple l'URL /course/:course_id contient un mot clé :course_id, que vous devrez remplacer par une valeurs numérique, par exemple /course/4.

2 La deuxième ligne et les lignes suivantes, lorsqu'elles sont présentes dans l'exemple, correspondent au contenu du "body" de la requête (requêtes de type POST ou PUT).

URL de production

Pour utiliser l'API en production, l'URL de base est :

https://api.drivoo.com

Important A terme L'API fonctionnera exclusivement en HTTPS (port 443). Si vous essayez d'utiliser l'API en HTTP, vous obtiendrez un message d'erreur.

URL de test/recette

Si votre utilisation de l'API nécessite l'accès en écriture, il est préférable de développer l'application sur notre plateforme de test.

L'URL de base devient alors :

http://sandbox.drivoo.com

Important La clé API, nécessaire pour tous les appels API, n'est pas la même que la clé API de production.

Format de réception de données

Atuellement, l'API Drivoo permet de récupérer les données dans le format : json.

Format d'envoi des données / Content-Type

Important Les requêtes d'écritures à l'API (requêtes HTTP utilisant la méthode POST), doivent contenir le header Content-Type correspondant au format des données envoyées dans le corps de la requête (body).

• application/json
• application/x-www-form-urlencoded

Authentification API

Pour effectuer des requêtes à l'API, vous aurez besoin :

• Un identifiant et un mot de passe

Pour obtenir ces identifiants, veuillez nous contacter par mail jerome@drivoo.fr

• This POST requests a new token to the OAuth2 server using the client_credentials mode. HTTP Basic : le login/mdp est envoyé dans chaque requête.
• Une session : première requête de connexion, puis envoie du header de session dans les requêtes suivantes.

POST http://api.drivoo.com/oauth
                {
                   "grant_type": "client_credentials",
                   "client_id":"testclient",
                   "client_secret":"testpass"
                }
                

Important N'oubliez pas de spécifier dans le header le Content-type à application/json

Le serveur OAuth2 renvoie une réponse avec le token dans la structure JSON suivante :

{
                "access_token":"8ed2b8d7f1210a39432a2fa2c41ecbb334de6f59",
                "expires_in":36000,
                "token_type":"Bearer",
                "scope":null
                }
                

Token

OAuth2 est basé sur l'échange d'un token entre le client et la ressource appelée.

Ce token sert à authentifier tous les appels à l'API au travers du HTTP Header.

Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia

Réponses API

Codes HTTP

Tous les codes du standard HTTP sont respectés au maximum. Le code de réponse HTTP est contenu dans l’entête HTTP, et non dans le contenu de la réponse. La récupération de ce code dépend donc du client HTTP utilisé.

• 200 OK : tout s’est bien passé
• 201 Created : un objet a été créé avec succès

Tous les autres codes indiquent que quelque chose s’est mal passé.

Les codes d’erreurs que vous êtes susceptibles de voir sont :

• 400 Bad Request : un paramètre de requête est manquant ou erroné. Le message d’erreur associé vous indique généralement le problème
• 401 Unauthorized : vous n’êtes pas authentifié ou le couple login/mot de passe est erroné
• 403 Forbidden : vous n’avez pas la permission requise pour exécuter cette opération
• 404 Not Found : la ressource demandée n’existe pas, ou vous n’y avez pas accès
• 405 Method Not Allowed : vous avez utilisé une méthode HTTP non disponible sur la ressource
• 500 Internal Server Error : un problème est survenu au sein de l’application DRIVOO; si cette erreur persiste, merci de nous contacter

Réponse des ressources de type collection

Les réponses sur les ressources collection sont paginées. (Par défaut, l’API Drivoo renvoie les 25 premiers éléments.)

La réponse contient donc des informations relatives à la pagination, mais aussi au tri :

API - Filtrage et Pagination

Important Les options ci-dessous sont disponibles uniquement sur les URLs de type "collection" (listes).

Options de tri et pagination

Par défaut, l’API de Drivoo propose une pagination de toutes les ressources « collection » limitée à 25 éléments.

Exemple :

GET https://api.drivoo.com/course?page=3&per_page=25&sort=id

Demande de clé API

Ressources de l'API Drivoo v1

Liste des ressources

• Colis
• Driver
• Course
• Retailer

Attributs communs

Les attributs ci-dessous sont communs à toutes les ressource de type member, et sont accessibles en lecture uniquement.

Etat de la course

Une course peut passer par les différents suivants:

Colis API

Un colis représente un objet à livrer pour un client donné.

Driver API

Un driver représente une personne physique pouvant effectuer la livraison de colis.

Course API

Création d’une course

POST /course

En cas de succès, le code HTTP renvoyé est 201 Created. En cas d'erreur, un code HTTP 400 est renvoyé.

                    POST https://api.drivoo.com/course
                    $ curl –X POST https://api.drivoo.com/course
                    --header "Content-Type:application/json"
                    --data '{
                    "retailer_id":"99999",
                    "date_debut":"2014-10-04T20:15:00.000Z",
                    "commentaire_retailer":"ici le commentaire",
                    "commentaire_client":"Sonnez Porte 1, bat B",
                    "delai":"2",
                    "client":{"address":"54 av Winston Churchill, 31770, Colomiers, France","nom":"Mme Michu","mobile":"0651451225"},
                    "colis":[
                        {
                        "description":"colis fragile","typecolis":"2"
                        }
                    ]
                    }'
                    

Important : Une course doit posséder au moins un colis.

Modifier une course

PUT /course/:id

En cas de succès, le code HTTP renvoyé est 201 Created. En cas d'erreur, un code HTTP 400 est renvoyé.

                    $ curl –X PUT  https://api.drivoo.com/course/1526 
                    --header "Content-Type:application/json"
                    --data  '{
                    "commentaire_client": "Saisir le code 1254 pour ouvrir la porte"
                    }'
                    

Lister les courses d'un retailer

GET /course

Important: Par défaut, toutes les courses sont retournés.
Pour obtenir seulement les courses disponibles, il suffit de passer le paramètre ?etat=created Voir la liste des états d'une course

                        {
                        "id": "107",
                        "date_debut": "2014-10-28 14:52:00",
                        "delai": "2",
                        "etat": "created",
                        "retailer_adresse": "Simorre",
                        "retailer_nom": "martin",
                        "retailer_societe": "Decathlon",
                        "retailer_lat": "43.5293972",
                        "retailer_long": "1.404874299",
                        "retailer_photo": "photo-mag-1268526336_54350b9a1b7ee.jpg",
                        "driver_adresse": null,
                        "driver_nom": null,
                        "driver_prenom": null,
                        "client_adresse": "Place du Capitole, Toulouse, France",
                        "client_nom": "ytytfut",
                        "client_prenom": null,
                        "client_lat": "43.6044328",
                        "client_long": "1.443463"
                        },
                        ........
                    

Annuler une course

DELETE /course/:id

En cas de succès, le code HTTP renvoyé est 204 No Content. En cas d'erreur, un code HTTP 400 est renvoyé.

Retailer API

Un retailer représente une entité physique ou un commerçant, ou les drivers récupèrent les colis pour vos clients.

Lister les retailers

GET /retailer

Important: Retourne une liste paginable de retailers.

                    "retailer": [
                          {
                            "id": "1",
                            "nom": "test",
                            "prenom": "eric",
                            "societe": "Allard Fleur",
                            "email": "allard@gmail.com",
                            "mobile": null,
                            "adresse": "869 ru de championnet , la seyne sur mer",
                            "latitude": "",
                            "longitude": "",
                            "ville_id": null,
                            "photo": null,
                            "user_id": "1",
                            "password": "",
                            "created": "0000-00-00 00:00:00",
                            "_links": {
                              "self": {
                                "href": "http://api.drivoo.com/retailer/1"
                              }
                            }
                          },
                          {
                            "id": "2",
                            "nom": "martin2",
                            "prenom": "eric2",
                            "societe": "Allard Fleur2",
                            "email": "allard@gmail.com",
                            "mobile": null,
                            "adresse": null,
                            "latitude": "",
                            "longitude": "",
                            "ville_id": null,
                            "photo": null,
                            "user_id": "0",
                            "password": "",
                            "created": "0000-00-00 00:00:00",
                            "_links": {
                              "self": {
                                "href": "http://api.drivoo.com/retailer/2"
                              }
                            }
                          },
                    ........
                    ]
                

Récupérer un retailer par son ID

GET /retailer/:id

GET https://api.drivoo.com/course/1

Retourne :

    
                {
                   "id": "1",
                   "nom": "test",
                   "prenom": "eric",
                   "societe": "Allard Fleur",
                   "email": "allard@gmail.com",
                   "password": "",
                   "mobile": null,
                   "adresse": "869 ru de championnet , la seyne sur mer",
                   "latitude": "",
                   "longitude": "",
                   "ville_id": null,
                   "photo": null,
                   "user_id": "1",
                   "_links":
                   {
                       "self":
                       {
                           "href": "http://api.drivoo.com/retailer/1"
                       }
                    }
                }