API Partenaires — Documentation pour développeurs

Authentification

Chaque entreprise partenaire reçoit une clé API secrète (format sk_live_...), générée une seule fois par un administrateur Camelia Logistics. Elle doit accompagner chaque requête dans l'en-tête HTTP Authorization :

En-tête HTTP

Authorization: Bearer sk_live_VOTRE_CLE_API_SECRETE

La clé n'est affichée qu'une seule fois, au moment de sa création ou d'une rotation. Conservez-la dans un coffre-fort de secrets — jamais en clair dans un dépôt de code. Toutes les requêtes doivent être faites en HTTPS.

Codes d'erreur d'authentification

HTTP	Erreur	Cause
`401`	`unauthorized`	En-tête `Authorization` manquant ou clé invalide
`403`	`forbidden`	Compte partenaire suspendu
`429`	`rate_limited`	Plus de 60 requêtes par minute

Créer une commande

POST /v1/orders

Corps de la requête

Champ	Type		Description
`partnerOrderRef`	string	requis	Votre identifiant interne de commande. Clé d'idempotence : renvoyer deux fois la même référence retourne la commande déjà créée.
`serviceType`	string	requis	Ex. `LIVRAISON`, `STOCKAGE`, `DÉMÉNAGEMENT ET TRANSPORT`, `EXPÉDITION`.
`pickupAddress`	string	requis	Adresse d'enlèvement.
`dropoffAddress`	string	requis	Adresse de livraison.
`packageNature`	string	requis	Nature du colis ou de la marchandise.
`vehicleType`	string	requis	Type de véhicule souhaité.
`contactName`	string	requis	Nom du contact terrain que le livreur peut joindre.
`contactPhone`	string	requis	Téléphone du contact terrain.
`description`	string	optionnel	Notes libres (max 1000 caractères).
`photoUrls`	string[]	optionnel	URLs de photos du colis (max 10).
`additionalDetails`	object	optionnel	Métadonnées libres (volume, étage, etc.).

Exemple — curl

# Création d'une commande, idempotente via partnerOrderRef
curl -X POST "https://us-central1-camelia-89667.cloudfunctions.net/partnerApi/v1/orders" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE_API_SECRETE" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerOrderRef": "CMD-2026-00042",
    "serviceType": "LIVRAISON",
    "pickupAddress": "Entrepôt Zone Industrielle, Douala",
    "dropoffAddress": "12 Rue des Jardins, Douala",
    "packageNature": "Pièces détachées",
    "vehicleType": "Camionnette",
    "contactName": "Awa Diop",
    "contactPhone": "+237600000000",
    "additionalDetails": { "poids_kg": 40 }
  }'

Réponse

201 Created pour une nouvelle commande, ou 200 OK si la commande existait déjà (idempotence) :

200 / 201 — application/json

{
  "order": {
    "id": "f3c1a9...",
    "status": "PENDING",
    "serviceType": "LIVRAISON",
    "priceQuote": null,
    "isQuote": true,
    "contactName": "Awa Diop",
    "partnerOrderRef": "CMD-2026-00042",
    "source": "partner_api",
    "createdAt": "2026-08-04T10:15:00.000Z"
  }
}

400 invalid_request si un champ requis est manquant ou invalide (détail dans details).

Consulter une commande

GET /v1/orders/{id}

Renvoie 200 avec l'objet commande, ou 404 not_found si elle n'existe pas ou n'appartient pas à votre compte.

Lister vos commandes

GET /v1/orders?status=PENDING&limit=20

status (optionnel) — filtre exact sur le statut.
limit (optionnel, défaut 20, max 100).

Statuts de commande

`PENDING`	Reçue, en attente de validation/tarification
`ACCEPTED`	Devis / prix accepté
`ASSIGNED`	Un livreur a été assigné
`IN_PROGRESS`	Livraison en cours
`COMPLETED`	Livrée
`CANCELLED`	Annulée

Webhooks — notifications de statut

Si une webhookUrl a été configurée pour votre compte, Camelia Logistics envoie un POST signé à chaque changement de statut important (ACCEPTED, ASSIGNED, IN_PROGRESS, COMPLETED, CANCELLED).

Camelia

Votre serveur

Payload

POST — application/json

{
  "event": "order.status_changed",
  "orderId": "f3c1a9...",
  "partnerOrderRef": "CMD-2026-00042",
  "status": "ASSIGNED",
  "priceQuote": 4500,
  "timestamp": "2026-08-04T10:20:00.000Z"
}

Vérification de la signature

Chaque requête contient un en-tête X-Camelia-Signature = HMAC-SHA256(corps JSON brut, webhookSecret), encodé en hexadécimal :

Node.js

const crypto = require('crypto');

function isValidSignature(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac('sha256', webhookSecret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Répondez 2xx rapidement (< 5s). Camelia retente jusqu'à 3 fois en cas d'échec ou de timeout, puis abandonne — utilisez GET /v1/orders/{id} en secours si vous suspectez un événement manqué.

Bonnes pratiques

Idempotence : générez toujours un partnerOrderRef unique et stable — un renvoi réseau ne créera jamais de doublon.
Rotation de clé : en cas de doute sur une fuite, demandez une rotation immédiate ; aucune interruption de service si vous mettez à jour la clé dans la foulée.
Limites : 60 requêtes par minute par compte. Contactez-nous si votre volume dépasse quelques centaines de commandes par mois.

Devenir partenaire

Votre entreprise souhaite intégrer Camelia Logistics à son système de commande ? Écrivez-nous, une clé API et un accès à cette documentation vous seront transmis.

Nous contacter WhatsApp

APIPartenaires