ColiXpress Developer API — Référence complète
Introduction
- Base URL :
https://api.colixpress.com - Format : JSON uniquement (
Content-Type: application/json)
Deux surfaces d'API
| Surface | Auth | Usage |
|---|---|---|
Portail développeur /api/developers/* |
Authorization: Bearer <token> |
Gestion compte + clés API (humain/dashboard) |
API métier /api/v1/* |
X-Api-Key + X-Api-Secret |
Commandes, tracking, estimations (serveur-à-serveur) |
Format des réponses
// Succès
{ "success": true, "message": "...", "data": {...} }
// Erreur
{ "success": false, "message": "Description", "errors?": {...} }
// Paginé
{ "success": true, "data": [...], "meta": {"total":50,"page":1,"per_page":20,"total_pages":3} }
Codes HTTP
200OK201Créé400Requête invalide401Non authentifié403Interdit404Introuvable409Conflit422Validation429Rate limit500Erreur serveur
1.1 POST /api/developers/register
Crée un compte développeur. Retourne immédiatement le token + une clé API de test.
// Request
{
"email": "dev@acme.cm",
"password": "secret123",
"first_name": "Alice",
"last_name": "Kamga",
"country_id": 1,
"company_name": "Acme SARL"
}
Erreurs : 409 email déjà utilisé · 422 validation
1.2 POST /api/developers/login
// Request
{ "email": "dev@acme.cm", "password": "secret123" }
// Response 200
{ "token": "...", "token_type": "Bearer", "user": {...} }
Erreurs : 401 identifiants invalides · 403 compte désactivé ou pas développeur
1.3 GET /api/developers/me
// Response 200
{
"user": {...},
"api_keys": { "total": 3, "live": 1, "test": 2 },
"total_requests": 15234
}
1.4 GET /api/developers/usage
{
"totals": { "orders": 152, "revenue": 458000, "requests": 15234 },
"per_key": [
{ "id": 12, "name": "Prod", "is_test_mode": false, "total_requests": 12000, "orders": 150, "revenue": 450000 }
]
}
1.5 Gestion des clés API — Bearer
| Méthode | Endpoint | Description |
|---|---|---|
| GET | /api/developers/api-keys | Liste des clés (sans les secrets) |
| POST | /api/developers/api-keys | Créer une clé · retourne api_secret une fois |
| PUT | /api/developers/api-keys/{id} | Modifier nom/webhook/IP/mode |
| POST | /api/developers/api-keys/{id}/regenerate-secret | Nouveau secret, visible une fois |
| DELETE | /api/developers/api-keys/{id} | Désactiver la clé |
| GET | /api/developers/api-keys/{id}/stats | Stats par clé |
// POST /api/developers/api-keys
{
"name": "Production - Site web",
"webhook_url": "https://monsite.com/webhook/colixpress",
"allowed_ips": "1.2.3.4,5.6.7.8"
}
2.1 POST /api/v1/orders
Headers requis :
X-Api-Key: clx_test_xxx X-Api-Secret: <secret>
// Request — commande "direct"
{
"order_type": "direct",
"external_reference": "ACME-9001",
"pickup_address": "Akwa, Douala",
"pickup_lat": 4.0511,
"pickup_lng": 9.7679,
"pickup_contact_name": "Expéditeur",
"pickup_contact_phone": "699000000",
"dropoff_address": "Bonapriso, Douala",
"dropoff_lat": 4.0089,
"dropoff_lng": 9.7120,
"dropoff_contact_name": "Client Final",
"dropoff_contact_phone": "655000000",
"package_description": "Carton 5kg",
"package_size": "moyen",
"package_weight_kg": 5.0,
"package_value": 25000,
"payment_method": "cash"
}
Valeurs package_size : petit, moyen, grand.
Lecture des commandes
| Endpoint | Description |
|---|---|
GET /api/v1/orders | Liste paginée — ?page=1&per_page=20&status=pending |
GET /api/v1/orders/{reference} | Détail par référence interne COL-... |
GET /api/v1/orders/by-reference/{reference} | Détail par votre external_reference |
GET /api/v1/orders/{reference}/tracking | {order_status, history[]} |
PUT /api/v1/orders/{reference}/cancel | Annulation si pending ou accepted |
2.3 GET /api/v1/estimate
GET /api/v1/estimate?pickup_lat=4.05&pickup_lng=9.76&dropoff_lat=4.00&dropoff_lng=9.71&city=Douala&package_size=moyen&package_weight_kg=5&package_value=25000
// Response
{
"distance_km": 4.21,
"price": 2500,
"currency": "XAF",
"city": "Douala"
}
2.4 Données de référence
| Endpoint | Description |
|---|---|
GET /api/v1/countries | Pays supportés |
GET /api/v1/pricing | Règles de tarification actives |
3. Statuts de commande
pending → accepted → picking → delivering → delivered
↘ cancelled (uniquement en pending ou accepted)
4. Sécurité & bonnes pratiques
- Stockez le
api_secretchiffré côté serveur. - Utilisez
allowed_ipspour whitelist l'IP sortante de votre serveur. - Configurez
webhook_urlpour recevoir les notifications. - Respectez le rate limit de 1000 requêtes/heure par clé.
Besoin d'aide ?
Contactez l'équipe technique à support@colixpress.com ou sur WhatsApp.