# Guide d'intégration API - Afritech Logistics

## Vue d'ensemble

Afritech Logistics utilise **Convex** comme backend, qui fonctionne via WebSocket plutôt que HTTP REST traditionnel. Ce guide explique comment intégrer votre application avec notre plateforme.

## Architecture

- **Backend**: Convex (WebSocket-based)
- **Authentification**: Clés API
- **Format de données**: JSON
- **Langues supportées**: FR, EN

## Configuration initiale

### 1. Obtenir une clé API

Contactez l'équipe Afritech Logistics à contact@afritechlogistics.com pour obtenir votre clé API.

### 2. Installer le client Convex

```bash
npm install convex
```

### 3. Configuration

```typescript
import { ConvexHttpClient } from "convex/browser";

const client = new ConvexHttpClient(process.env.CONVEX_URL);
```

## Fonctions API disponibles

### 1. Obtenir le statut d'une demande

**Fonction**: `api.api.public.getRequestStatus`

**Paramètres**:
- `trackingNumber` (string): Numéro de suivi
- `apiKey` (string): Votre clé API

**Exemple**:

```typescript
const status = await client.query(api.api.public.getRequestStatus, {
  trackingNumber: "TRK1234567890123",
  apiKey: "votre_cle_api"
});

console.log(status);
// {
//   trackingNumber: "TRK1234567890123",
//   status: "in_transit",
//   origin: { city: "Dakar", country: "Sénégal" },
//   destination: { city: "Abidjan", country: "Côte d'Ivoire" },
//   lastLocation: {
//     latitude: 14.6928,
//     longitude: -17.4467,
//     status: "En route",
//     timestamp: 1234567890
//   }
// }
```

**Réponse**:

```typescript
{
  trackingNumber: string;
  status: "pending" | "quoted" | "assigned" | "in_transit" | "delivered" | "cancelled";
  origin: {
    address: string;
    city: string;
    country: string;
    latitude?: number;
    longitude?: number;
  };
  destination: {
    address: string;
    city: string;
    country: string;
    latitude?: number;
    longitude?: number;
  };
  cargoType: string;
  cargoWeight: number;
  pickupDate: number;
  deliveryDate?: number;
  estimatedCost?: number;
  finalCost?: number;
  currency: string;
  client: {
    name: string;
    company?: string;
  } | null;
  transporter: {
    name: string;
    company?: string;
  } | null;
  lastLocation: {
    latitude: number;
    longitude: number;
    status: string;
    timestamp: number;
  } | null;
}
```

---

### 2. Créer une demande de transport

**Fonction**: `api.api.public.createTransportRequest`

**Paramètres**:
- `apiKey` (string): Votre clé API
- `clientEmail` (string): Email du client
- `origin` (object): Point de départ
- `destination` (object): Point d'arrivée
- `cargoType` (string): Type de cargo
- `cargoWeight` (number): Poids en kg
- `cargoVolume` (number, optionnel): Volume en m³
- `cargoValue` (number, optionnel): Valeur en devise
- `pickupDate` (number): Date de collecte (timestamp)
- `currency` (string): EUR, USD, ou XOF
- `notes` (string, optionnel): Notes additionnelles

**Exemple**:

```typescript
const result = await client.mutation(api.api.public.createTransportRequest, {
  apiKey: "votre_cle_api",
  clientEmail: "client@example.com",
  origin: {
    address: "123 Rue Example",
    city: "Dakar",
    country: "Sénégal",
    latitude: 14.6928,
    longitude: -17.4467
  },
  destination: {
    address: "456 Avenue Test",
    city: "Abidjan",
    country: "Côte d'Ivoire",
    latitude: 5.3600,
    longitude: -4.0083
  },
  cargoType: "Électronique",
  cargoWeight: 500,
  cargoVolume: 2.5,
  cargoValue: 50000,
  pickupDate: Date.now() + 86400000, // Demain
  currency: "XOF",
  notes: "Fragile - Manipuler avec précaution"
});

console.log(result);
// {
//   requestId: "jx7abc123...",
//   trackingNumber: "TRK1234567890456",
//   status: "pending",
//   message: "Transport request created successfully"
// }
```

---

### 3. Lister les transporteurs disponibles

**Fonction**: `api.api.public.listTransporters`

**Paramètres**:
- `apiKey` (string): Votre clé API
- `country` (string, optionnel): Filtrer par pays

**Exemple**:

```typescript
const transporters = await client.query(api.api.public.listTransporters, {
  apiKey: "votre_cle_api",
  country: "Sénégal" // Optionnel
});

console.log(transporters);
// [
//   {
//     id: "abc123...",
//     companyName: "Transport Express Dakar",
//     rating: 4.8,
//     completedDeliveries: 156,
//     vehicleTypes: ["truck", "van"],
//     capacity: { maxWeight: 5000, maxVolume: 20 },
//     operatingCountries: ["Sénégal", "Mali", "Guinée"],
//     contact: {
//       name: "Mamadou Diallo",
//       email: "contact@transportexpress.sn",
//       phone: "+221 77 123 45 67"
//     }
//   }
// ]
```

