> ## 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.

# Annulations & refus

> Sc 3, 4, 5, 17 — annulations expéditeur, refus transporteur, blocage post-dépôt, destinataire absent.

Quatre scénarios couvrent les sorties non-nominales de la machine à états avant LIVREE.

## Sc 3 — Annulation pré-dépôt par expéditeur

```mermaid theme={null}
stateDiagram-v2
    EN_ATTENTE --> ANNULEE : sender cancels
    ACCEPTEE --> ANNULEE : sender cancels (pré-dépôt)
    ANNULEE --> [*]
    note right of ANNULEE
        Stripe refund FULL
        Pénalité timing-based
    end note
```

### Logique

* Annulation autorisée tant que **dépôt non effectué** (`EN_ATTENTE` ou `ACCEPTEE`)
* Pénalité timing-based selon le délai entre booking et annulation (commit `087b4f2`)
* Stripe refund 100% du `PaymentIntent` capturé

### Endpoint

```http theme={null}
POST /v1/api/bookings/{id}/cancel-with-refund
```

**Référence** : commit `087b4f2`

## Sc 4 — Refus transporteur

```mermaid theme={null}
sequenceDiagram
    actor C as Carrier
    participant API as Backend
    participant S as Stripe
    actor Sender

    C->>API: POST /v1/api/bookings/{id}/reject
    alt Statut CONFIRMED (post-capture)
        API->>S: refunds.create(payment_intent)
    else Statut AUTHORIZED_ESCROW (pré-capture)
        API->>S: payment_intents.cancel()
    end
    API->>API: Counter mensuel refus++ (JPA updatedAt proxy)
    alt Counter ≥ 3 ce mois
        API->>API: notifyTransporteurRefusSeuilAtteint
    end
    API-->>Sender: Push "Refusée par carrier" + refund 100%
    Note over API: → REFUSEE
```

### Anti-abus

* Compteur mensuel basé sur `updatedAt` JPA (zero migration)
* Seuil 3 refus / mois → alerte admin + email carrier
* 6 tests Mockito + 84 tests reservation verts

**Référence** : commit `3572e91`

## Sc 5 — Annulation post-dépôt → forcée vers litige

Si le sender tente d'annuler **après** le dépôt (état `EN_COURS_DE_LIVRAISON`), le système bloque l'annulation directe et **force l'ouverture d'un litige** : on ne peut plus rembourser sans intervention humaine car le colis est physiquement en transit.

```mermaid theme={null}
stateDiagram-v2
    EN_COURS_DE_LIVRAISON --> LITIGE : sender cancel post-dépôt
    LITIGE --> [*] : Resolution superadmin
    note right of LITIGE
        Hold Stripe
        Notif superadmin
        Modes: REFUND_FULL, REFUND_PARTIAL, REJECTED
    end note
```

**Référence** : commit `087b4f2` (mêmes commits que Sc 3 — gate timing-based)

## Sc 17 — Destinataire absent à la livraison

Le carrier arrive au point de livraison mais le recipient est absent. Le système autorise **3 tentatives maximum** avant de basculer le booking en échec.

```mermaid theme={null}
flowchart TD
    A[Carrier au point de livraison] --> B{Recipient présent ?}
    B -->|Oui| C[Scan QR livraison<br/>→ LIVREE]
    B -->|Non| D[POST /bookings/id/livraison-echouee]
    D --> E[counter tentativesLivraison++]
    E --> F{tentatives ≥ 3 ?}
    F -->|Non| G[Reprogrammer livraison<br/>Notif sender + recipient]
    F -->|Oui| H[LivraisonEpuiseeException<br/>HTTP 422 MAX_TENTATIVES_LIVRAISON_ATTEINTES]
    H --> I[Bascule LITIGE manuel]
```

### Endpoint

```http theme={null}
POST /v1/api/bookings/{id}/livraison-echouee
```

### Erreur après 3 tentatives

```json theme={null}
{
  "errorCode": "MAX_TENTATIVES_LIVRAISON_ATTEINTES",
  "status": 422,
  "message": "Nombre maximal de tentatives de livraison atteint"
}
```

### Tests

* 6 tests Mockito + 78 tests reservation verts

**Référence** : commit `f1c9bf7`

## Récap effets Stripe par scénario

| Scénario             | Action Stripe            | Pénalité ColisMove                  |
| -------------------- | ------------------------ | ----------------------------------- |
| Sc 3 (pré-dépôt)     | Refund 100%              | Timing-based (jusqu'à -10%)         |
| Sc 4 (refus carrier) | Refund 100%              | Aucune côté sender, counter carrier |
| Sc 5 (post-dépôt)    | Hold + résolution litige | Décidée superadmin                  |
| Sc 17 (3 échecs)     | Hold pending litige      | Décidée superadmin                  |