Guide Shopopop
Migration API v1 vers v2
Découvrez tous les changements liés à la montée de version de notre API.
URL
Sandbox : https://partners-api-sandbox.shopopop.com/v2
Production : https://partners-api.shopopop.com/v2
| URL API v1 | URL API v2 |
| POST https://partners.shopopop.com/deliveries/eligibility | POST https://partners-api.shopopop.com/v2/deliveries/eligibility |
| POST https://partners.shopopop.com/deliveries | POST https://partners-api.shopopop.com/v2/deliveries |
| PUT https://partners.shopopop.com/deliveries/{deliveryId}/delivery-slot | PUT https://partners-api.shopopop.com/v2/deliveries/{deliveryId}/delivery-slot |
| POST https://partners.shopopop.com/deliveries/{deliveryId}/cancel | DELETE https://partners-api.shopopop.com/v2/deliveries/{deliveryId} |
| GET https://partners.shopopop.com/deliveries/{deliveryId}/status | ❌ SUPPRIMÉ, remplacé par GET https://partners-api.shopopop.com/v2/deliveries/{deliveryId} |
| GET https://partners.shopopop.com/deliveries/{deliveryId}/history |
❌ SUPPRIMÉ, remplacé par GET https://partners-api.shopopop.com/v2/deliveries/{deliveryId} |
Authentification
Désormais l’authentification pour chaque appel à l’API V2 de Shopopop doit se faire en utilisant le principe de ‘Basic Access Authentication’ et être uniquement envoyé en tant qu’en-tête.
Le format attendu pour l'en-tête de la requête est le suivant :Authorization: Basic <base64-encoded-partner_id:api_key>
En V1 :
Vous aviez deux possibilités :
- Chaque appel contient deux informations au niveau de l’en-tête de la requête.
- Les informations pouvaient être présente au niveau du corps de la requête.
En V2 :
L’en-tête de la requête contient :Authorization: Basic <base64-encoded-"ABCD:EFGH">
Vos identifiants actuels fonctionneront également en V2. Si vous souhaitez connaître vos identifiant (Sandbox et Production), veuillez contacter support.api@shopopop.com.
Vous trouverez plus d’informations sur notre documentation.
Exemple :
Authorization: Basic cGFydG5lcl9pZDpwYXJ0bmVyX2tleQ==cGFydG5lcl9pZDpwYXJ0bmVyX2tleQ== : Correspond à l’encodage en base 64 de la chaîne de caractères “partner_id:api_key”
| ℹ️ Le partner_key demandé en v2 correspond à l’api_key demandé en v1 ⇒ partner_key = api_key |
POST /deliveries/eligibily - POST /deliveries
| ℹ️ Si vous n’utilisiez pas la route eligibility dans la v1, elle n’est également pas obligatoire dans la v2. |
| ℹ️ Une grande partie des champs existants dans la v1 ont été renommés dans la v2. |
| ℹ️ Les nouveaux champs ajouté à la requête sont optionnels et permettront d’ajouter plus de contexte à la livraison. |
La requête est maintenant divisé en 3 entités :
pickupdropoffdelivery
Détails entités pickup / dropoff / delivery
Entité pickup
Entité lié au point de retrait.
Détails :
|
Champs v1 |
Champs v2 |
Description |
Required |
| data.drive.id | pickup.id | L’identifiant du point de retrait dans votre système. | ✅ |
| data.drive.name | pickup.name | Nom du point de retrait. |
| ℹ️ Les informations des champs supprimés entre la version 1 et 2, n’étaient pas utilisées car elles sont paramétrées dans notre interface Shopopop lors de la création des points de retrait. |
Exemples :
Entité dropoff
Entité liée à la dépose de la livraison.
Détails :
| Champs v1 | Champs v2 | Description | Required |
|
data.delivery.delivery_date |
dropoff.dropoff_start |
Changement |
✅ |
|
data.delivery.delivery_date |
dropoff.dropoff_end |
Changement |
✅ |
| data.client.first_name | dropoff.contact.first_name | Prénom du destinataire | |
| data.client.last_name | dropoff.contact.last_name | Nom du destinataire | ✅ |
| data.client.email | dropoff.contact.email | Email du destinataire. Il doit être unique pour chaque destinataire. ⚠️ Attention, si vous envoyez une adresse mail par defaut pour plusieurs destinataire, cela va écraser les données précédentes à chaque nouvelle livraison. |
✅ |
| data.client.telephone | dropoff.contact.phone | Téléphone du destinataire | ✅ |
| data.address.street | dropoff.street | La rue du destinataire | ✅ |
| data.address.zip_code | dropoff.zip_code | Le code postal du destinataire | ✅ |
| data.address.city | dropoff.city | La ville du destinataire | ✅ |
| data.address.country | dropoff.country | Le pays du destinataire | |
| data.address.telephone_other | dropoff.phone_other | Téléphone alternatif du destinataire | |
| 🆕 Nouveau champ |
dropoff.location_name ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
Nom de la localisation (nom d’une église, nom d’entreprise…) | |
| data.address.type | dropoff.type ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
🆕 Nouvelles données |
|
| data.address.digicode | dropoff.entry_code | Digicode de l’adresse du destinataire | |
| data.address.floor | SUPPRIMÉ | Étage de l’adresse du destinataire. | |
| data.address.elevator | dropoff.elevator | Ascenseur de l’adresse du destinataire Si null sera traduit par “Ne sait pas” dans le back-office et l’application mobile |
|
| data.address.comment | dropoff.comment | Information supplémentaire de l’adresse du destinataire | |
| data.address.latitude | dropoff.latitude | Coordonnées GPS de l’adresse du destinataire | |
| data.address.longitude | dropoff.longitude | Coordonnées GPS de l’adresse du destinataire |
Exemples :
Entité delivery
Information sur la livraison et son contenu.
Détails :
| Champs v1 | Champs v2 | Description | Required |
|
data.delivery.trip_id
|
delivery.id |
Identifiant unique de la livraison
|
✅ |
|
data.delivery
|
delivery.order |
Entité contenant des informations sur la commande
|
✅ |
| data.delivery.reference | delivery.order.reference | Référence de la commande | ✅ |
| data.delivery.amount | delivery.order.amount | Montant total de la commande. | ✅ |
| data.delivery.quantity | delivery.order.number_of_items | Nombre total d’articles | |
| data.delivery.has_fresh_food | delivery.order.frozen_food | Changement Est-ce que la commande contient des produits surgelés ? Par défaut : FALSE Attention, ce champs ne concerne désormais que les articles surgelés. |
|
| 🆕 Nouveau champ |
delivery.order.alcohol ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
Est-ce que la commande contient de l’alcool ? Par défaut : FALSE |
|
| data.delivery.other_detail | delivery.order.order_detail | Détails des articles de la commande | |
| data.delivery.other_detail.title | delivery.order.order_detail.title | Nom de l’article | |
| data.delivery.other_detail.quantity | delivery.order.order_detail.quantity | Quantité de l’article | |
| 🆕 Nouvelle entité | delivery.content_size |
Entité contenant les informations de dimensions de la commande à livrer. |
✅ |
| 🆕 Nouveau champ | delivery.content_size.category | Taille de la commande avec des tailles de t-shirt : XS S M L XL XXL) | |
| data.delivery.weight | delivery.content_size.weight | Poids total de la commande en Kg |
|
| data.delivery.volume | delivery.content_size.volume | Volume total de la commande en Litres | |
| 🆕 Nouvelle entité | delivery.content_size.dimensions | Entité contenant les dimensions en cm de la commande | |
| 🆕 Nouveau champ | delivery.content_size.dimensions.length | Longueur totale des articles de la commande | |
| 🆕 Nouveau champ | delivery.content_size.dimensions.height | Hauteur totale des articles de la commande | |
| 🆕 Nouveau champ | delivery.content_size.dimensions.depth | Profondeur totale des articles de la commande | |
|
🆕 Nouveau champ |
delivery.content_size.heavy_item |
Est-ce qu’il y a présence d’un article lourd ? Par défaut : FALSE |
|
| 🆕 Nouveau champ |
delivery.content_size.bulky_item ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
Est-ce qu’il y a un article volumineux ou encombrant ? Par défaut : FALSE |
|
| 🆕 Nouvelle entité | delivery.content_size.size_for_florists | Entité contenant des détails sur la taille des commandes pour les fleuristes. | |
| 🆕 Nouveau champ | delivery.content_size.size_for_florists.type | Type d’articles : SINGLE_BOUQUET FLORAL_ARRANGEMENT TREE_PLANT | |
| 🆕 Nouveau champ | delivery.content_size.size_for_florists.quantity | Nombre d’articles | |
| 🆕 Nouveau champ |
delivery.special_event ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
Pour quel évènement la commande est a livrer ? GIFT FUNERAL NONE Par défaut : NONE |
|
| 🆕 Nouveau champ |
delivery.minimal_transport_mode ℹ️ Ce champ est accepté mais n'est pas encore affiché dans tous nos produits |
Quel mode transport minimum souhaitez-vous pour cette livraison ? TRANSPORT_1 TRANSPORT_2 TRANSPORT_3 TRANSPORT_4 TRANSPORT_5 TRANSPORT_6 Pour plus d’information, vous pouvez aller voir la documentation |
|
| delivery.additional_infos | delivery.additional_infos | Information complémentaire concernant la commande à livrer. ⚠️ Attention ce champ s’affiche en amont de la réservation sur l’application, il ne doit pas contenir de donnée personnelle. (Ex : numéro de téléphone / digicode …) |
Exemples :
Détails : delivery.special_event et data.address.type
Exemple pour une livraison de type deuil, vous pouvez envoyer :
-
delivery.special_event : FUNERAL
-
data.address.type : CEMETERY ou FUNERAL_HOME ou NONE
Correspondance des types de lieux :
- Domicile d’un particulier : PRIVATE_HOME
- Entreprise : COMPANY
- Lieu de culte : PLACE_OF_WORSHIP
- Lieu de santé : HEALTH_FACILITY
- Cimetière : CEMETERY
- Funérarium : FUNERAL_HOME
Détails : delivery.content_size
|
ℹ️ Si actuellement sur la v1, vous nous envoyez le poids ou la volume de la livraison, ils nous permettront toujours de déterminer la taille de la livraison. |
Nous demandons au minimum 1 élément permettant de déterminer la taille de la livraison.
Pour plus d’information, vous pouvez consulter la documentation API.
Éléments permettant de déterminer la taille :
delivery.content_size.categorydelivery.content_size.weightdelivery.content_size.volumedelivery.content_size.dimensionsdelivery.content_size.size_for_florists
Matrice pour évaluer la delivery.content_size.category :
Exemples :
V2 - delivery.content_size.category
v2 - delivery.content_size.size_for_florists
V2 - delivery.content_size.dimensions
PUT /deliveries/{deliveryId}/delivery-slot
Cette route permet de modifier le créneau de la livraison, date ou heure.
Détails :
| Champs v1 | Champs v2 | Description | Required |
| delivery_start | dropoff_start | Début du nouveau créneau de livraison. | ✅ |
| delivery_end | dropoff_end | Fin du nouveau créneau de livraison | ✅ |
Exemples :
GET /deliveries
La route GET /deliveries remplace les deux routes :
- GET /deliveries/status
- GET /deliveries/history
Il est cependant recommandé d’utiliser les webhooks pour recevoir les statuts des livraisons à chaque changement. Pour plus d’information, vous pouvez aller voir la documentation.
Réponses
Réponses 2XX
| Réponses v1 | Réponses v2 | Description | Routes concernées |
| Changement Success - 200 |
Success - 204 | La livraison est modifiée | PUT/delivery-slot |
| Changement Success - 200 |
Success - 204 | La livraison est annulée | DELETE/deliveries |
Réponses 4XX et 5XX
| Réponses v1 | Réponses v2 | Description | Routes concernées |
| Changement WRONG_AUTHENTICATION_PARAM - 403 |
not_authorized - 401 | POST /deliveries POST /eligibility DELETE /deliveries PUT /delivery-slot |
|
| Changement fields request data - 400 |
invalid_format - 400 | Format invalid transmis. | POST /deliveries POST /eligibility DELETE /deliveries PUT /delivery-slot |
| Changement ACTIVE_PICKUP_POINT_NOT_FOUND - 400 |
pickup_not_valid - 400 | Pickup point n’est pas connu | POST /deliveries POST /eligibility |
| Changement INVALID_RETAILER_CODE - 409 |
retailer_not_valid - 400 | Enseigne n’est pas connu connu | POST /deliveries POST /eligibility |
| Changement CANNOT_GEOLOCATE - 500 |
geocoding_impossible - 400 | Le géocodage de l’adresse n’est pas possible | POST /deliveries POST /eligibility |
| Changement INVALID_COUNTRY - 400 |
different_countries - 400 | Le pickup point et l’adresse de livraison n’est pas le dans le même pays | POST /deliveries POST /eligibility |
| Changement WRONG_INTERVAL_BETWEEN_DELIVERY_DATES - 400 |
delivery_slot_too_short - 400 | Créneau de livraison trop court | POST /deliveries POST /eligibility PUT /delivery-slot |
| Changement INVALID_DELIVERY_HOURS - 400 |
delivery_slot_not_valid - 400 | Créneau de livraison non valide car en dehors des horaires de livraison. | POST /deliveries POST /eligibility PUT /delivery-slot |
| Changement ERRAND_UPDATE_IMPOSSIBLE - 400 |
delivery_cannot_be_shifted - 400 | La livraison ne peut être modifié dût à un statut avancé | PUT /delivery-slot |
| Changement NOT_FOUND - 404 |
delivery_not_found - 404 | La livraison n’est pas connu | PUT /delivery-slot DELETE /deliveries |
| Changement NOT_EXISTING - 404 |
status_does_not_permit_cancellation - 400 | La livraison ne peut pas être annulé dût à un statut avancé | DELETE /deliveries |
Exemples de réponses :