---

### 4. Mettre à jour le statut d'une demande

**Fonction**: `api.api.public.updateRequestStatus`

**Paramètres**:
- `apiKey` (string): Votre clé API
- `trackingNumber` (string): Numéro de suivi
- `status` (string): Nouveau statut
- `latitude` (number, optionnel): Position GPS
- `longitude` (number, optionnel): Position GPS
- `notes` (string, optionnel): Notes

**Exemple**:

```typescript
const result = await client.mutation(api.api.public.updateRequestStatus, {
  apiKey: "votre_cle_api",
  trackingNumber: "TRK1234567890123",
  status: "in_transit",
  latitude: 14.7167,
  longitude: -17.4677,
  notes: "Départ de Dakar confirmé"
});

console.log(result);
// {
//   success: true,
//   trackingNumber: "TRK1234567890123",
//   status: "in_transit",
//   message: "Status updated successfully"
// }
```

---

## Statuts des demandes

| Statut | Description |
|--------|-------------|
| `pending` | En attente de devis |
| `quoted` | Devis reçus |
| `assigned` | Transporteur assigné |
| `in_transit` | En cours de transport |
| `delivered` | Livré |
| `cancelled` | Annulé |

---

## Gestion des erreurs

Les erreurs sont retournées au format ConvexError :

```typescript
try {
  const result = await client.query(api.api.public.getRequestStatus, {
    trackingNumber: "INVALID",
    apiKey: "votre_cle_api"
  });
} catch (error) {
  console.error(error.data);
  // {
  //   code: "NOT_FOUND",
  //   message: "Transport request not found"
  // }
}
```

**Codes d'erreur possibles** :
- `UNAUTHENTICATED` - Clé API invalide
- `NOT_FOUND` - Ressource non trouvée
- `FORBIDDEN` - Accès non autorisé
- `BAD_REQUEST` - Paramètres invalides

---

## Webhooks (à venir)

Pour recevoir des notifications en temps réel, vous pourrez configurer des webhooks pour :
- Nouveau devis reçu
- Changement de statut
- Livraison confirmée
- Documents uploadés

**Configuration** : Contactez support@afritechlogistics.com

---

## Limites de taux

- **Requêtes par minute** : 100
- **Requêtes par heure** : 5000
- **Requêtes par jour** : 50000

Dépassement = erreur `TOO_MANY_REQUESTS`

---

## Support

- **Email** : api-support@afritechlogistics.com
- **Documentation** : https://docs.afritechlogistics.com
- **Status** : https://status.afritechlogistics.com

---

## Exemples d'intégration

### Node.js avec Express

```javascript
const express = require('express');
const { ConvexHttpClient } = require("convex/browser");
const { api } = require("./convex/_generated/api");

const app = express();
const client = new ConvexHttpClient(process.env.CONVEX_URL);

app.get('/track/:trackingNumber', async (req, res) => {
  try {
    const status = await client.query(api.api.public.getRequestStatus, {
      trackingNumber: req.params.trackingNumber,
      apiKey: process.env.API_KEY
    });
    res.json(status);
  } catch (error) {
    res.status(400).json({ error: error.message });
  }
});

app.listen(3000);
```

### Python

```python
import requests
import json

CONVEX_URL = "https://your-convex-deployment.convex.cloud"
API_KEY = "your_api_key"

def get_request_status(tracking_number):
    response = requests.post(
        f"{CONVEX_URL}/api/query",
        json={
            "path": "api/public:getRequestStatus",
            "args": {
                "trackingNumber": tracking_number,
                "apiKey": API_KEY
            }
        }
    )
    return response.json()

status = get_request_status("TRK1234567890123")
print(status)
```

### PHP

```php
<?php
$convexUrl = "https://your-convex-deployment.convex.cloud";
$apiKey = "your_api_key";

function getRequestStatus($trackingNumber) {
    global $convexUrl, $apiKey;
    
    $data = [
        "path" => "api/public:getRequestStatus",
        "args" => [
            "trackingNumber" => $trackingNumber,
            "apiKey" => $apiKey
        ]
    ];
    
    $options = [
        'http' => [
            'method' => 'POST',
            'header' => 'Content-Type: application/json',
            'content' => json_encode($data)
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($convexUrl . '/api/query', false, $context);
    
    return json_decode($result, true);
}

$status = getRequestStatus("TRK1234567890123");
print_r($status);
?>
```

---

## Sécurité

1. **Gardez votre clé API secrète** - Ne la commitez jamais dans Git
2. **Utilisez HTTPS** - Toutes les requêtes doivent passer par HTTPS
3. **Rotation des clés** - Changez votre clé tous les 90 jours
4. **IP Whitelisting** - Disponible sur demande pour plans Enterprise

---

## Changelog

### Version 1.0.0 (2025-01-08)
- Lancement initial de l'API
- 4 endpoints disponibles
- Support FR/EN

---

**© 2025 Afritech Logistics - Tous droits réservés**