Skip to main content

🔌 API Reference - Vue d'ensemble

FreeTrade expose une API REST complète avec 163 endpoints organisés en modules logiques pour une utilisation intuitive.

🎯 Caractéristiques de l'API​

Standards respectés​

  • REST : Architecture RESTful avec verbes HTTP appropriés
  • JSON : Format d'échange standardisé
  • HTTP Status Codes : Codes de statut sémantiques
  • Pagination : Pagination standardisée sur toutes les listes
  • Filtering : Filtres avancés et recherche textuelle

Authentification​

  • JWT Bearer Token : Authentification sécurisée
  • Cache intelligent : Performance optimisée
  • Gestion des erreurs : Messages d'erreur explicites
  • Audit trail : Traçabilité complète

📊 Structure de l'API​

Base URL​

https://api.freetrade.cm
# ou en développement
http://localhost:3004

Format de réponse standardisé​

Réponse de succès​

{
  "success": true,
  "message": "Opération réussie",
  "result": {
    "data": [...],
    "meta": {
      "total": 100,
      "current_page": 1,
      "total_pages": 10,
      "limit": 10
    }
  },
  "errors": null,
  "except": null
}

Réponse d'erreur​

{
  "success": false,
  "message": "Message d'erreur descriptif",
  "result": null,
  "errors": ["Détails des erreurs de validation"],
  "except": "Exception technique (si applicable)"
}

🔐 Authentification​

Obtenir un token​

POST /auth/login
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "password123"
}

Utiliser le token​

Authorization: Bearer <access_token>

Endpoints d'authentification​

  • POST /auth/login - Connexion utilisateur
  • GET /auth/profile - Profil utilisateur authentifié

📋 Modules disponibles​

👨‍💼 Modules Admin (115 endpoints)​

👥 Actors (25 endpoints)​

Gestion centralisée des acteurs du système

  • Admins : /admin/actors/admins/*
  • Agents : /admin/actors/agents/*
  • Customers : /admin/actors/customers/*
  • Statistiques : /admin/actors/stats

👤 Users (12 endpoints)​

Gestion des utilisateurs et sessions

  • CRUD : /admin/users/*
  • Sessions : /admin/users/sessions/*
  • Mots de passe : /admin/users/{id}/password

🏢 Organizations (5 endpoints)​

Gestion des organisations

  • CRUD : /admin/organizations/*
  • Hiérarchie : Support parent-enfant

📋 Complaints (9 endpoints)​

Système de gestion des plaintes

  • CRUD : /admin/complaints/*
  • Statistiques : /admin/complaints/stats
  • Statuts : /admin/complaints/{id}/status

🚛 Transports (8 endpoints)​

Gestion des transports et véhicules

  • CRUD : /admin/transports/*
  • Attribution : /admin/transports/{id}/assign-customer
  • Statistiques : /admin/transports/stats

💬 Forum (6 endpoints)​

Modération du forum communautaire

  • Messages signalés : /admin/forum/reported-messages/*
  • Modération : /admin/forum/*/moderate
  • Statistiques : /admin/forum/stats

⚙️ Configurations (42 endpoints)​

Gestion centralisée des configurations

  • Catégories : /admin/configurations/categories/*
  • Types de plaintes : /admin/configurations/complaint-types/*
  • Rôles : /admin/configurations/roles/*
  • Tags : /admin/configurations/tags/*
  • Types de véhicules : /admin/configurations/vehicle-types/*
  • Pays/États : /admin/configurations/countries/*, /admin/configurations/states/*

📢 Announcements (8 endpoints)​

Gestion des annonces système

  • CRUD : /admin/announcements/*
  • Publication : /admin/announcements/{id}/publish
  • Actions en lot : /admin/announcements/bulk-action

🚀 Modules Trade (46 endpoints)​

📋 Trade Complaints (8 endpoints)​

Plaintes côté utilisateur

  • CRUD : /trade/complaints/*
  • Types : /trade/complaints/types
  • Upload : /trade/complaints/upload

🚛 Trade Transports (7 endpoints)​

Création et gestion des transports

  • CRUD : /trade/transports/*
  • Types de véhicules : /trade/transports/vehicle-types
  • Upload : /trade/transports/upload

💬 Trade Forum (21 endpoints)​

Forum communautaire complet

  • Topics : /trade/forum/topics/*
  • Messages : /trade/forum/messages/*
  • Catégories : /trade/forum/categories/*
  • Tags : /trade/forum/tags/*
  • Interactions : Likes, signalements

📢 Trade Announcements (5 endpoints)​

Annonces utilisateur

  • CRUD : /trade/announcements/*

📚 Trade Tutorials (5 endpoints)​

Tutoriels et guides

  • CRUD : /trade/tutorials/*

🔍 Paramètres de requête communs​

Pagination​

GET /admin/users?page=1&limit=10

Recherche​

GET /admin/users?search=john

Filtres​

GET /admin/complaints?status=PENDING&countryId=1&startDate=2024-01-01

Tri​

GET /admin/announcements?sortBy=createdAt&sortOrder=DESC

📝 Exemples d'utilisation​

Créer un utilisateur​

curl -X POST http://localhost:3004/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john.doe",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "password": "password123",
    "confirmPassword": "password123",
    "roleId": 1
  }'

Lister les transports avec filtres​

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3004/admin/transports?page=1&limit=5&vehicleTypeId=1&loadingPoint=Douala"

Créer une plainte​

curl -X POST http://localhost:3004/trade/complaints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transportId": 123,
    "complaintTypeId": 1,
    "label": "Retard de livraison",
    "description": "Transport en retard de 3 heures",
    "location": "Yaoundé"
  }'

🚨 Gestion des erreurs​

Codes de statut HTTP​

  • 200 OK : Opération réussie
  • 201 CREATED : Ressource créée
  • 400 BAD REQUEST : Données invalides
  • 401 UNAUTHORIZED : Non authentifié
  • 403 FORBIDDEN : Accès refusé
  • 404 NOT FOUND : Ressource non trouvée
  • 409 CONFLICT : Conflit (ex: email déjà utilisé)
  • 500 INTERNAL SERVER ERROR : Erreur serveur

Exemples d'erreurs​

Erreur de validation​

{
  "success": false,
  "message": "Données de validation invalides",
  "errors": [
    "email must be an email",
    "password must be longer than or equal to 6 characters"
  ]
}

Erreur d'authentification​

{
  "success": false,
  "message": "Token invalide ou expiré",
  "errors": ["UNAUTHORIZED"]
}

📊 Limites et quotas​

Rate Limiting​

  • Authentifié : 1000 requêtes/heure
  • Non authentifié : 100 requêtes/heure
  • Admin : 5000 requêtes/heure

Taille des requêtes​

  • JSON : 10 MB maximum
  • Upload de fichiers : 50 MB maximum
  • Pagination : 100 éléments maximum par page

🔧 Outils de développement​

Collection Postman​

Téléchargez la collection complète : FreeTrade API Collection

SDK et clients​

  • JavaScript/TypeScript : Client officiel disponible
  • Python : Wrapper en développement
  • cURL : Exemples dans chaque section

Environnements​

  • Développement : http://localhost:3004
  • Staging : https://staging-api.freetrade.cm
  • Production : https://api.freetrade.cm

Explorez les sections détaillées :