Aller au contenu principal

Porteurs de cartes (Administration)

Base URL : /api/v1/admin/org

Gestion des porteurs de cartes (élèves, personnel, parents), imports Excel et liens parent-enfant.

Types de porteurs​

Type (holder_type)Description
studentÉlève
employeeEmployé
professorEnseignant
parentParent
otherAutre (défaut)

GET /admin/org/cards/holders​

Liste paginée des porteurs.

Permissions : card.read

ParamTypeDéfautDescription
searchstring—Recherche (nom, code)
holder_typestring—Filtrer par type
limitinteger20Éléments par page
offsetinteger0Décalage

Réponse (200) :

{
  "items": [
    {
      "id": "uuid",
      "establishment_name": "Cours Lumière",
      "last_name": "Diallo",
      "first_name": "Fatou",
      "email": "fatou@example.com",
      "code": "CL-EL-0008",
      "holder_type": "student",
      "created_at": "2025-01-10T10:00:00Z"
    }
  ],
  "total": 320
}

POST /admin/org/cards/holders​

Crée un porteur.

Permissions : card_holder.create

ChampTypeRequisDescription
establishment_namestringOuiÉtablissement
last_namestringOuiNom
first_namestringOuiPrénom
phone_numberstringOuiTéléphone
emailstringNonEmail
holder_typestringNonType (défaut other)
passwordstringNonMot de passe (auto-généré sinon)

Réponse (201) :

{
  "id": "uuid",
  "establishment_name": "Cours Lumière",
  "last_name": "Diallo",
  "first_name": "Fatou",
  "email": "fatou@example.com",
  "code": "CL-EL-0008",
  "login_identifier": "CL-EL-0008",
  "password": "a1b2c3d4e5f6",
  "holder_type": "student",
  "created_at": "2025-01-10T10:00:00Z"
}

GET /admin/org/cards/holders/{id}​

Détail d'un porteur.

Permissions : card.read

Réponse (200) :

{
  "id": "uuid",
  "establishment_name": "Cours Lumière",
  "last_name": "Diallo",
  "first_name": "Fatou",
  "phone_number": "+22890123456",
  "email": "fatou@example.com",
  "code": "CL-EL-0008",
  "holder_type": "student",
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z"
}

PUT /admin/org/cards/holders/{id}​

Met à jour un porteur.

Permissions : card_holder.update

ChampTypeRequis
establishment_namestringOui
last_namestringOui
first_namestringOui
phone_numberstringOui
emailstringNon
holder_typestringOui

Réponse (200) : { id, establishment_name, last_name, first_name, email, code, holder_type, created_at }

DELETE /admin/org/cards/holders/{id}​

Permissions : card_holder.delete

Réponse (200) : { "deleted": true }

Cartes et réservations d'un porteur​

GET /admin/org/cards/holders/{id}/cards​

Permissions : card.read

{
  "items": [
    {
      "id": "uuid",
      "code": "CL-EL-0008",
      "card_number": "6287940000123456",
      "status": "active",
      "balance_cents": 5000,
      "balance": 5000,
      "balance_formatted": "5 000 FCFA",
      "currency": "XOF",
      "created_at": "2025-01-10T10:00:00Z"
    }
  ],
  "currency": "XOF"
}

GET /admin/org/cards/holders/{id}/reservations​

Permissions : reservation.read

{
  "items": [
    {
      "id": "uuid",
      "product_id": "uuid",
      "quantity": 1,
      "total_price_cents": 1200,
      "total_price": 1200,
      "total_price_formatted": "1 200 FCFA",
      "for_date": "2025-06-21",
      "status": "pending",
      "created_at": "2025-06-20T10:00:00Z"
    }
  ],
  "currency": "XOF"
}

POST /admin/org/cards/holders/{id}/reset-password​

Réinitialise le mot de passe du porteur.

Permissions : card_holder.create

Réponse (200) : { "password": "a1b2c3d4e5f6" }

Imports Excel​

POST /admin/org/card-holders/import-students​

Importe des élèves (et crée les parents associés).

Permissions : card_holder.create Type : multipart/form-data, champ file (fichier .xlsx)

Colonnes attendues :

ColContenu
BNom
CPrénom
DClasse
ESexe
FDate de naissance
GEmail
HAllergies
IEmails parents (séparés par virgule)
JNoms parents (séparés par virgule)
KPrénoms parents (séparés par virgule)

Réponse (200) :

{
  "message": "Import terminé: 45 élèves, 30 parents",
  "summary": {
    "students_created": 45,
    "students_skipped": 2,
    "parents_created": 30,
    "parents_reused": 8,
    "cards_created": 45,
    "links_created": 40
  },
  "errors": [
    { "row": 12, "student": "Diallo Aïcha", "ok": false, "message": "Classe manquante" }
  ]
}

POST /admin/org/card-holders/import-staff​

Importe du personnel.

Permissions : card_holder.create Type : multipart/form-data, champ file (.xlsx)

Colonnes : B Nom, C Prénoms, D Sexe, E Email, F Téléphone, G Catégorie (→ establishment_name).

Réponse (200) :

{
  "message": "Import terminé: 20 personnels, 20 cartes",
  "summary": { "staff_created": 20, "staff_skipped": 1, "cards_created": 20 },
  "errors": []
}

Liens parent-enfant​

GET /admin/org/card-holders/{parent_id}/children​

Enfants liés à un parent.

Permissions : card_link.read

ParamTypeDéfaut
limitinteger20
offsetinteger0

Réponse (200) : { "items": [CardHolder], "total": 2 }

POST /admin/org/card-holders/{parent_id}/children​

Lie un enfant à un parent.

Permissions : card_link.create

{
  "child_id": "uuid",
  "relation": "father"
}

Réponse (201) :

{
  "message": "Lien parent-enfant créé",
  "link": {
    "id": "uuid",
    "parent_id": "uuid",
    "child_id": "uuid",
    "relation": "father",
    "created_at": "2025-06-01T10:00:00Z"
  }
}

DELETE /admin/org/card-holders/{parent_id}/children/{child_id}​

Supprime un lien parent-enfant.

Permissions : card_link.delete

Réponse (200) : { "message": "Lien parent-enfant supprimé" }

Liste des liens parent-enfant groupés.

Permissions : card_link.read

ParamTypeDéfaut
searchstring—
limitinteger20
offsetinteger0

Réponse (200) :

{
  "items": [
    {
      "parent": { "id": "uuid", "first_name": "Moussa", "last_name": "Diallo" },
      "children": [
        { "id": "uuid", "first_name": "Aïcha", "last_name": "Diallo" }
      ]
    }
  ],
  "total": 30
}

Permissions​

PermissionDescription
card.readLecture des porteurs et cartes
card_holder.createCréation, import, reset password
card_holder.updateModification
card_holder.deleteSuppression
card_link.read / card_link.create / card_link.deleteLiens parent-enfant