> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colismove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flux de réservation

> Cycle de vie complet d'une réservation de colis, de la création à la livraison

# 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> EN_ATTENTE_PAIEMENT: Sender creates booking
    EN_ATTENTE_PAIEMENT --> RESERVATION_PAYEE: Stripe payment captured
    EN_ATTENTE_PAIEMENT --> ERREUR_PAIEMENT: Payment fails
    RESERVATION_PAYEE --> EN_ATTENTE: Payment confirmed
    EN_ATTENTE --> ACCEPTEE: Carrier accepts
    EN_ATTENTE --> REFUSEE: Carrier rejects
    EN_ATTENTE --> ANNULEE: Sender cancels
    ACCEPTEE --> EN_COURS_DE_LIVRAISON: Deposit validated (QR code)
    ACCEPTEE --> ANNULEE: Either party cancels
    EN_COURS_DE_LIVRAISON --> LIVREE: Delivery validated (QR code)
    LIVREE --> [*]
```

## Étape par étape

### 1. Créer la réservation

L'expéditeur sélectionne une annonce et crée une réservation :

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
POST /v1/api/reservations/{id}/annuler
```

<Warning>
  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.
</Warning>