💰 API Trade Flow

Documentation complète de l'API de gestion des flux commerciaux.

🎯 Vue d'ensemble

L'API Trade Flow gère les collections de données commerciales, les workflows de validation multi-niveaux et les rapports statistiques du système Commerce Tracking.

Fonctionnalités principales

Collections : Création et gestion des collections de données
Validation : Workflow de validation multi-niveaux
Collectes digitalisées : Gestion des collectes digitalisées
Rapports : Génération de rapports et statistiques
Workflow : Gestion des états et transitions

🔑 Authentification requise

Tous les endpoints nécessitent un token JWT valide :

Authorization: Bearer <jwt-token>

📊 Endpoints Collections

POST /trade-flow/collections

Créer une nouvelle collection de données commerciales.

Request:

POST /trade-flow/collections
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "collection_date": "2024-01-15T10:30:00Z",
  "collector_id": 456,
  "location": {
    "country_id": 1,
    "region_id": 2,
    "district_id": 3,
    "city_id": 4,
    "checkpoint_id": 5
  },
  "trade_data": {
    "product_type": "agricultural",
    "products": [
      {
        "product_id": 101,
        "quantity": 100,
        "unit": "kg",
        "value_usd": 500.00
      }
    ],
    "transport_mode": "road",
    "origin_country": 1,
    "destination_country": 2,
    "trader_info": {
      "name": "John Trader",
      "nationality": "CD",
      "document_type": "passport",
      "document_number": "AB123456"
    }
  },
  "metadata": {
    "collection_method": "digital",
    "device_id": "DEVICE_001",
    "gps_coordinates": {
      "latitude": -4.4419,
      "longitude": 15.2663
    }
  }
}

Response Success (201):

{
  "success": true,
  "message": "Collection créée avec succès",
  "result": {
    "id": 123,
    "public_id": "uuid-string",
    "collection_date": "2024-01-15T10:30:00Z",
    "collector_id": 456,
    "status": "draft",
    "validation_level": 0,
    "location": {
      "country_id": 1,
      "region_id": 2,
      "district_id": 3,
      "city_id": 4,
      "checkpoint_id": 5
    },
    "trade_data": {
      "product_type": "agricultural",
      "products": [
        {
          "product_id": 101,
          "quantity": 100,
          "unit": "kg",
          "value_usd": 500.00
        }
      ],
      "transport_mode": "road",
      "origin_country": 1,
      "destination_country": 2,
      "trader_info": {
        "name": "John Trader",
        "nationality": "CD",
        "document_type": "passport",
        "document_number": "AB123456"
      }
    },
    "metadata": {
      "collection_method": "digital",
      "device_id": "DEVICE_001",
      "gps_coordinates": {
        "latitude": -4.4419,
        "longitude": 15.2663
      }
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "errors": null,
  "except": null
}

GET /trade-flow/collections

Lister les collections avec pagination et filtres.

Query Parameters:

GET /trade-flow/collections?page=1&limit=10&status=draft&collector_id=456&date_from=2024-01-01&date_to=2024-01-31

Response Success (200):

{
  "success": true,
  "message": "Collections récupérées avec succès",
  "result": {
    "data": [
      {
        "id": 123,
        "public_id": "uuid-string",
        "collection_date": "2024-01-15T10:30:00Z",
        "collector_id": 456,
        "status": "draft",
        "validation_level": 0,
        "total_value_usd": 500.00,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 150,
      "total_pages": 15
    },
    "filters": {
      "status": "draft",
      "collector_id": 456,
      "date_from": "2024-01-01",
      "date_to": "2024-01-31"
    }
  },
  "errors": null,
  "except": null
}

GET /trade-flow/collections/:id

Récupérer une collection spécifique par son ID.

Request:

GET /trade-flow/collections/123
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Collection récupérée avec succès",
  "result": {
    "id": 123,
    "public_id": "uuid-string",
    "collection_date": "2024-01-15T10:30:00Z",
    "collector_id": 456,
    "status": "draft",
    "validation_level": 0,
    "location": { /* ... */ },
    "trade_data": { /* ... */ },
    "metadata": { /* ... */ },
    "validations": [
      {
        "id": 1,
        "level": 1,
        "status": "pending",
        "validator_id": 789,
        "created_at": "2024-01-15T11:00:00Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "errors": null,
  "except": null
}

PUT /trade-flow/collections/:id

Modifier une collection existante.

Request:

PUT /trade-flow/collections/123
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "collection_date": "2024-01-15T11:00:00Z",
  "trade_data": {
    "product_type": "agricultural",
    "products": [
      {
        "product_id": 101,
        "quantity": 150,  // Modifié
        "unit": "kg",
        "value_usd": 750.00  // Modifié
      }
    ]
  }
}

DELETE /trade-flow/collections/:id

Supprimer une collection.

Request:

DELETE /trade-flow/collections/123
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Collection supprimée avec succès",
  "result": null,
  "errors": null,
  "except": null
}

✅ Endpoints Validation

POST /trade-flow/collections/:id/submit

Soumettre une collection pour validation.

Request:

POST /trade-flow/collections/123/submit
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "comments": "Collection prête pour validation"
}

POST /trade-flow/collections/:id/validate/team-manager

Validation niveau 1 par le chef d'équipe.

Request:

POST /trade-flow/collections/123/validate/team-manager
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "action": "approve",  // "approve" ou "reject"
  "comments": "Données validées, conforme aux procédures"
}

POST /trade-flow/collections/:id/validate/supervisor

Validation niveau 2 par le superviseur.

Request:

POST /trade-flow/collections/123/validate/supervisor
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "action": "approve",
  "comments": "Validation finale approuvée"
}

