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 :

Schéma principe 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)

info

Vous devez d'abord créer un compte développeur sur la production.

Pour vous authentifier, renseignez les deux paramètres suivants :

ID de l'application : Disponible une fois connecté à votre compte développeur sur www.cocolis.fr, dans le menu Intégration > Documentation de votre compte Cocolis.
Mot de passe : Celui que vous avez utilisé lors de la création de votre compte. Si vous l'avez modifié depuis, utilisez tout de même le mot de passe initial.

info

Vous devez d'abord créer un compte développeur sur la sandbox.

Pour vous authentifier, renseignez les deux paramètres suivants :

ID de l'application : Disponible une fois connecté à votre compte développeur sur sandbox.cocolis.fr, dans le menu Intégration > Documentation de votre compte Cocolis.
Mot de passe : Celui que vous avez utilisé lors de la création de votre compte. Si vous l'avez modifié depuis, utilisez tout de même le mot de passe initial.

3. Authentification

Toutes les requêtes API doivent être authentifiées grâce à notre librairie JS pour pouvoir accéder aux ressources.

info

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' });

info

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

attention

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

attention

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`

info

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`

info

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

1. Principe général​

2. Demander un compte développeur​

3. Authentification​

4. Gérer l'expiration d'un token​

5. Éligibilité d'une livraison​

Schéma de la réponse​

6. Création d'une annonce​

7. Suivi de la livraison par votre site​

8. Suivi de la livraison par l'acheteur​

Exemples​

9. Suivi de la livraison par le vendeur​

Exemples​

1. Principe général

2. Demander un compte développeur

3. Authentification

4. Gérer l'expiration d'un token

5. Éligibilité d'une livraison

Schéma de la réponse

6. Création d'une annonce

7. Suivi de la livraison par votre site

8. Suivi de la livraison par l'acheteur

Exemples

9. Suivi de la livraison par le vendeur

Exemples