Professionnels et API | KOUMBA Livraison

API simple

Devis, création, suivi et annulation en quelques appels HTTP. Authentification par clé secrète.

Webhooks signés

Chaque changement de statut est envoyé à votre serveur, signé HMAC-SHA256.

Suivi pour vos clients

Un lien de suivi par livraison, avec code de remise pour le destinataire.

Facture mensuelle

Pas de paiement à chaque commande. Tarif remisé selon votre volume.

Documentation de l’API

Base : https://www.koumba-livraison.fr/api/v1. Toutes les requêtes portent l’en-tête Authorization: Bearer klk_…. Les montants sont en centimes d’euro.

Obtenir un prix

curl -X POST https://www.koumba-livraison.fr/api/v1/quotes \
  -H "Authorization: Bearer klk_votre_cle" -H "Content-Type: application/json" \
  -d '{ "pickup":  { "label": "10 rue de Rivoli, 75004 Paris" },
        "dropoff": { "label": "5 avenue Foch, 75116 Paris" },
        "size": "small", "weight_kg": 2, "urgency": "standard" }'

Créer une livraison

curl -X POST https://www.koumba-livraison.fr/api/v1/deliveries \
  -H "Authorization: Bearer klk_votre_cle" -H "Content-Type: application/json" \
  -d '{ "external_ref": "CMD-1042",
        "pickup":  { "label": "10 rue de Rivoli, 75004 Paris", "contact_name": "Boutique", "phone": "0142000000" },
        "dropoff": { "label": "5 avenue Foch, 75116 Paris", "contact_name": "Mme Martin", "phone": "0612345678" },
        "category": "parcel", "description": "Coffret cadeau", "size": "small", "weight_kg": 2,
        "urgency": "standard", "idem_key": "CMD-1042" }'

La réponse contient id, status, price_cents, tracking_url (pour vous), recipient_tracking_url (à envoyer au destinataire) et delivery_code. Utilisez idem_key pour éviter les doublons en cas de nouvel essai.

Autres routes

GET /deliveries/{id} : état d’une livraison
GET /deliveries : les dernières livraisons
POST /deliveries/{id}/cancel : annulation

Statuts

searching, scheduled, assigned, at_pickup, in_transit, at_dropoff, delivered, failed, cancelled, expired.

Webhooks

Événements : delivery.assigned, delivery.picked_up, delivery.delivered, delivery.failed, delivery.cancelled. Le corps est la livraison au format JSON ci-dessus. L’en-tête x-kl-signature: t=<horodatage>,v1=<hex> est un HMAC-SHA256 de "<horodatage>.<corps brut>" avec votre secret de webhook. Rejetez les horodatages de plus de 5 minutes.

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(',').map((x) => x.split('=')));
  const mac = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
  return Math.abs(Date.now() / 1000 - Number(p.t)) < 300 &&
         crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(p.v1));
}

Ouvrir un compte professionnel

Dites-nous ce que vous livrez : nous revenons vers vous sous un jour ouvré avec vos accès et un tarif adapté à votre volume.

La livraison de vos clients, sans y penser