⚙️ API Admin

Documentation de l'API d'administration du système Commerce Tracking.

🎯 Vue d'ensemble

L'API Admin fournit les fonctionnalités d'administration du système, incluant la gestion des utilisateurs, des acteurs commerciaux et des données de référence.

Fonctionnalités

• Gestion des utilisateurs : Création, modification, suppression
• Gestion des acteurs : Administration des acteurs commerciaux
• Données de référence : Gestion des données communes
• Configuration système : Paramètres et configuration
• Audit et logs : Suivi des actions administratives

🔑 Authentification requise

Permissions requises : Rôle Superviseur (role_id: 5) ou Chef d'Équipe (role_id: 4) selon l'action.

Authorization: Bearer <jwt-token>

👥 Gestion des utilisateurs

POST /admin/users

Créer un nouvel utilisateur.

Request:

POST /admin/users
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "username": "new.user",
  "email": "new.user@example.com",
  "password": "securePassword123",
  "role_id": 3,
  "country_id": 1,
  "actor_id": 789
}

Response Success (201):

{
  "success": true,
  "message": "Utilisateur créé avec succès",
  "result": {
    "id": 124,
    "username": "new.user",
    "email": "new.user@example.com",
    "role_id": 3,
    "country_id": 1,
    "actor_id": 789,
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "errors": null,
  "except": null
}

GET /admin/users

Lister les utilisateurs avec pagination et filtres.

Query Parameters:

GET /admin/users?page=1&limit=10&role_id=3&country_id=1&is_active=true

Response Success (200):

{
  "success": true,
  "message": "Utilisateurs récupérés avec succès",
  "result": {
    "data": [
      {
        "id": 123,
        "username": "john.doe",
        "email": "john.doe@example.com",
        "role_id": 4,
        "role_name": "Chef d'Équipe",
        "country_id": 1,
        "country_name": "République Démocratique du Congo",
        "actor_id": 456,
        "actor_name": "John Doe",
        "is_active": true,
        "last_login": "2024-01-15T09:00:00Z",
        "created_at": "2024-01-01T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 45,
      "total_pages": 5
    }
  },
  "errors": null,
  "except": null
}

GET /admin/users/:id

Récupérer un utilisateur spécifique.

Request:

GET /admin/users/123
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Utilisateur récupéré avec succès",
  "result": {
    "id": 123,
    "username": "john.doe",
    "email": "john.doe@example.com",
    "role_id": 4,
    "role_name": "Chef d'Équipe",
    "country_id": 1,
    "country_name": "République Démocratique du Congo",
    "actor_id": 456,
    "actor": {
      "id": 456,
      "actor_role": "Trade Officer",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+243 123 456 789"
    },
    "is_active": true,
    "last_login": "2024-01-15T09:00:00Z",
    "created_at": "2024-01-01T08:00:00Z",
    "updated_at": "2024-01-15T09:00:00Z"
  },
  "errors": null,
  "except": null
}

PUT /admin/users/:id

Modifier un utilisateur existant.

Request:

PUT /admin/users/123
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "email": "john.doe.updated@example.com",
  "role_id": 5,
  "is_active": false
}

DELETE /admin/users/:id

Supprimer un utilisateur.

Request:

DELETE /admin/users/123
Authorization: Bearer <jwt-token>

🏢 Gestion des acteurs

POST /admin/actors

Créer un nouvel acteur commercial.

Request:

POST /admin/actors
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "actor_role": "Trade Officer",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+243 987 654 321",
  "country_id": 1,
  "specialization": "Agricultural Products",
  "experience_years": 5
}

Response Success (201):

{
  "success": true,
  "message": "Acteur créé avec succès",
  "result": {
    "id": 790,
    "actor_role": "Trade Officer",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+243 987 654 321",
    "country_id": 1,
    "specialization": "Agricultural Products",
    "experience_years": 5,
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "errors": null,
  "except": null
}

GET /admin/actors

Lister les acteurs avec filtres.

Query Parameters:

GET /admin/actors?page=1&limit=10&actor_role=Trade Officer&country_id=1&is_active=true

Response Success (200):

{
  "success": true,
  "message": "Acteurs récupérés avec succès",
  "result": {
    "data": [
      {
        "id": 456,
        "actor_role": "Trade Officer",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone": "+243 123 456 789",
        "country_id": 1,
        "country_name": "République Démocratique du Congo",
        "specialization": "Agricultural Products",
        "experience_years": 8,
        "is_active": true,
        "created_at": "2024-01-01T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "total_pages": 3
    }
  },
  "errors": null,
  "except": null
}

GET /admin/actors/:id

Récupérer un acteur spécifique.

Request:

GET /admin/actors/456
Authorization: Bearer <jwt-token>

PUT /admin/actors/:id

Modifier un acteur existant.

Request:

PUT /admin/actors/456
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "phone": "+243 123 456 789",
  "specialization": "Livestock Products",
  "experience_years": 10
}

DELETE /admin/actors/:id

Supprimer un acteur.

Request:

DELETE /admin/actors/456
Authorization: Bearer <jwt-token>

📊 Données de référence

GET /admin/reference-data

Lister les données de référence avec gestion.

Query Parameters:

GET /admin/reference-data?type=country&page=1&limit=20

Response Success (200):

{
  "success": true,
  "message": "Données de référence récupérées avec succès",
  "result": {
    "data": [
      {
        "id": 1,
        "type": "country",
        "code": "CD",
        "name": "République Démocratique du Congo",
        "name_en": "Democratic Republic of the Congo",
        "metadata": {
          "iso_code": "COD",
          "region": "Central Africa",
          "currency_code": "CDF"
        },
        "is_active": true,
        "created_at": "2024-01-01T08:00:00Z",
        "updated_at": "2024-01-01T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 195,
      "total_pages": 10
    }
  },
  "errors": null,
  "except": null
}

POST /admin/reference-data

Créer une nouvelle donnée de référence.

Request:

POST /admin/reference-data
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "type": "currency",
  "code": "XAF",
  "name": "Franc CFA",
  "name_en": "CFA Franc",
  "metadata": {
    "symbol": "FCFA",
    "decimal_places": 0,
    "region": "Central Africa"
  }
}

PUT /admin/reference-data/:id

Modifier une donnée de référence.

Request:

PUT /admin/reference-data/5
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "name": "Franc CFA BEAC",
  "metadata": {
    "symbol": "FCFA",
    "decimal_places": 0,
    "region": "Central Africa",
    "central_bank": "BEAC"
  }
}

