Skip to main content

​
Booking Flow

This guide explains the complete booking lifecycle, from a sender creating a booking to the carrier delivering the parcel.

​
State Machine

​
Step-by-Step

​
1. Create Booking

The sender selects an announcement and creates a booking: 
POST /v1/api/reservations
{
  "annonceId": 42,
  "description": "Box of electronics",
  "poids": 5.0,
  "nombreColis": 1,
  "nomDestinataire": "Jean Dupont",
  "telephoneDestinataire": "+33612345678"
}
Response: Booking created with status EN_ATTENTE_PAIEMENT.

​
2. Payment (Stripe Checkout)

Redirect the sender to the Stripe Checkout page: 
POST /v1/api/payments/checkout
{
  "reservationId": 123
}
Response: { "checkoutUrl": "https://checkout.stripe.com/..." } The payment is captured immediately and held in platform escrow.

​
3. Carrier Decision

Once payment is confirmed (RESERVATION_PAYEE → EN_ATTENTE), the carrier can:
  • Accept: POST /v1/api/reservations/{id}/accepter → generates deposit QR code
  • Reject: POST /v1/api/reservations/{id}/refuser

​
4. Parcel Deposit (QR Code)

When the sender deposits the parcel with the carrier: 
POST /v1/api/qrcode/process-depot
{
  "reservationId": 123,
  "code": "ABC123"
}
Status transitions to EN_COURS_DE_LIVRAISON.

​
5. Delivery Confirmation (QR Code)

When the carrier delivers the parcel to the recipient: 
POST /v1/api/qrcode/process-livraison
{
  "reservationId": 123,
  "code": "XYZ789"
}
Status transitions to LIVREE. Side effects:
  • Carrier receives payment (minus 15% platform fee) via Stripe Transfer
  • Carrier’s wallet balance is updated
  • Both parties are notified
  • The recipient receives a WhatsApp confirmation

​
6. Cancellation

Either party can cancel under certain conditions: 
POST /v1/api/reservations/{id}/annuler
Cancellation rules vary by status. After EN_COURS_DE_LIVRAISON, cancellation requires admin intervention via a dispute.