UC-08 — Carte perdue

Acteur : Agent / Gestionnaire But : Signaliser une carte perdue et bloquer son utilisation

Trigger

Un porteur signale la perte de sa carte.

Préconditions

• Permission card.update
• La carte existe et est active

Postconditions

• La carte est marquée lost (ou deactivated) et ne peut plus être utilisée
• Un motif est enregistré

Endpoints

Marquer la carte comme perdue

POST /api/v1/admin/org/cards/{id}/lost
Content-Type: application/json

{
  "reason": "Carte perdue signalée le 2025-06-10"
}

Désactiver la carte (alternative)

POST /api/v1/admin/org/cards/{id}/deactivate
Content-Type: application/json

{
  "reason": "Nouveau numéro requis"
}

Pas de « debit-lost »

L'endpoint /cards/{id}/debit-lost n'existe pas. La consommation du solde résiduel se fait via une transaction dédiée (debit_lost_card) ou une correction, séparément du blocage. Le blocage lui-même passe par /lost ou /deactivate.

Flow

sequenceDiagram
    participant Porteur
    participant Agent
    participant Dashboard
    participant API
    participant DB

    Porteur->>Agent: "J'ai perdu ma carte"
    Agent->>Dashboard: Rechercher la carte
    Dashboard->>API: GET /admin/org/cards/{id}
    API-->>Dashboard: {status: active, balance_cents: 4500}

    Agent->>Dashboard: Signaler la perte
    Dashboard->>API: POST /admin/org/cards/{id}/lost {reason}
    API->>DB: UPDATE cards SET status = 'lost'
    API-->>Dashboard: {message: "Carte marquée perdue", card: {...}}
    Dashboard->>Agent: "Carte bloquée ✓"

Exemple de réponse

{
  "message": "Carte marquée perdue",
  "card": {
    "id": "uuid",
    "code": "CL-EL-0008",
    "status": "lost",
    "balance_cents": 4500,
    "currency": "XOF"
  }
}

Permissions

Permission	Description
card.update	Modifier l'état d'une carte
card.debit.lost_card	(défini) consommer le solde d'une carte perdue

Erreurs

error_code	Description
NotFound	Carte introuvable
Validation	État incompatible
Forbidden	Permission insuffisante

Voir Cartes (Admin) pour le cycle de vie complet.