Parcours métier
Récupération, atelier et retour
Deux courses AREL, un seul parcours de suivi : du client vers l’atelier, puis de l’atelier vers le client.
Disponible pour les comptes autorisés par AREL
Ce parcours s’utilise uniquement sur les créations portant explicitement workflow: "workshop_return". Les livraisons ordinaires et les anciennes commandes conservent leur fonctionnement habituel. Contactez AREL pour autoriser ce parcours sur votre compte avant de l’intégrer.
1. Créer les deux courses d’une même commande
Envoyez deux requêtes à POST /shipping avec la même groupReference : une collecte isCollection: true, puis un retour isCollection: false. La référence de groupe est propre à votre compte et doit identifier une seule commande atelier. Une course normale avec la même référence ne rejoint pas automatiquement ce parcours.
Chaque requête de ce parcours doit porter une X-Idempotency-Key distincte, de 128 caractères maximum. Réutilisez la même clé pour réessayer exactement la même création après une interruption ; utilisez une autre clé pour le second trajet.
curl -X POST "https://api.arelpro.com/pro/api/v1/shipping" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "X-Client-Id: VOTRE_CLIENT_ID" \
-H "X-Idempotency-Key: commande-1042-collecte" \
-H "Content-Type: application/json" \
-d '{
"workflow": "workshop_return",
"groupReference": "COMMANDE-1042",
"isCollection": true,
"collectionContact": {
"name": "Camille Martin",
"email": "camille@example.com",
"phoneNumber": "+33600000000"
},
"pickupAddress": {
"street": "10 rue de Rivoli",
"postalCode": "75001", "city": "Paris", "country": "France"
},
"deliveryAddress": {
"recipientName": "Atelier",
"street": "20 rue de Tolbiac",
"postalCode": "75013", "city": "Paris", "country": "France",
"email": "atelier@example.com", "phoneNumber": "+33600000001"
},
"parcelDetails": { "weight": 1, "nature": "Bien à prendre en charge" }
}'curl -X POST "https://api.arelpro.com/pro/api/v1/shipping" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "X-Client-Id: VOTRE_CLIENT_ID" \
-H "X-Idempotency-Key: commande-1042-retour" \
-H "Content-Type: application/json" \
-d '{
"workflow": "workshop_return",
"groupReference": "COMMANDE-1042",
"isCollection": false,
"pickupAddress": {
"street": "20 rue de Tolbiac",
"postalCode": "75013", "city": "Paris", "country": "France"
},
"deliveryAddress": {
"recipientName": "Camille Martin",
"street": "10 rue de Rivoli",
"postalCode": "75001", "city": "Paris", "country": "France",
"email": "camille@example.com", "phoneNumber": "+33600000000"
},
"parcelDetails": { "weight": 1, "nature": "Bien après passage à l’atelier" }
}'Les autres conditions habituelles restent applicables : compte autorisé, droits API, adresse valide, zones de livraison ouvertes et conditions de paiement. Chaque course conserve son propre bordereau, livreur, tarif et statut opérationnel. Le parcours comprend deux courses facturées selon les conditions habituelles du compte ; le retour en attente reste une course créée, avec son tarif.
2. Conserver l’identifiant et le lien du parcours
La réponse de création ajoute shipping.journey. Stockez son id avec votre commande et affichez son trackingUrl au client. Le lien est commun aux deux trajets ; les références des deux bordereaux restent disponibles pour vos opérations.
{
"success": true,
"shipping": {
"referenceNumber": "AREL-20261112-00042",
"status": "programmed",
"journey": {
"id": "IDENTIFIANT_DU_PARCOURS",
"role": "return",
"hold": true,
"trackingUrl": "https://arelpro.com/tracking/journey/TOKEN_PUBLIC"
}
}
}hold: true signifie que le retour attend encore son autorisation de départ. La création de sa course ou la simple assignation d’un livreur ne signifie pas que le bien a déjà été récupéré à l’atelier.
3. Afficher les quatre jalons métier
| Événement sur la course | Code du jalon | Texte client |
|---|---|---|
| Collecte : picked_up | collected_from_customer | Récupéré chez le client |
| Collecte : delivered | dropped_at_workshop | Déposé à l’atelier |
| Retour : picked_up | collected_from_workshop | Récupéré à l’atelier |
| Retour : delivered | delivered_to_customer | Livré |
Le dépôt à l’atelier n’est pas la livraison finale
Une collecte au statut opérationnel delivered veut dire « déposée à l’atelier ». Pour votre commande client, utilisez le statut du parcours. Celui-ci devient delivered lorsque le retour a été livré au client, et non au premier dépôt.
Le parcours renvoie status, statusLabel, version, updatedAt, workshopReadyAt, les milestones et les legs. Chaque jalon porte completed et occurredAt ; une étape à venir garde occurredAt: null. Affichez ces confirmations réelles sans inventer les étapes manquantes.
| Statut du parcours | Signification |
|---|---|
awaiting_collection | En attente de récupération chez le client |
collected_from_customer | Récupéré chez le client, en route vers l’atelier |
at_workshop | Déposé à l’atelier, attente de sa confirmation |
awaiting_return | Atelier prêt, attente de récupération à l’atelier |
collected_from_workshop | Récupéré à l’atelier pour retour au client |
delivered | Restitution finale confirmée |
cancelled | Parcours annulé |
attention | Situation à vérifier ; ne pas afficher une livraison réussie |
Annulation ou incident sur un trajet
L’annulation d’une course peut placer le parcours en attention. Ne la traduisez pas automatiquement par « livré » ou par l’annulation de toute la commande. L’historique reste visible et aucune course de remplacement n’est créée automatiquement. Vérifiez la situation auprès d’AREL avant d’organiser une nouvelle prise en charge.
4. Confirmer que l’atelier est prêt
Lorsque l’atelier peut rendre le bien, votre serveur appelle POST /shipping/journeys/:id/ready, avec les mêmes en-têtes d’authentification que vos créations. Cette action est idempotente : la répéter ne doit pas créer une autre course.
Appelez cette route après le dépôt confirmé à l’atelier et après avoir créé la course de retour en attente. Un appel anticipé est refusé sans déclencher de départ. Le départ du retour exige à la fois le dépôt confirmé à l’atelier et le signal « prêt ». Ce signal ne confirme ni un enlèvement ni une livraison : le troisième jalon attend la récupération effective par le livreur. Une date prévue ou l’existence du bordereau de retour ne remplace pas cette confirmation.
5. Recevoir les changements sur votre serveur
Abonnez votre serveur à shipping.journey.updated. Cet événement porte l’état global du parcours ; les anciens événements shipping.picked_up et shipping.delivered restent les événements de chaque course.
curl -X POST "https://api.arelpro.com/pro/api/v1/webhooks" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "X-Client-Id: VOTRE_CLIENT_ID" \
-H "Content-Type: application/json" \
-d '{
"url": "https://votre-serveur.example/webhooks/arel",
"events": ["shipping.journey.updated"]
}'Extrait d’une notification de parcours :
{
"id": "journey_IDENTIFIANT_DU_PARCOURS_v3",
"eventId": "journey_IDENTIFIANT_DU_PARCOURS_v3",
"event": "shipping.journey.updated",
"timestamp": "2026-11-12T14:00:00.000Z",
"data": {
"id": "IDENTIFIANT_DU_PARCOURS",
"groupReference": "COMMANDE-1042",
"workflow": "workshop_return",
"status": "at_workshop",
"statusLabel": "Déposé à l’atelier",
"version": 3,
"updatedAt": "2026-11-12T14:00:00.000Z"
}
}Le champ data contient la projection marchande du parcours, dont les jalons et les deux trajets. Le champ eventId, repris dans X-Arel-Event-Id, reste identique à chaque tentative de remise de cette version.
- Vérifiez la signature HMAC sur
X-Arel-Timestamp + "." + corps_brut, avec le secret renvoyé à la création de votre abonnement. Contrôlez aussi la fraîcheur de l’horodatage et conservez le corps brut avant de le parser. - Enregistrez durablement l’événement reçu avant de répondre
2xx, puis traitez-le en tâche de fond. La réponse doit arriver en moins de cinq secondes. - Dédupliquez sur
eventIdet gardez la dernièredata.versionappliquée par parcours. Ne dédupliquez pas surdata.id + event: cela supprimerait tous les jalons suivants du même parcours. - Les événements de parcours sont conservés dans une file dédiée avec réessais persistants. Un retard réseau peut différer leur réception et une réponse perdue peut entraîner un doublon. Relisez le parcours par API en cas d’écart.
6. Lire et actualiser le suivi
# Authentification identique aux autres routes de l’API marchande.
GET /shipping/journeys?groupReference=COMMANDE-1042
GET /shipping/journeys/IDENTIFIANT_DU_PARCOURS
POST /shipping/journeys/IDENTIFIANT_DU_PARCOURS/ready
# Lecture publique, sans clé API : URL distincte de la base marchande.
GET https://api.arelpro.com/public/journeys/TOKEN_PUBLICLes lectures marchandes renvoient { success: true, journey } ou { success: true, journeys } pour la recherche par groupe. L’accès reste limité aux parcours de votre compte. La lecture publique renvoie directement la projection de suivi, sans enveloppe success.
- Utilisez le parcours comme référence de suivi de votre commande, et gardez les deux identifiants de course pour vos opérations.
- Votre serveur reçoit les mises à jour, puis votre interface relit le parcours pour afficher l’état courant. Un événement reçu par votre serveur n’actualise pas à lui seul le navigateur du client.
- Sur une page ouverte, une lecture toutes les 15 secondes est suffisante ; suspendez-la en arrière-plan et arrêtez-la sur
deliveredoucancelled. Une nouvelle lecture après retour sur la page permet de retrouver l’état courant. - La
versionaide à ignorer une information plus ancienne déjà reçue. Conservez un traitement idempotent des événements et relisez l’état courant en cas de doute.
Confidentialité et codes de remise
Le lien public contient un jeton aléatoire de 64 caractères hexadécimaux. Il donne accès au suivi : partagez-le uniquement avec les personnes concernées, ne l’utilisez pas comme identifiant de commande et ne l’envoyez pas à des outils de mesure d’audience.
Le suivi public ne contient ni coordonnées personnelles, ni adresse complète, ni prix, ni QR code. Les preuves de récupération et de remise restent propres à chaque course, avec le bon code communiqué au bon acteur au moment concerné.