Implémentation standard
Retrouvez notre librairie JavaScript sur le lien suivant : https://github.com/Cocolis-1/cocolis-js
L'implémentation de Cocolis se fait en général en respectant ces étapes :
1. Principe général
Voici un schéma des échanges entre votre site et l'API Cocolis :
Le prélèvement du montant de la livraison est effectué sur le compte MangoPay associé à votre compte Cocolis. Il est déclenché lors de la confirmation de la livraison par le transporteur, c'est-à-dire lorsque la "Ride" passe en statut "completed".
2. Demander un compte développeur
L'authentification dépend de l'environnement choisi. Sélectionnez votre environnement ci-dessous pour obtenir les bonnes instructions.
- 🟢 Production
- 🧪 Sandbox (test)
Vous devez d'abord créer un compte développeur sur la production.
Générez ensuite votre clé API depuis la page de gestion de vos clés de votre compte développeur.
Gardez précieusement le token généré : il ne sera plus affiché par la suite, et toute personne y ayant accès pourra se faire passer pour vous via des appels API.
Le détail de la procédure se trouve sur Comment obtenir son token d'authentification.
Vous devez d'abord créer un compte développeur sur la sandbox.
Générez ensuite votre clé API depuis la page de gestion de vos clés de votre compte développeur.
Gardez précieusement le token généré : il ne sera plus affiché par la suite, et toute personne y ayant accès pourra se faire passer pour vous via des appels API.
Le détail de la procédure se trouve sur Comment obtenir son token d'authentification.
3. Authentification
Toutes les requêtes API doivent être authentifiées grâce à notre librairie JS pour pouvoir accéder aux ressources.
Pour comprendre le fonctionnement de l'authentification, reportez-vous à la rubrique dédiée. En particulier, concernant la vérification de la validité de vos tokens.
- Créez un Client HTTP avec notre API en vous authentifiant :
Authentification recommandée (API KEY)
const CocolisClient = new Cocolis({ live: false, apiKey: 'mon_api_key' });
La clé est envoyée dans l'en-tête X-API-KEY de chaque appel. Contrairement à l'authentification dépréciée, celle-ci ne nécessite pas de sign_in.
Authentification dépréciée (Tokens)
const CocolisClient = new Cocolis({ live: false });
var r = await CocolisClient.sign_in({ app_id: 'mon_app_id', password: 'mon_password' });
La librairie JS se chargera d'utiliser vos tokens d'authentification pour vous authentifier lors de vos prochains appels.
4. Gérer une erreur d'authentification
Une réponse avec un code 401 signifie que votre authentification n'est pas valide.
Avec une clé API, vérifiez que le token transmis est correct et qu'il n'a pas été régénéré depuis. Une clé API n'expire pas d'elle-même.
Avec l'authentification dépréciée, cela signifie que votre token a expiré : il suffit de refaire un await CocolisClient.sign_in({ app_id: 'mon_app_id', password: 'mon_password' })
5. Éligibilité d'une livraison
Tous nos prix sont en centimes
Pour savoir si la livraison Cocolis est éligible d'un code postal A à un code postal B, il faut appeler :
const canMatchParams = {
from: {
postal_code: '13001',
},
to: {
postal_code: '31000',
},
volume: 500, // Volume en m3
content_value: 120000, // Prix en centimes
};
let response = await CocolisClient.can_match(canMatchParams);
La réponse est sous la forme d'un object Javascript.
Schéma de la réponse
{
"title": "Response",
"type": "object",
"properties": {
"result": { "type": "boolean", "description": "Cocolis peut réaliser la livraison" },
"estimated_prices": {
"type": "object",
"properties": {
"with_insurance": { "type": "number", "description": "Prix avec assurance" },
"regular": { "type": "number", "description": "Prix sans assurance" }
}
},
"insurance_detail": {
"type": "object",
"description": "Informations de l'assurance si éligible",
"properties": {
"amount": { "type": "number", "description": "Montant assuré en centimes" },
"conditions_url": { "type": "string", "description": "Lien vers les conditions générales de l'assurance" }
}
},
"rider_count": { "type": "number", "description": "Le nombre de transporteurs déjà disponibles pour effectuer la livraison" }
}
}
6. Création d'une annonce
Tous nos prix sont en centimes
Quand une vente a été réalisée sur votre site avec notre mode de livraison, il faut ensuite la créer sur Cocolis. Nous vous recommandons de la créer 30 minutes après le paiement pour gérer des cas d'annulation rapide sur votre site.
const createRideParams = {
description: 'Carcassonne vers Toulouse',
from_lat: 43.212498,
to_lat: 43.59912,
from_address: 'Carcassonne',
to_address: 'Toulouse',
from_lng: 2.350351,
to_lng: 1.444391,
from_is_flexible: true,
from_pickup_date: '2020-06-13T14:21:21+00:00',
to_is_flexible: true,
to_pickup_date: '2020-06-13T14:21:21+00:00',
is_passenger: false,
is_packaged: false,
price: 57000,
volume: 15,
environment: 'objects',
ride_delivery_information_attributes: {
from_address: '14 rue des fleurs',
from_postal_code: 69000,
from_city: 'Lyon',
from_country: 'FR',
from_contact_name: 'John Smith',
from_contact_email: 'john.smith@gmail.com',
from_contact_phone: '0601020202',
to_address: '19 rue des champignons',
to_postal_code: 75000,
to_city: 'Paris',
to_country: 'FR',
to_contact_name: 'John Doe',
to_contact_email: 'john.doe@gmail.com',
to_contact_phone: '06 07 08 06 09',
},
};
let response = await CocolisClient.create(createRideParams);
La réponse sera un objet Javascript.
7. Suivi de la livraison par votre site
À chaque changement de statut de l'annonce sur Cocolis, notre système vous enverra des webhooks Voir documentation détaillée aux URLs que vous avez spécifiées. De cette manière, vous pourrez suivre les différentes étapes de la livraison.
8. Suivi de la livraison par l'acheteur
L'acheteur dispose d'une interface dédiée pour le suivi de la livraison. Lors de la création de l'annonce, nous vous avons retourné un buyer_tracking qui est un code de suivi pour votre acheteur. Il permet de construire l'URL de suivi qui prend la forme suivante :
https://:domain/rides/buyer/:buyer_tracking
| Paramètre | Valeur | Commentaire |
|---|---|---|
| :domain | www.cocolis.fr | En sandbox, le domaine sera sandbox.cocolis.fr |
| :buyer_tracking | ride.buyer_tracking | Lors de la création de la ride, nous vous avons renvoyé ce paramètre dans la clé buyer_tracking |
Nous vous conseillons de remonter cette information sur la page de suivi de commande de votre client.
Exemples
Production :
https://www.cocolis.fr/rides/buyer/CFE9E3620F1626F9
Sandbox :
https://sandbox.cocolis.fr/rides/buyer/CFE9E3620F1626F9
9. Suivi de la livraison par le vendeur
Le vendeur dispose d'une interface dédiée pour suivre la livraison. Lors de la création de l'annonce, nous retournons un seller_tracking qui est un code de suivi pour votre vendeur. Il permet de construire l'URL de suivi qui prend la forme suivante :
https://:domain/rides/seller/:seller_tracking
| Paramètre | Valeur | Commentaire |
|---|---|---|
| :domain | www.cocolis.fr | En sandbox, le domaine sera sandbox.cocolis.fr |
| :seller_tracking | ride.seller_tracking | Lors de la création de la ride, nous vous avons renvoyé ce paramètre dans la clé seller_tracking |
Nous vous conseillons de remonter cette information sur la page de suivi de commande de votre client.
Exemples
Production :
https://www.cocolis.fr/rides/seller/7E20B021BF8721A2
Sandbox :
https://sandbox.cocolis.fr/rides/seller/7E20B021BF8721A2