Skip to main content

Les Rides

Une Ride correspond à une annonce chez Cocolis.

Vous pouvez regarder le Model pour voir toutes les informations renseignées sur une Ride.

Le volume​

Nos algorithmes de calcul de poids sont basés sur le volume en m3 et la distance de l'annonce. Voici le tableau des correspondances format des objets/volumes :

FormatVolume en m3Exemple
s0.01Tient dans une boîte à chaussures (téléphone, clés, doudou…)
m0.05Tient dans une valise cabine (ordinateur, caisse de vin, platine vinyle…)
l0.3C’est l’équivalent de 4 petites valises cabine. Tient dans le coffre d’une voiture (tableau, télévision, lit parapluie...)
xl0.75Tient dans un break ou un monospace (commode, fauteuil, table basse…)
xxl1.50Nécessite un petit utilitaire (scooter, armoire, canapé, lit…)

Lier votre commande​

Lors de la création d'une annonce, vous devez envoyer dans le champ external_id l'id de la commande chez vous qui a déclenché la création de l'annonce. C'est cette valeur que nous vous renvoyons sur nos webhooks afin de relier nos objets à ceux dans votre base de données.

Les objets d'une annonce​

Lors de la création d'une ride, vous devez envoyer les objets à transporter dans le format spécifié.

Il est important de donner le plus d'informations possibles concernant ces objets :

  • Le format peut soit être donnée via les dimensions exactes (height, width, length) ou bien via un paramètre format qui prend une des valeurs suivantes : s, m, l, xl, xxl correspond à des volumes d'objets tel que défini dans le tableau ci-dessous.

    • format S : 0.01 m3
    • format M : 0.05 m3
    • format L : 0.3 m3
    • format XL : 0.8 m3
    • format XXL : 1.5 m3

  • Le poids peut soit être donnée via un paramètre exact_weight avec le poids exacte en kg ou bien via un paramètre plus général weight qui prend une des valeurs suivantes less_than_5_kg, between_5_and_30_kg, between_30_and_100_kg, more_than_100_kg.

Les options de livraison​

Lors de la création d'une ride, vous pouvez envoyer l'id de(s) option(s) de livraison sélectionnée(s) par l'utilisateur dans le champ ride_delivery_options_ids. Ces ids sont disponibles sur la réponse du can_match dans la clée available_options :

Voir la documentation détaillée

"available_options": {
    "handling": {
        "title": "Manutention",
        "description": "Choisissez une option de manutention pour votre livraison",
        "options": [
            {
                "option_id": 1,
                "label": "Au pied du véhicule",
                "price": 0.0,
                "is_default": true,
                "description": "Aucune aide du transporteur pour porter le bien."
            },
            {
                "option_id": 2,
                "label": "Dans la pièce de mon choix - avec 1 personne",
                "price": 2900.0,
                "is_default": false,
                "description": "Une personne est nécessaire pour porter le bien dans la pièce de votre choix"
            },
            {
                "option_id": 3,
                "label": "Dans la pièce de mon choix - avec 2 personnes",
                "price": 5900.0,
                "is_default": false,
                "description": "Deux personnes sont nécessaires pour porter le bien dans la pièce de votre choix."
            }
        ]
    }
}

