Cartes (Administration)

Base URL : /api/v1/admin/org/cards

Gestion complète des cartes : création, cycle de vie, attribution aux porteurs, QR codes et imports. Les porteurs eux-mêmes sont gérés dans Cartes — Porteurs.

---

Statuts de carte

Statut	Description
unassigned	Créée, non attribuée
active	Attribuée et utilisable
deactivated	Désactivée
lost	Déclarée perdue

---

Cycle de vie

stateDiagram-v2
    [*] --> unassigned: POST /cards
    unassigned --> active: POST /cards/{id}/assign
    active --> deactivated: POST /cards/{id}/deactivate
    active --> lost: POST /cards/{id}/lost
    deactivated --> active: POST /cards/{id}/activate
    lost --> active: POST /cards/{id}/activate
    active --> active: POST /cards/{id}/reassign

---

GET /admin/org/cards

Liste paginée des cartes.

Permissions : card.read

Param	Type	Défaut	Description
search	string	—	Recherche (code, numéro, porteur)
status	string	—	unassigned, active, deactivated, lost
limit	integer	20	Éléments par page
offset	integer	0	Décalage

Réponse (200) :

{
  "items": [
    {
      "id": "uuid",
      "code": "CL-EL-0008",
      "card_number": "6287940000123456",
      "status": "active",
      "balance_cents": 5000,
      "balance": 5000,
      "balance_formatted": "5 000 FCFA",
      "card_holder_id": "uuid",
      "card_holder": {
        "id": "uuid",
        "first_name": "Fatou",
        "last_name": "Diallo",
        "establishment_name": null,
        "code": "CL-EL-0008"
      },
      "created_at": "2025-01-10T10:00:00Z"
    }
  ],
  "total": 150,
  "currency": "XOF"
}

---

POST /admin/org/cards

Crée une carte, éventuellement avec un porteur inline.

Permissions : card.create

Corps de la requête

Champ	Type	Requis	Description
card_number	string	Non	Numéro (auto si absent)
holder_id	uuid	Non	Porteur existant à attribuer
holder	object	Non	Porteur inline (prioritaire sur holder_id)
holder.establishment_name	string	Oui*	Établissement
holder.last_name	string	Oui*	Nom
holder.first_name	string	Oui*	Prénom
holder.phone_number	string	Oui*	Téléphone
holder.email	string	Non	Email
holder.holder_type	string	Non	Type de porteur (défaut other)
holder.password	string	Non	Mot de passe (auto-généré sinon)

POST /api/v1/admin/org/cards
Content-Type: application/json

{
  "holder": {
    "establishment_name": "Cours Lumière",
    "last_name": "Diallo",
    "first_name": "Fatou",
    "phone_number": "+22890123456"
  }
}

Réponse (201) :

{
  "id": "uuid",
  "code": "CL-EL-0008",
  "card_number": "6287940000123456",
  "status": "active",
  "balance_cents": 0,
  "balance": 0,
  "balance_formatted": "0 FCFA",
  "card_holder_id": "uuid",
  "created_at": "2025-01-10T10:00:00Z",
  "password": "a1b2c3d4e5f6"
}

Champ password

password n'est présent que lorsqu'un porteur inline a été créé avec un mot de passe généré.

---

GET /admin/org/cards/{id}

Détail d'une carte.

Permissions : card.read

Réponse (200) :

{
  "id": "uuid",
  "code": "CL-EL-0008",
  "card_number": "6287940000123456",
  "card_holder_id": "uuid",
  "holder_name": "Fatou Diallo",
  "status": "active",
  "balance_cents": 5000,
  "balance": 5000,
  "balance_formatted": "5 000 FCFA",
  "activated_at": "2025-01-10T10:00:00Z",
  "deactivated_at": null,
  "deactivated_reason": null,
  "metadata": {},
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z",
  "currency": "XOF"
}

---

PUT /admin/org/cards/{id}

Met à jour une carte.

Permissions : card.update

Champ	Type	Description
card_number	string	Numéro
metadata	object	Métadonnées
daily_limit_cents	integer	Plafond journalier (≤ 0 retire le plafond)

Réponse (200) : { "message": "Carte mise à jour", "card": {...} }

---

DELETE /admin/org/cards/{id}

Permissions : card.delete

Réponse (200) : { "message": "Carte supprimée" }

---

Attribution et cycle de vie

POST /admin/org/cards/{id}/assign

Attribue la carte à un porteur.

Permissions : card.update

{ "holder_id": "uuid" }

Réponse (200) : { "message": "Carte attribuée", "card": {...} }

POST /admin/org/cards/{id}/reassign

Réattribue la carte à un autre porteur.

Permissions : card.update

{ "holder_id": "uuid" }

Réponse (200) : { "message": "Carte réassignée", "card": {...} }

POST /admin/org/cards/{id}/revoke

Révoque le propriétaire actuel de la carte.

Permissions : card.update

Réponse (200) : { "message": "Propriétaire révoqué de la carte", "card": {...} }

POST /admin/org/cards/{id}/deactivate

Désactive la carte.

Permissions : card.update

{ "reason": "Carte endommagée" }

Réponse (200) : { "message": "Carte désactivée", "card": {...} }

POST /admin/org/cards/{id}/lost

Marque la carte comme perdue.

Permissions : card.update

{ "reason": "Déclarée perdue par le porteur" }

Réponse (200) : { "message": "Carte marquée perdue", "card": {...} }

POST /admin/org/cards/{id}/activate

Réactive une carte.

Permissions : card.update

Réponse (200) : { "message": "Carte réactivée", "card": {...} }

---

QR codes et visuels

GET /admin/org/cards/{id}/qr

Retourne le QR code de la carte en PNG.

Permissions : card.read Type MIME : image/png (Content-Disposition: attachment; filename="{code}.png")

GET /admin/org/cards/{id}/card

Retourne la carte formatée (350×500) en PNG.

Permissions : card.read Type MIME : image/png (filename="card_{code}.png")

POST /admin/org/cards/qr-export

Retourne les QR codes de plusieurs cartes en base64 (max 500).

Permissions : card.read

{ "card_ids": ["uuid", "uuid"] }

Réponse (200) :

{
  "items": [
    { "card_id": "uuid", "code": "CL-EL-0008", "png_base64": "iVBORw0KGgo..." }
  ]
}

POST /admin/org/cards/qr-export/zip

Retourne une archive ZIP des QR codes.

Permissions : card.read Type MIME : application/zip (entrées qr_codes/{code}.png)

POST /admin/org/cards/cards-export/zip

Retourne une archive ZIP des cartes formatées.

Permissions : card.read Type MIME : application/zip (entrées cards/{code}.png)

---

POST /admin/org/cards/import

Importe des cartes en lot (max 500).

Permissions : card.create

{
  "cards": [
    {
      "card_number": "6287940000123456",
      "code": "CL-EL-0009",
      "holder_id": "uuid",
      "status": "active",
      "daily_limit_cents": 2000
    }
  ]
}

Réponse (200) :

{
  "message": "3 cartes importées",
  "created": 3,
  "cards": [ ],
  "currency": "XOF"
}

---

Permissions

Permission	Description
card.read	Lecture des cartes et QR codes
card.create	Création et import
card.update	Modification, attribution, cycle de vie
card.delete	Suppression
card.manage	Super-permission couvrant toutes les opérations