Skip to main content

Implémentation standard

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. Inscription pour un compte développeur​

Inscrivez-vous sur cocolis.fr/developer-sign-up. Une fois connecté, suivez les étapes et remplissez les informations demandées.

Il vous suffira ensuite de créer une clé API depuis votre espace clés API.

3. Authentification​

Toutes les requêtes API doivent être authentifiées via une clé API passée en header de toutes vos requêtes pour pouvoir accéder aux ressources.

info

Pour comprendre le fonctionnement de l'authentification, reportez vous à la rubrique dédiée.

5. Eligibilité d'une livraison​

warning

Tous nos prix sont en centimes​

info

Afin de simuler une livraison non éligible en sandbox, utilisez comme code postal d'arrivée 15000​

info

Calcul du volume final : Le calcul du volume final de l'annonce suit la règle suivante par ordre de priorité :​

  1. Somme de la clée volume_in_m3 des rides objects
  2. Calcul du volume à partir des dimensions des rides_objects : (width * length * height * quantity)
  3. Conversion du format en m3
  4. Prise en compte de la clée volume sur la ride

Pour savoir si la livraison Cocolis est éligible d'un point A à un point B, il faut appeler l'URL :

POST /api/v1/rides/can_match

{
    "title": "Response",
    "type": "object",
    "properties": {
        "from": {
            "type": "object",
            "properties": {
              "postal_code": {
                "type": "string",
                "description": "Code postal du point de départ"
              }
            },
            "required": [
              "postal_code"
            ]
        },
        "to": {
            "type": "object",
            "properties": {
              "postal_code": {
                "type": "string",
                "description": "Code postal du point d'arrivée"
              }
            },
            "required": [
              "postal_code"
            ]
        },
        "volume": {
            "type": "number",
            "description": "Somme des volumes en m3 des produits à livrer. Privilégiez plutôt le champ 'objects'"
        },
        "objects": {
            "type": "array",
            "description": "Dimensions et quantité des objets à livrer ! !!! Si le paramètre volume est défini, c'est le volume calculé des objets qui sera utilisé en priorité !!!!",
            "items": {
              "type": "object",
              "properties": {
                "height": {
                  "type": "number",
                  "description": "Hauteur en cm"
                },
                "width": {
                  "type": "number",
                  "description": "Largeur en cm"
                },
                "length": {
                  "type": "number",
                  "description": "Longueur en cm"
                },
                "volume_in_m3": {
                  "type": "number",
                  "description": "Volume en m3 !!! ne sera pas multiplié par la quantité !!!"
                },
                "qty": {
                  "type": "integer",
                  "description": "Quantité"
                }
              }
            }
        },
        "content_value": {
            "type": "number",
            "description": "Valeur de la livraison en Centimes (Valeur de la commande). Utilisé pour le montant de l'assurance"
        }
    },
    "required": [
      "from",
      "to",
      "volume",
      "content_value"
    ]
}
info

Pour avoir une gestion plus fine des prix, vous pouvez envoyer les dimensions exactes en centimètres des produits à livrer dans la clé objects de l'appel can_match​

6. Création d'une annonce :​

warning

Tous nos prix sont en centimes​

info

N'oubliez pas de spécifier la valeur de external_id (généralement votre identifiant de commande) afin de pouvoir relier les webhooks avec votre commande.​

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.

POST https://api.cocolis.fr/api/v1/rides

{
  "type": "object",
  "description": "Body de la requête",
  "properties": {
    "ride": {
      "$ref": "../models/ride/ride-create.v1.json"
    }
  }
}
info

La Ride est en status published. N'oubliez pas d'implémenter le webhook ride_published !

Quand un transporteur se proposera, l'expéditeur et le destinataire recevront des SMS et mails pour accepter ou refuser le créneaux de passage.

7. Suivi de la livraison par votre site​

A 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.

Dans la documentation détaillée, nous vous donnons un exemple des actions à mettre en place de votre coté selon l'évènement.

8. Suivi de la livraison par le destinataire​

Le destinataire 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 destinataire. Il permet de construire l'URL de suivi qui prend la forme suivante :

https://:domain/tracking/recipient/:tracking_code
ParamètreValeurCommentaire
:domainwww.cocolis.frEn sandbox, le domaine sera sandbox.cocolis.fr
:tracking_coderide.buyer_trackingLors 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 ce lien de tracking sur la page de suivi de commande de votre client.

8.1 Documents de facturation du destinataire​

Le buyer_tracking vous permet également de générer les documents de facturation du destinataire en format PDF. Cela se fait via une URL qui prend la forme suivante et qui déclenchera le téléchargement du PDF :

https://:domain/cocolis-api/rides/recipient/:tracking_code/billing_document
ParamètreValeurCommentaire
:domainwww.cocolis.frEn sandbox, le domaine sera sandbox.cocolis.fr
:tracking_coderide.buyer_trackingLors de la création de la ride, nous vous avons renvoyé ce paramètre dans la clé buyer_tracking
info

Nous vous conseillons d'afficher un lien "Téléchargez la facture" information sur la page de suivi de commande de votre client. Ce bouton est disponible sinon sur la page de tracking mentionnée plus haut.

9. Suivi de la livraison par l'expéditeur​

L'expéditeur 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 expéditeur. Il permet de construire l'URL de suivi qui prend la forme suivante :

https://:domain/tracking/sender/:seller_tracking
ParamètreValeurCommentaire
:domainwww.cocolis.frEn sandbox, le domaine sera sandbox.cocolis.fr
:seller_trackingride.seller_trackingLors 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 ce lien de tracking sur la page de suivi de commande de votre client.

9.1 Documents de facturation de l'expéditeur​

Le seller_tracking vous permet également de générer les documents de facturation de l'acheteur en format PDF. Cela se fait via une URL qui prend la forme suivante et qui déclenchera le téléchargement du PDF :

https://:domain/cocolis-api/rides/sender/:seller_tracking/billing_document
ParamètreValeurCommentaire
:domainwww.cocolis.frEn sandbox, le domaine sera sandbox.cocolis.fr
:seller_trackingride.seller_trackingLors de la création de la ride, nous vous avons renvoyé ce paramètre dans la clé seller_tracking
info

Nous vous conseillons d'afficher un lien "Téléchargez la facture" information sur la page de suivi de commande de votre client. Ce bouton est disponible sinon sur la page de tracking mentionnée plus haut.