POST /trade-flow/collections/:id/reject

Rejeter une collection.

Request:

POST /trade-flow/collections/123/reject
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "reason": "Données incomplètes",
  "comments": "Veuillez compléter les informations manquantes"
}

POST /trade-flow/collections/:id/return

Retourner une collection pour correction.

Request:

POST /trade-flow/collections/123/return
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "reason": "Correction nécessaire",
  "comments": "Veuillez corriger les quantités indiquées"
}

📱 Endpoints Collectes Digitalisées

POST /trade-flow/digitalized-collections

Créer une collecte digitalisée.

Request:

POST /trade-flow/digitalized-collections
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "collection_id": 123,
  "digital_data": {
    "form_version": "1.2",
    "sections": [
      {
        "section_id": "basic_info",
        "fields": {
          "trader_name": "John Trader",
          "nationality": "CD",
          "document_type": "passport"
        }
      },
      {
        "section_id": "products",
        "fields": {
          "product_list": [
            {
              "product_id": 101,
              "quantity": 100,
              "unit": "kg"
            }
          ]
        }
      }
    ]
  },
  "device_info": {
    "device_id": "MOBILE_001",
    "app_version": "1.0.0",
    "platform": "android",
    "gps_accuracy": 5.2
  }
}

GET /trade-flow/digitalized-collections

Lister les collectes digitalisées.

Response Success (200):

{
  "success": true,
  "message": "Collectes digitalisées récupérées avec succès",
  "result": {
    "data": [
      {
        "id": 1,
        "collection_id": 123,
        "digital_data": { /* ... */ },
        "device_info": { /* ... */ },
        "created_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 50,
      "total_pages": 5
    }
  },
  "errors": null,
  "except": null
}

📊 Endpoints Statistiques

GET /trade-flow/statistics

Récupérer les statistiques globales.

Request:

GET /trade-flow/statistics?date_from=2024-01-01&date_to=2024-01-31&country_id=1
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Statistiques récupérées avec succès",
  "result": {
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "overview": {
      "total_collections": 1250,
      "validated_collections": 1180,
      "pending_collections": 45,
      "rejected_collections": 25,
      "total_value_usd": 1250000.00
    },
    "by_status": {
      "draft": 45,
      "submitted": 12,
      "validated": 1180,
      "rejected": 25
    },
    "by_product_type": {
      "agricultural": 800,
      "livestock": 300,
      "minerals": 150
    },
    "by_transport_mode": {
      "road": 900,
      "rail": 200,
      "air": 50,
      "water": 100
    },
    "trends": {
      "daily_collections": [
        { "date": "2024-01-01", "count": 45, "value": 45000 },
        { "date": "2024-01-02", "count": 52, "value": 52000 }
      ]
    }
  },
  "errors": null,
  "except": null
}

GET /trade-flow/statistics/agent

Statistiques spécifiques à un agent.

Request:

GET /trade-flow/statistics/agent?agent_id=456&date_from=2024-01-01&date_to=2024-01-31
Authorization: Bearer <jwt-token>

Response Success (200):