Une seule option n'est possible par catégorie d'option (ici dans l'exemple : handling)

Actuellement Cocolis propose uniquement comme catégorie la manutention, pour laquelle 3 choix sont proposés :

  • Aucune aide du transporteur pour porter le bien. option par défaut
  • Une personne est nécessaire pour porter le bien dans la pièce de votre choix.
  • Deux personnes sont nécessaires pour porter le bien dans la pièce de votre choix.

Si l'option retenue est payante, le champ price ne doit pas prendre en compte le prix de l'option, ce champ ne représente que la part livraison.

Les statuts des rides​

StatutsCorrespondanceProchains statuts possiblesCommentaire
publishedRide publiée sur Cocolisavailabilities_pending, expired, removed, moderatedLa ride est publiée sur le site. Elle est visible par les transporteurs disponibles.
availabilities_pendingEn attente de validation des créneauxin_progress, removedUn transporteur a proposé des créneaux de passage que l'expéditeur et le destinataire doivent confirmer
in_progressRide en cours de livraisoncompleted, published, removedL'expéditeur et le destinataire ont validé le créneau de collecte et livraison et la livraison est en cours.
expiredLa ride n'a pas trouvé de transporteur.removedLa ride a expiré sans qu’un transporteur ne se soit proposé. L’équipe de Cocolis reprend la main pour trouver un transporteur.
completedLa ride est terminéeLa livraison a été effectuée
removedLa ride est suppriméeL'annonce est supprimée suite à l’annulation de la vente ou bien si aucun créneau proposé n'a été confirmé plusieurs fois d'affilée par l'expéditeur ou le destinataire.
moderatedLa ride est modéréeLa livraison a été modérée par un administrateur Cocolis

Enchaînement des status​

tip

L'enchaînement standard d'une annonce est : published > availabilities_pending > in_progress > completed

Voici le cycle de vie d'une annonce :

Status de la Ride

Documents de facturation​

Les documents de facturation sont accessibles depuis une URL non-authentifiée de 2 façons.

warning

Ils sont accessibles seulement si le statut est completed ou removed

1. Retrouver les URLs à partir de l'API​

Dans le modèle Ride, vous pouvez retrouvez les propriétés [billing_documents][buyer] et [billing_documents][seller] qui contiennent les URLs des Billing Documents :

{
  'billing_documents': {
    'buyer': 'https://www.cocolis.fr/cocolis-api/rides/recipient/CFE9E3620F1626F9/billing_document',
    'seller': 'https://www.cocolis.fr/cocolis-api/rides/sender/CFE9E3620F1626F9/billing_document'
  }
}

2. Construire l'URL​

Les attributs buyer_tracking et le seller_tracking de la ride vous permettent de générer les documents de facturation de l'acheteur et du vendeur au format PDF. Cela se fait via une URL qui prend l'une des formes suivantes :

# Buyer Billing Documents
> https://:domain/cocolis-api/rides/recipient/:buyer_tracking/billing_document

# Seller Billing Documents
> https://:domain/cocolis-api/rides/sender/:seller_tracking/billing_document
ParamètreValeurCommentaire
:domainwww.cocolis.frEn sandbox, le domaine sera sandbox.cocolis.fr
:buyer_trackingride.buyer_trackingLors de la création de la ride, nous vous avons renvoyé ce paramètre dans la clé buyer_tracking
: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 pour télécharger la facture Cocolis sur la page de suivi de commande de votre client. Ce lien est également disponible à partir de la page de suivi de livraison sur Cocolis.

Idempotence des requêtes​

L'API prend en charge l'idempotence pour permettre la répétition sécurisée des requêtes de création d'annonce sans risque d'exécuter accidentellement la même opération deux fois. Lors de la création, vous pouvez optionnellement utilisez une clé d'idempotence. Ensuite, en cas d'erreur de connexion, vous pouvez répéter la requête en toute sécurité sans risque de créer une deuxième annonce.

Pour effectuer une requête idempotente, fournissez une clé d'idempotence supplémentaire dans les options de la ride idempotency_key.

Vous devez générer manuellement une clé d'idempotence, qui est une clé unique que le serveur utilise pour reconnaître les nouvelles tentatives de la même requête. La manière dont vous créez des clés uniques vous appartient, mais nous vous suggérons d'utiliser des UUID V4 ou une autre chaîne aléatoire avec suffisamment d'entropie pour éviter les collisions. Les clés d'idempotence peuvent avoir jusqu'à 255 caractères.

En cas d'appel de création d'annonce, si notre API detecte une annonce existante avec la même clé d'idempotence, elle renverra l'annonce déjà existante en base ayant la même clé d'idempotence.

Date d'expiration de l'annonce​

La date d'expiration d'une annonce est de 21 jours par défaut après sa publication. Cette valeur peut être ajustée à différents niveaux en contactant l'équipe Cocolis:

  • globalement pour toutes les annonces d'un utilisateur

A noter que si la personne à réception ou à l'expédition a spécifié qu'elle n'est pas disponible avant une date donnée T, la date d'expiration sera recalculée en se basant sur cette date (T + 21 jours).