Créez des livraisons directement depuis votre système

Chaque requête vers partner-api/v1/* s'authentifie avec une paire clé/secret propre à votre compte.

Ces identifiants se génèrent depuis votre tableau de bord Carygoo, section Intégration API. Le secret n'est affiché qu'une seule fois, au moment de la génération — Carygoo ne le stocke jamais en clair et ne peut pas vous le redonner.

HTTP/1.1 401 Unauthorized
{
  "error": {
    "code": "invalid_api_credentials",
    "message": "Clé API ou secret invalide."
  }
}

Limite de débit : 120 requêtes/minute par clé. Au-delà, réponse 429 Too Many Requests.

Chaque type porte sa propre grille tarifaire, non exposée ici — le prix final est toujours calculé par Carygoo à la création de la livraison.

{
  "vehicle_types": [
    { "id": 1, "libelle": "Moto", "description": "Petits colis, documents" },
    { "id": 2, "libelle": "Voiture", "description": "Colis moyens" }
  ]
}

Pas besoin de gérer votre propre clé Google Maps : Carygoo propose, par défaut, un proxy vers Google Place Autocomplete. Facultatif — vous pouvez continuer à résoudre vos adresses de votre côté et envoyer directement des coordonnées à la création de livraison.

{
  "suggestions": [
    { "description": "Akwa, Douala, Cameroon", "place_id": "ChIJ6Yas2F8SYRARJq4txF-eIIw" }
  ]
}

Non facturé. Générez un session_token (un UUID de votre côté) au début de la saisie et réutilisez-le pour tous les appels autocomplete de la même recherche.

{
  "address": "Akwa I, Douala, Cameroon",
  "lat": 4.0531425, "lng": 9.6995823,
  "wallet_balance_after": 48500
}

Facturé (action place_lookup, cf. section 8) — c'est cet appel qui clôt la session et engage un coût réel, jamais autocomplete. 402 insufficient_wallet_balance si le solde ne le permet pas.

Créer une livraison

Requête

{
  "pickup": {
    "address": "Akwa, Douala",
    "lat": 4.0483, "lng": 9.7043,
    "contact_name": "Boutique Akwa",
    "contact_phone": "699000001"
  },
  "dropoff": {
    "address": "Bonapriso, Douala",
    "lat": 4.0221, "lng": 9.6987,
    "contact_name": "Jean Client",
    "contact_phone": "677000002"
  },
  "category_id": 1,
  "notes": "Sonner à l'interphone"
}

Réponse — 201 Created

{
  "delivery_id": "8f14e45f-ceea-467e-bd97-4b3a1c1e0f6a",
  "status": "driver_assigned",
  "distance_km": 4.8, "duration_min": 14.2,
  "price": { "amount": 1220, "currency": "XAF" },
  "wallet_balance_after": 48490
}

delivery_id est l'identifiant public à utiliser pour le suivi et l'annulation.

Erreurs

À la création, Carygoo cherche un livreur disponible en deux temps :

Ce réglage (fallback_to_global_pool, activé par défaut) se configure depuis votre tableau de bord, section Intégration API.

Si aucun livreur n'est trouvé immédiatement, la livraison passe au statut no_driver_found et Carygoo continue de chercher automatiquement (tentatives espacées de 30s à 5min) — vous êtes notifié par webhook dès qu'un livreur est trouvé.

Suivre / annuler

{
  "delivery_id": "8f14e45f-ceea-467e-bd97-4b3a1c1e0f6a",
  "status": "picked_up",
  "price": { "amount": 1220, "currency": "XAF" },
  "driver": {
    "name": "Paul Mbarga",
    "phone": "690000000",
    "vehicle_plate": "LT-1234-AB",
    "position": { "lat": 4.031, "lng": 9.701 }
  }
}

Possible uniquement avant récupération par le livreur (pending, driver_assigned, no_driver_found) — sinon 409 delivery_not_cancelable.

Cycle de vie

↳ à tout moment avant picked_up : canceled

↳ si aucun livreur : no_driver_found → retrouvé → driver_assigned

Configurez une URL de callback depuis votre tableau de bord (section Intégration API). Carygoo y envoie un POST JSON à chaque événement.

Payload

{
  "event": "delivery.status_changed",
  "data": {
    "delivery_id": "8f14e45f-...",
    "status": "driver_assigned",
    "driver": { "name": "Paul Mbarga", ... }
  }
}

Vérifier la signature

Chaque requête inclut X-Carygoo-Event, X-Carygoo-Timestamp et X-Carygoo-Signature — un HMAC-SHA256 de timestamp + "." + corps_brut avec votre webhook_secret (affiché une seule fois, comme votre api_secret).

$expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

const expected = crypto
  .createHmac('sha256', secret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

if (!crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(signature)
)) return res.status(401).end();

L'usage de l'API a un coût réel pour Carygoo (Google Distance Matrix à chaque livraison, Google Places si vous utilisez la recherche d'adresse, infrastructure) — distinct du prix de la livraison elle-même, qui rémunère le livreur.

Rechargez votre portefeuille en Mobile Money (MTN/Orange, via Dohone — le même moyen déjà utilisé pour votre abonnement) depuis votre tableau de bord. Un solde négatif (dette) est toléré jusqu'à un plafond défini par Carygoo — au-delà, l'API renvoie 402 insufficient_wallet_balance jusqu'à recharge.

Tous les montants sont exprimés en XAF (Francs CFA), en unité entière.