{
  "success": true,
  "message": "Statistiques agent récupérées avec succès",
  "result": {
    "agent_id": 456,
    "agent_name": "John Doe",
    "period": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    },
    "performance": {
      "total_collections": 85,
      "validated_collections": 80,
      "pending_collections": 3,
      "rejected_collections": 2,
      "validation_rate": 94.12,
      "average_daily_collections": 2.74
    },
    "productivity": {
      "collections_by_day": [
        { "date": "2024-01-01", "count": 3 },
        { "date": "2024-01-02", "count": 2 }
      ],
      "peak_hours": [9, 10, 11, 14, 15, 16],
      "most_productive_day": "Monday"
    },
    "quality": {
      "first_time_validation_rate": 85.71,
      "average_corrections_needed": 1.2,
      "common_rejection_reasons": [
        "Données incomplètes",
        "Informations contradictoires"
      ]
    }
  },
  "errors": null,
  "except": null
}

🔄 Workflow des états

États possibles

stateDiagram-v2
    [*] --> Draft: Create Collection
    Draft --> Submitted: Submit for Validation
    Submitted --> TeamManagerValidation: Level 1 Validation
    TeamManagerValidation --> Approved: Approve
    TeamManagerValidation --> Rejected: Reject
    TeamManagerValidation --> SupervisorValidation: Level 2 Validation
    SupervisorValidation --> Approved: Approve
    SupervisorValidation --> Rejected: Reject
    Rejected --> Draft: Return for Correction
    Approved --> [*]

Transitions autorisées

État actuel	Transition	Condition	Nouvel état
`draft`	Submit	Utilisateur authentifié	`submitted`
`submitted`	Validate L1	Role Chef d'Équipe	`team_manager_validation`
`team_manager_validation`	Approve	Validation positive	`supervisor_validation`
`team_manager_validation`	Reject	Validation négative	`rejected`
`supervisor_validation`	Approve	Validation finale	`approved`
`supervisor_validation`	Reject	Rejet final	`rejected`
`rejected`	Return	Retour pour correction	`draft`

🛠️ Gestion des erreurs

Erreurs de validation

{
  "success": false,
  "message": "Erreur de validation",
  "result": null,
  "errors": [
    "Le champ 'collection_date' est requis",
    "Le champ 'collector_id' doit être un nombre",
    "La quantité doit être supérieure à 0"
  ],
  "except": null
}

Erreurs d'autorisation

{
  "success": false,
  "message": "Permissions insuffisantes",
  "result": null,
  "errors": ["Vous n'avez pas les permissions pour valider cette collection"],
  "except": null
}

Erreurs de workflow

{
  "success": false,
  "message": "Transition non autorisée",
  "result": null,
  "errors": ["Impossible de valider une collection déjà approuvée"],
  "except": null
}

Cette API Trade Flow fournit une interface complète pour la gestion des flux commerciaux avec un système de validation robuste et des capacités de reporting avancées.

🎯 Vue d'ensemble​

Fonctionnalités principales​

🔑 Authentification requise​

📊 Endpoints Collections​

POST /trade-flow/collections​

GET /trade-flow/collections​

GET /trade-flow/collections/:id​

PUT /trade-flow/collections/:id​

DELETE /trade-flow/collections/:id​

✅ Endpoints Validation​

POST /trade-flow/collections/:id/submit​

POST /trade-flow/collections/:id/validate/team-manager​

POST /trade-flow/collections/:id/validate/supervisor​

POST /trade-flow/collections/:id/reject​

POST /trade-flow/collections/:id/return​

📱 Endpoints Collectes Digitalisées​

POST /trade-flow/digitalized-collections​

GET /trade-flow/digitalized-collections​

📊 Endpoints Statistiques​

GET /trade-flow/statistics​

GET /trade-flow/statistics/agent​

🔄 Workflow des états​

États possibles​

Transitions autorisées​

🛠️ Gestion des erreurs​

Erreurs de validation​

Erreurs d'autorisation​

Erreurs de workflow​

🎯 Vue d'ensemble

Fonctionnalités principales

🔑 Authentification requise

📊 Endpoints Collections

POST /trade-flow/collections

GET /trade-flow/collections

GET /trade-flow/collections/:id

PUT /trade-flow/collections/:id

DELETE /trade-flow/collections/:id

✅ Endpoints Validation

POST /trade-flow/collections/:id/submit

POST /trade-flow/collections/:id/validate/team-manager

POST /trade-flow/collections/:id/validate/supervisor

POST /trade-flow/collections/:id/reject

POST /trade-flow/collections/:id/return

📱 Endpoints Collectes Digitalisées

POST /trade-flow/digitalized-collections

GET /trade-flow/digitalized-collections

📊 Endpoints Statistiques

GET /trade-flow/statistics

GET /trade-flow/statistics/agent

🔄 Workflow des états

États possibles

Transitions autorisées

🛠️ Gestion des erreurs

Erreurs de validation

Erreurs d'autorisation

Erreurs de workflow