Aller au contenu principal

📊 API Common Data

Documentation de l'API des données de référence communes.

🎯 Vue d'ensemble​

L'API Common Data fournit l'accès aux données de référence utilisées dans tout le système Commerce Tracking. Ces données sont mises en cache pour optimiser les performances.

Fonctionnalités​

  • Données de référence : Pays, devises, langues, rôles, saisons, unités
  • Données géographiques : Régions, districts, villes, corridors, points de contrôle
  • Produits et animaux : Catalogue des produits et types d'animaux
  • Transport et services : Modes et méthodes de transport, services disponibles
  • Cache intelligent : Mise en cache automatique pour les performances

🔑 Authentification requise​

Tous les endpoints nécessitent un token JWT valide :

Authorization: Bearer <jwt-token>

🌍 Données de référence​

GET /common-data/countries​

Récupérer la liste des pays.

Request:

GET /common-data/countries
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Pays récupérés avec succès",
  "result": [
    {
      "id": 1,
      "code": "CD",
      "name": "République Démocratique du Congo",
      "name_en": "Democratic Republic of the Congo",
      "iso_code": "COD",
      "region": "Central Africa",
      "currency_code": "CDF",
      "is_active": true
    },
    {
      "id": 2,
      "code": "RW",
      "name": "Rwanda",
      "name_en": "Rwanda",
      "iso_code": "RWA",
      "region": "East Africa",
      "currency_code": "RWF",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/currencies​

Récupérer la liste des devises.

Request:

GET /common-data/currencies
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Devises récupérées avec succès",
  "result": [
    {
      "id": 1,
      "code": "CDF",
      "name": "Franc Congolais",
      "symbol": "FC",
      "decimal_places": 2,
      "is_active": true
    },
    {
      "id": 2,
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimal_places": 2,
      "is_active": true
    },
    {
      "id": 3,
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimal_places": 2,
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/languages​

Récupérer la liste des langues.

Request:

GET /common-data/languages
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Langues récupérées avec succès",
  "result": [
    {
      "id": 1,
      "code": "fr",
      "name": "Français",
      "name_native": "Français",
      "is_active": true
    },
    {
      "id": 2,
      "code": "en",
      "name": "English",
      "name_native": "English",
      "is_active": true
    },
    {
      "id": 3,
      "code": "sw",
      "name": "Kiswahili",
      "name_native": "Kiswahili",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/roles​

Récupérer la liste des rôles système.

Request:

GET /common-data/roles
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Rôles récupérés avec succès",
  "result": [
    {
      "id": 3,
      "name": "Agent",
      "name_en": "Agent",
      "level": 1,
      "description": "Utilisateur de base avec accès limité",
      "permissions": [
        "collections:create",
        "collections:read:own",
        "collections:update:own",
        "collections:delete:own"
      ],
      "is_active": true
    },
    {
      "id": 4,
      "name": "Chef d'Équipe",
      "name_en": "Team Manager",
      "level": 2,
      "description": "Superviseur niveau 1 avec validation",
      "permissions": [
        "collections:create",
        "collections:read:team",
        "collections:update:team",
        "collections:validate:level_1",
        "reports:read:team"
      ],
      "is_active": true
    },
    {
      "id": 5,
      "name": "Superviseur",
      "name_en": "Supervisor",
      "level": 3,
      "description": "Superviseur niveau 2 avec accès complet",
      "permissions": [
        "collections:create",
        "collections:read:all",
        "collections:update:all",
        "collections:validate:level_2",
        "users:manage",
        "reports:read:all",
        "system:configure"
      ],
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/seasons​

Récupérer la liste des saisons.

Request:

GET /common-data/seasons
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Saisons récupérées avec succès",
  "result": [
    {
      "id": 1,
      "name": "Saison sèche",
      "name_en": "Dry Season",
      "start_month": 5,
      "end_month": 9,
      "description": "Période de faible précipitation",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Saison des pluies",
      "name_en": "Rainy Season",
      "start_month": 10,
      "end_month": 4,
      "description": "Période de forte précipitation",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/unities​

Récupérer la liste des unités de mesure.

Request:

GET /common-data/unities
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Unités récupérées avec succès",
  "result": [
    {
      "id": 1,
      "code": "kg",
      "name": "Kilogramme",
      "name_en": "Kilogram",
      "category": "weight",
      "symbol": "kg",
      "conversion_factor": 1.0,
      "is_active": true
    },
    {
      "id": 2,
      "code": "ton",
      "name": "Tonne",
      "name_en": "Tonne",
      "category": "weight",
      "symbol": "t",
      "conversion_factor": 1000.0,
      "is_active": true
    },
    {
      "id": 3,
      "code": "piece",
      "name": "Pièce",
      "name_en": "Piece",
      "category": "count",
      "symbol": "pcs",
      "conversion_factor": 1.0,
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

🗺️ Données géographiques​

GET /common-data/regions​

Récupérer la liste des régions.

Request:

GET /common-data/regions?country_id=1
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Régions récupérées avec succès",
  "result": [
    {
      "id": 1,
      "name": "Kinshasa",
      "name_en": "Kinshasa",
      "country_id": 1,
      "code": "KIN",
      "coordinates": {
        "latitude": -4.4419,
        "longitude": 15.2663
      },
      "is_active": true
    },
    {
      "id": 2,
      "name": "Kongo-Central",
      "name_en": "Kongo-Central",
      "country_id": 1,
      "code": "KON",
      "coordinates": {
        "latitude": -5.4667,
        "longitude": 13.4667
      },
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/districts​

Récupérer la liste des districts.

Request:

GET /common-data/districts?region_id=1
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Districts récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Kinshasa",
      "name_en": "Kinshasa",
      "region_id": 1,
      "code": "KIN_DIST",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Mont-Ngafula",
      "name_en": "Mont-Ngafula",
      "region_id": 1,
      "code": "MNG",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/cities​

Récupérer la liste des villes.

Request:

GET /common-data/cities?district_id=1
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Villes récupérées avec succès",
  "result": [
    {
      "id": 1,
      "name": "Kinshasa",
      "name_en": "Kinshasa",
      "district_id": 1,
      "code": "KIN_CITY",
      "population": 15000000,
      "is_active": true
    },
    {
      "id": 2,
      "name": "Lemba",
      "name_en": "Lemba",
      "district_id": 1,
      "code": "LEM",
      "population": 500000,
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/corridors​

Récupérer la liste des corridors commerciaux.

Request:

GET /common-data/corridors
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Corridors récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Kinshasa-Brazzaville",
      "name_en": "Kinshasa-Brazzaville",
      "origin_country_id": 1,
      "destination_country_id": 2,
      "distance_km": 25,
      "estimated_time_hours": 2,
      "transport_modes": ["road", "water"],
      "is_active": true
    },
    {
      "id": 2,
      "name": "Kinshasa-Lubumbashi",
      "name_en": "Kinshasa-Lubumbashi",
      "origin_country_id": 1,
      "destination_country_id": 1,
      "distance_km": 1500,
      "estimated_time_hours": 24,
      "transport_modes": ["road", "air"],
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/checkpoints​

Récupérer la liste des points de contrôle.

Request:

GET /common-data/checkpoints?corridor_id=1
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Points de contrôle récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Poste Frontière Maluku",
      "name_en": "Maluku Border Post",
      "corridor_id": 1,
      "city_id": 1,
      "coordinates": {
        "latitude": -4.4419,
        "longitude": 15.2663
      },
      "checkpoint_type": "border",
      "services": ["customs", "immigration", "health"],
      "operating_hours": "06:00-18:00",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

🥬 Produits et animaux​

GET /common-data/products​

Récupérer la liste des produits.

Request:

GET /common-data/products?category=agricultural
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Produits récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Maïs",
      "name_en": "Corn",
      "category": "agricultural",
      "product_type_id": 1,
      "code": "CORN",
      "scientific_name": "Zea mays",
      "seasonality": [1, 2], // Saison sèche et pluie
      "storage_requirements": "dry_place",
      "export_restrictions": [],
      "is_active": true
    },
    {
      "id": 2,
      "name": "Manioc",
      "name_en": "Cassava",
      "category": "agricultural",
      "product_type_id": 1,
      "code": "CASSAVA",
      "scientific_name": "Manihot esculenta",
      "seasonality": [1, 2],
      "storage_requirements": "cool_place",
      "export_restrictions": ["health_certificate"],
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/animals​

Récupérer la liste des animaux.

Request:

GET /common-data/animals?category=livestock
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Animaux récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Bœuf",
      "name_en": "Cattle",
      "category": "livestock",
      "animal_type_id": 1,
      "code": "CATTLE",
      "scientific_name": "Bos taurus",
      "average_weight_kg": 400,
      "health_requirements": ["vaccination", "health_certificate"],
      "export_restrictions": ["veterinary_inspection"],
      "is_active": true
    },
    {
      "id": 2,
      "name": "Chèvre",
      "name_en": "Goat",
      "category": "livestock",
      "animal_type_id": 2,
      "code": "GOAT",
      "scientific_name": "Capra aegagrus hircus",
      "average_weight_kg": 50,
      "health_requirements": ["vaccination"],
      "export_restrictions": ["veterinary_inspection"],
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/product-types​

Récupérer les types de produits.

Request:

GET /common-data/product-types
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Types de produits récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Produits agricoles",
      "name_en": "Agricultural Products",
      "category": "agricultural",
      "description": "Produits issus de l'agriculture",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Produits minéraux",
      "name_en": "Mineral Products",
      "category": "minerals",
      "description": "Produits issus de l'extraction minière",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/animal-types​

Récupérer les types d'animaux.

Request:

GET /common-data/animal-types
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Types d'animaux récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Bovins",
      "name_en": "Cattle",
      "category": "livestock",
      "description": "Animaux de la famille des bovins",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Caprins",
      "name_en": "Goats",
      "category": "livestock",
      "description": "Animaux de la famille des caprins",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

🚚 Transport et services​

GET /common-data/transport-modes​

Récupérer les modes de transport.

Request:

GET /common-data/transport-modes
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Modes de transport récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Route",
      "name_en": "Road",
      "code": "ROAD",
      "description": "Transport par voie routière",
      "icon": "truck",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Chemin de fer",
      "name_en": "Railway",
      "code": "RAIL",
      "description": "Transport par voie ferrée",
      "icon": "train",
      "is_active": true
    },
    {
      "id": 3,
      "name": "Avion",
      "name_en": "Air",
      "code": "AIR",
      "description": "Transport aérien",
      "icon": "plane",
      "is_active": true
    },
    {
      "id": 4,
      "name": "Eau",
      "name_en": "Water",
      "code": "WATER",
      "description": "Transport par voie fluviale/maritime",
      "icon": "ship",
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/transport-methods​

Récupérer les méthodes de transport.

Request:

GET /common-data/transport-methods
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Méthodes de transport récupérées avec succès",
  "result": [
    {
      "id": 1,
      "name": "Camion",
      "name_en": "Truck",
      "transport_mode_id": 1,
      "code": "TRUCK",
      "capacity_kg": 25000,
      "average_speed_kmh": 60,
      "cost_per_km": 0.5,
      "is_active": true
    },
    {
      "id": 2,
      "name": "Véhicule léger",
      "name_en": "Light Vehicle",
      "transport_mode_id": 1,
      "code": "LIGHT_VEHICLE",
      "capacity_kg": 1000,
      "average_speed_kmh": 80,
      "cost_per_km": 0.3,
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

GET /common-data/services​

Récupérer la liste des services.

Request:

GET /common-data/services
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Services récupérés avec succès",
  "result": [
    {
      "id": 1,
      "name": "Douanes",
      "name_en": "Customs",
      "code": "CUSTOMS",
      "category": "government",
      "description": "Service des douanes",
      "required_documents": ["commercial_invoice", "packing_list"],
      "is_active": true
    },
    {
      "id": 2,
      "name": "Immigration",
      "name_en": "Immigration",
      "code": "IMMIGRATION",
      "category": "government",
      "description": "Service d'immigration",
      "required_documents": ["passport", "visa"],
      "is_active": true
    },
    {
      "id": 3,
      "name": "Inspection sanitaire",
      "name_en": "Health Inspection",
      "code": "HEALTH",
      "category": "government",
      "description": "Inspection sanitaire et phytosanitaire",
      "required_documents": ["health_certificate", "phytosanitary_certificate"],
      "is_active": true
    }
  ],
  "errors": null,
  "except": null
}

🔄 Cache et performance​

Stratégie de cache​

  • TTL : 24 heures pour les données de référence
  • Invalidation : Automatique lors des mises à jour
  • Clé de cache : reference:${type}:${id}

Optimisations​

  • Mise en cache automatique des réponses
  • Compression des données
  • Pagination pour les grandes listes
  • Filtrage côté serveur

🛠️ Gestion des erreurs​

Erreurs de cache​

{
  "success": false,
  "message": "Erreur de cache",
  "result": null,
  "errors": ["Impossible de récupérer les données du cache"],
  "except": null
}

Erreurs de données​

{
  "success": false,
  "message": "Données non trouvées",
  "result": null,
  "errors": ["Aucune donnée trouvée pour les critères spécifiés"],
  "except": null
}

Cette API Common Data fournit un accès rapide et optimisé aux données de référence essentielles du système Commerce Tracking, avec une mise en cache intelligente pour garantir des performances optimales.