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
Vous pouvez demander la création d'un compte développeur en remplissant ce formulaire. Une clé API vous sera alors fournie pour Sandbox et Production.
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 :
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 l'expiration d'un token
Si vous obtenez une réponse avec un code 401, cela signifie que votre token a expiré.
Si le token n'est plus valide, 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