DELETE /admin/reference-data/:id

Supprimer une donnée de référence.

Request:

DELETE /admin/reference-data/5
Authorization: Bearer <jwt-token>

⚙️ Configuration système

GET /admin/config

Récupérer la configuration système.

Request:

GET /admin/config
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Configuration récupérée avec succès",
  "result": {
    "system": {
      "name": "Commerce Tracking",
      "version": "1.0.0",
      "environment": "production",
      "maintenance_mode": false
    },
    "features": {
      "digital_collections": true,
      "mobile_app": true,
      "reports_generation": true,
      "email_notifications": true
    },
    "limits": {
      "max_collections_per_day": 100,
      "max_file_size_mb": 10,
      "session_timeout_minutes": 60,
      "password_expiry_days": 90
    },
    "integrations": {
      "email_service": "smtp",
      "sms_service": "disabled",
      "backup_service": "enabled"
    }
  },
  "errors": null,
  "except": null
}

PUT /admin/config

Modifier la configuration système.

Request:

PUT /admin/config
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "features": {
    "email_notifications": false
  },
  "limits": {
    "max_collections_per_day": 150,
    "session_timeout_minutes": 120
  }
}

📋 Audit et logs

GET /admin/audit-logs

Récupérer les logs d'audit.

Query Parameters:

GET /admin/audit-logs?page=1&limit=20&user_id=123&action=create&date_from=2024-01-01&date_to=2024-01-31

Response Success (200):

{
  "success": true,
  "message": "Logs d'audit récupérés avec succès",
  "result": {
    "data": [
      {
        "id": 1001,
        "user_id": 123,
        "user_name": "john.doe",
        "action": "create",
        "resource_type": "user",
        "resource_id": 124,
        "resource_name": "new.user",
        "details": {
          "fields_modified": ["username", "email", "role_id"],
          "old_values": null,
          "new_values": {
            "username": "new.user",
            "email": "new.user@example.com",
            "role_id": 3
          }
        },
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 500,
      "total_pages": 25
    }
  },
  "errors": null,
  "except": null
}

GET /admin/system-stats

Récupérer les statistiques système.

Request:

GET /admin/system-stats
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Statistiques système récupérées avec succès",
  "result": {
    "users": {
      "total": 45,
      "active": 42,
      "inactive": 3,
      "by_role": {
        "agent": 35,
        "team_manager": 8,
        "supervisor": 2
      }
    },
    "actors": {
      "total": 125,
      "active": 120,
      "inactive": 5
    },
    "collections": {
      "total": 15000,
      "today": 45,
      "this_month": 1250,
      "by_status": {
        "draft": 150,
        "submitted": 25,
        "validated": 14000,
        "rejected": 825
      }
    },
    "system": {
      "uptime_hours": 720,
      "database_size_mb": 250,
      "cache_hit_rate": 0.85,
      "average_response_time_ms": 150
    }
  },
  "errors": null,
  "except": null
}

🛠️ Gestion des erreurs

Erreurs d'autorisation

{
  "success": false,
  "message": "Permissions insuffisantes",
  "result": null,
  "errors": ["Seuls les superviseurs peuvent créer des utilisateurs"],
  "except": null
}

Erreurs de validation

{
  "success": false,
  "message": "Erreur de validation",
  "result": null,
  "errors": [
    "L'email doit être valide",
    "Le rôle doit être spécifié",
    "Le pays est requis"
  ],
  "except": null
}

Erreurs de ressource

{
  "success": false,
  "message": "Ressource non trouvée",
  "result": null,
  "errors": ["Utilisateur avec l'ID 999 non trouvé"],
  "except": null
}

🔐 Permissions par action

Action	Permission requise	Description
Lire utilisateurs	Chef d'Équipe (4)	Voir les utilisateurs de son équipe
Lire tous utilisateurs	Superviseur (5)	Voir tous les utilisateurs
Créer utilisateur	Superviseur (5)	Créer de nouveaux utilisateurs
Modifier utilisateur	Chef d'Équipe (4)	Modifier utilisateurs de son équipe
Supprimer utilisateur	Superviseur (5)	Supprimer des utilisateurs
Gestion acteurs	Chef d'Équipe (4)	Gérer les acteurs commerciaux
Configuration système	Superviseur (5)	Modifier la configuration
Logs d'audit	Superviseur (5)	Accéder aux logs d'audit

---

Cette API Admin fournit un contrôle complet sur l'administration du système Commerce Tracking avec des permissions granulaires et un suivi d'audit complet.