Skip to main content

​
Flux de réservation

Ce guide décrit le cycle de vie complet d’une réservation, depuis sa création par un expéditeur jusqu’à la livraison du colis par le transporteur.

​
Machine à états

​
Étape par étape

​
1. Créer la réservation

L’expéditeur sélectionne une annonce et crée une réservation : 
POST /v1/api/reservations
{
  "annonceId": 42,
  "description": "Box of electronics",
  "poids": 5.0,
  "nombreColis": 1,
  "nomDestinataire": "Jean Dupont",
  "telephoneDestinataire": "+33612345678"
}
Réponse : réservation créée avec le statut EN_ATTENTE_PAIEMENT.

​
2. Paiement (Stripe Checkout)

Rediriger l’expéditeur vers la page Stripe Checkout : 
POST /v1/api/payments/checkout
{
  "reservationId": 123
}
Réponse : { "checkoutUrl": "https://checkout.stripe.com/..." } Le paiement est capturé immédiatement et conservé en entiercement (escrow) sur la plateforme.

​
3. Décision du transporteur

Une fois le paiement confirmé (RESERVATION_PAYEE → EN_ATTENTE), le transporteur peut :
  • Accepter : POST /v1/api/reservations/{id}/accepter → génère le QR code de dépôt
  • Refuser : POST /v1/api/reservations/{id}/refuser

​
4. Dépôt du colis (QR Code)

Lorsque l’expéditeur dépose le colis auprès du transporteur : 
POST /v1/api/qrcode/process-depot
{
  "reservationId": 123,
  "code": "ABC123"
}
Le statut passe à EN_COURS_DE_LIVRAISON.

​
5. Confirmation de livraison (QR Code)

Lorsque le transporteur remet le colis au destinataire : 
POST /v1/api/qrcode/process-livraison
{
  "reservationId": 123,
  "code": "XYZ789"
}
Le statut passe à LIVREE. Effets de bord :
  • Le transporteur reçoit son paiement (déduction de 15 % de commission plateforme) via un Stripe Transfer
  • Le solde du portefeuille du transporteur est mis à jour
  • Les deux parties sont notifiées
  • Le destinataire reçoit une confirmation WhatsApp

​
6. Annulation

Chacune des deux parties peut annuler sous certaines conditions : 
POST /v1/api/reservations/{id}/annuler
Les règles d’annulation varient selon le statut. Après EN_COURS_DE_LIVRAISON, l’annulation nécessite l’intervention d’un administrateur via un litige.