Cartes (utilisation)

Base URL : /api/v1/cards

Consultation des cartes et de leurs informations pour les utilisateurs d'une organisation. La gestion (création, cycle de vie, QR) est documentée dans Administration — Cartes.

---

POST /cards/resolve-qr

Résout un QR code scanné en informations de carte (sans données personnelles).

Permissions : card.read

Corps de la requête

Champ	Type	Requis	Description
qr_token	string	Oui	Jeton QR signé

POST /api/v1/cards/resolve-qr
Content-Type: application/json

{ "qr_token": "..." }

Réponse (200)

{
  "card_id": "uuid",
  "code": "CL-EL-0008",
  "card_number": "00042",
  "status": "active",
  "balance_cents": 4500,
  "card_holder_id": "uuid",
  "recent_transactions": [
    {
      "id": "uuid",
      "type": "credit_cash",
      "amount_cents": 5000,
      "balance_after_cents": 9500,
      "performed_by_user_id": "uuid",
      "metadata": {},
      "created_at": "2025-06-10T09:15:00Z"
    }
  ]
}

recent_transactions contient les 10 dernières transactions. Les montants sont en centimes bruts.

---

GET /cards/{id}/balance

Solde d'une carte.

Permissions : card.read

GET /api/v1/cards/{id}/balance

Réponse (200)

{
  "card_id": "uuid",
  "code": "CL-EL-0008",
  "card_number": "00042",
  "balance_cents": 4500
}

---

GET /cards/{id}/history

Historique des transactions d'une carte.

Permissions : card.read

Param	Type	Défaut	Description
limit	integer	10	Max 100
offset	integer	0

Réponse (200)

{
  "card_id": "uuid",
  "transactions": [
    {
      "id": "uuid",
      "type": "debit_purchase",
      "amount_cents": 1500,
      "balance_after_cents": 3500,
      "performed_by_user_id": "uuid",
      "performed_by_name": "Jean Mbeki",
      "created_at": "2025-06-10T09:15:00Z",
      "purchase_items": [
        { "name": "Café", "quantity": 1, "unit_price_cents": 1500 }
      ]
    }
  ],
  "total": 47
}

remarque

purchase_items n'est présent que pour type == "debit_purchase". Aucun champ currency n'est inclus ici.

---

GET /cards/{id}/daily-limit

Plafond journalier d'une carte et dépenses du jour.

Permissions : card.read

La journée est calculée selon le fuseau business_hours.timezone de l'organisation. Les dépenses prises en compte sont les debit_purchase et debit_reservation.

Réponse (200)

{
  "card_id": "uuid",
  "daily_limit_cents": 2000,
  "spent_today_cents": 1200,
  "remaining_limit_cents": 800,
  "daily_limit": 2000,
  "spent_today": 1200,
  "remaining_limit": 800,
  "currency": "XOF"
}

Si aucun plafond n'est configuré, les champs daily_limit_cents, remaining_limit_cents, daily_limit et remaining_limit valent null.

---

Consultation publique

GET /cards/public/{code}

Consultation publique d'une carte par son code (sans authentification). Résout l'organisation à partir du préfixe du code.

GET /api/v1/cards/public/CL-EL-0008

Réponse (200) :

{
  "code": "CL-EL-0008",
  "balance_cents": 4500,
  "status": "active",
  "holder": {
    "first_name": "Fatima",
    "last_name": "Kone",
    "establishment_name": "Cours Lumière"
  }
}

GET /cards/public/consult

Consultation publique étendue, acceptant code, token ou qr_hash (sans authentification).

Param	Type	Description
code	string	Code carte
token	string	Jeton QR (payload optionnellement signé)
qr_hash	string	Hash du QR

Réponse (200) :

{
  "code": "CL-EL-0008",
  "balance": 4500.0,
  "status": "active",
  "holder_first_name": "Fatima",
  "holder_last_name": "Kone",
  "establishment_name": "Cours Lumière"
}

Différence entre les deux endpoints

/cards/public/{code} retourne balance_cents (entier) et un objet holder imbriqué, tandis que /cards/public/consult retourne balance (décimal) et des champs porteur aplatis.

---

Voir aussi

• Administration — Cartes — CRUD, cycle de vie, QR, imports
• Administration — Porteurs — porteurs, imports, liens parent-enfant
• Transactions — recharges et achats