Documentation Dashboard Connexion

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

SurfaceAuthUsage
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

  • 200 OK
  • 201 Créé
  • 400 Requête invalide
  • 401 Non authentifié
  • 403 Interdit
  • 404 Introuvable
  • 409 Conflit
  • 422 Validation
  • 429 Rate limit
  • 500 Erreur 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éthodeEndpointDescription
GET/api/developers/api-keysListe des clés (sans les secrets)
POST/api/developers/api-keysCré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-secretNouveau secret, visible une fois
DELETE/api/developers/api-keys/{id}Désactiver la clé
GET/api/developers/api-keys/{id}/statsStats 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

EndpointDescription
GET /api/v1/ordersListe 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}/cancelAnnulation 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

EndpointDescription
GET /api/v1/countriesPays supportés
GET /api/v1/pricingRè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_secret chiffré côté serveur.
  • Utilisez allowed_ips pour whitelist l'IP sortante de votre serveur.
  • Configurez webhook_url pour 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.