SendIt Retour au site English

Pour les développeurs

Votre boutique crée le colis.
Nous faisons le reste.

Une API REST, du JSON, une clé dans un en-tête. Votre client paie sa commande, votre serveur appelle SendIt, le colis part. Le destinataire suit le sien sur WhatsApp, vous suivez le vôtre par webhook.

Adresse de base https://api.sendit-bj.com/v1

Pas d’abonnement, pas de frais d’intégration. Vous payez les transports que vous nous confiez, au tarif affiché.

Nous facturons le transport, et rien d’autre. L’argent de la marchandise ne passe pas par nous : vous encaissez votre client comme vous le faites déjà.

Trois boutiques en ligne, panier, commande et paiement, appellent SendIt en JSON. SendIt en ressort un colis, une livraison à domicile et une notification WhatsApp.

Votre clé

Nous vous remettons deux clés : une pour vos essais, une pour la production.

Essais

sk_test_…

Rien de réel. Bac à sable séparé, aucun colis, aucun message, aucune facture.

Production

sk_live_…

De vrais colis, de vrais messages WhatsApp, une vraie facture.

Elle voyage dans l’en-tête Authorization :

Authorization: Bearer sk_live_votre_cle

Nous ne conservons pas votre clé, seulement son empreinte SHA-256. Si vous la perdez, nous ne pouvons pas vous la redonner : nous en créons une nouvelle et révoquons l’ancienne. Si vous pensez qu’elle a fuité, dites-le-nous, la révocation prend effet en moins d’une minute.

Chaque clé porte des permissions. Celle de votre page de tarification n’a besoin que de quotes:read et ne pourra pas créer de colis.

PermissionCe qu’elle ouvre
quotes:read Calculer un prix
parcels:read Lire vos colis et leur historique
parcels:write Créer et annuler des colis
webhooks:manage Gérer vos notifications
codes:read Recevoir le code de remise, pour le transmettre vous-même

Les erreurs

Toujours la même forme, quel que soit l’appel. Lisez le code, pas la phrase : la phrase est écrite pour un humain et peut changer.

{
  "error": {
    "code": "invalid_request",
    "message": "Le numéro du destinataire doit être un mobile.",
    "param": "recipient.phone"
  }
}

param nomme le champ fautif quand il y en a un, pour que vous puissiez le pointer dans votre propre interface.

Code HTTP Ce que ça veut dire
unauthorized 401 Clé absente, invalide ou révoquée.
forbidden 403 Clé valide, mais sans la permission qu’il faut.
not_found 404 Ce colis n’existe pas, ou n’est pas à vous.
method_not_allowed 405 L’adresse existe, pas ce verbe.
invalid_request 422 Nous avons lu votre JSON et un champ ne va pas. param le nomme.
unserved_route 422 Nous ne desservons pas encore cette liaison.
price_on_request 422 Hors grille. Appelez-nous, ce n’est pas une erreur de votre côté.
conflict 409 L’état du colis interdit ce que vous demandez.
rate_limited 429 Trop d’appels. Les en-têtes RateLimit-* disent où vous en êtes.
payment_required 402 Solde insuffisant. Rechargez votre compte : la commande n’a pas été expédiée.
internal_error 500 De notre côté. Réessayez, puis dites-le-nous.

Où nous livrons

Un seul comptoir, à Godomey, et nous allons chercher le colis où qu’il soit dans la zone : 50 km autour de ce comptoir. Au-delà, l’aller-retour mange la journée d’un tricycle, donc nous disons non plutôt que de promettre.

Code Lieu Rattaché à Tarif
ABC Abomey-Calavi au tarif
AKA Akassato Abomey-Calavi au tarif
ALL Allada sur demande
COC Cococodji Abomey-Calavi au tarif
COT Cotonou au tarif
HEV Hevié Abomey-Calavi au tarif
OUI Ouidah au tarif
PAH Pahou Ouidah au tarif
PNO Porto-Novo au tarif
TOR Tori-Bossito sur demande

Un quartier est un nom valide. Cococodji, Hevié, Akassato et Pahou se tarifent comme leur commune : vous envoyez le nom que votre client vous a donné, et le quartier reste dans l’adresse, là où le livreur le lit.

Deux communes de la zone n’ont pas encore de tarif publié. Nous y allons, mais le devis répond price_on_request : appelez-nous et nous le fixons.

curl https://api.sendit-bj.com/v1/cities -H "Authorization: Bearer sk_live_votre_cle"

Appelez /v1/cities plutôt que de recopier cette liste. Elle grandira, et votre formulaire la suivra sans que vous y touchiez.

Hors de la zone, c’est un refus, pas une invitation à appeler : Comé est à 61 km du comptoir, Lokossa à 90, Bohicon à 114. Un tricycle qui doit rentrer le soir n’y va pas.

Calculer un prix

Avant de créer le colis, pour l’afficher dans le panier. Le prix que ce calcul renvoie est exactement celui qui sera facturé : c’est la même fonction des deux côtés, donc votre page de paiement ne peut pas annoncer un montant que le comptoir refuserait.

curl -G https://api.sendit-bj.com/v1/quotes \
  -H "Authorization: Bearer sk_live_votre_cle" \
  -d size=MEDIUM -d from=COT -d to=PNO -d collection=BRANCH
{
  "size": "MEDIUM",
  "origin": "COT",
  "destination": "PNO",
  "collection": "BRANCH",
  "collection_point": "Godomey",
  "price_fcfa": 3000,
  "currency": "XOF",
  "tariff_version": 3,
  "zone": 3
}

La taille se nomme, ou se mesure. Si vous connaissez vos cartons en centimètres, envoyez length, width et height : nous choisissons la tranche.

collection vaut BRANCH si vous apportez le colis à notre comptoir de Godomey, HOME si nous passons le prendre chez vous. Depuis ailleurs que Calavi, HOME est le défaut : il n’y a qu’un comptoir. Le second coûte plus cher, et la grille dit combien.

Les montants sont des entiers en francs CFA. Le franc CFA n’a pas de centimes : aucun de nos montants n’a de décimale, nulle part.

Créer un colis

Un appel, et le colis existe. Nous renvoyons son code de suivi et le lien que vous pouvez coller dans votre confirmation de commande.

curl -X POST https://api.sendit-bj.com/v1/parcels \
  -H "Authorization: Bearer sk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CMD-2026-114",
    "recipient": { "name": "Awa Dossou", "phone": "01 97 00 00 11" },
    "destination": {
      "city": "PNO",
      "address": "En face de la pharmacie Sainte-Marie"
    },
    "size": "MEDIUM",
    "collection": "BRANCH"
  }'
{
  "tracking_code": "SDT-COT-PNO-0001250",
  "reference": "CMD-2026-114",
  "status": "REGISTERED",
  "size": "MEDIUM",
  "origin": "Cotonou",
  "destination": "Porto-Novo",
  "destination_address": "En face de la pharmacie Sainte-Marie",
  "recipient": {
    "name": "Awa Dossou",
    "phone": "+2290197000011"
  },
  "price_fcfa": 3000,
  "currency": "XOF",
  "is_paid": false,
  "collection": "BRANCH",
  "tracking_url": "https://sendit-bj.com/?code=SDT-COT-PNO-0001250"
}

Les champs

Champ Type Ce que c’est
reference ≤ 64 Votre numéro de commande. Obligatoire.
recipient { name, phone } Nom et numéro du destinataire.
destination { city, address } Ville et adresse de livraison.
origin { city } Ville de départ. Par défaut, la vôtre.
size enum XS_S, MEDIUM, LARGE ou XL. Ou bien dimensions_cm.
dimensions_cm { length, width, height } Longueur, largeur, hauteur en centimètres.
collection enum BRANCH (vous déposez à Godomey) ou HOME (nous passons).
description ≤ 280 Ce qu’il y a dedans. Pour vous et pour le comptoir.

reference est votre protection contre la double expédition

Votre numéro de commande est la clé d’idempotence. Si votre serveur relance l’appel parce que la connexion a coupé, nous vous rendons le colis déjà créé, avec un 200 au lieu d’un 201. Nous n’expédions pas deux fois la même commande, et vous n’avez rien de particulier à coder pour ça.

L’adresse

Au Bénin, une adresse est un repère : « en face de la pharmacie Sainte-Marie », « carrefour Gbegnigan, maison à portail bleu ». Écrivez ce que votre client vous a donné. Le livreur appellera de toute façon, et un repère juste vaut mieux qu’un numéro de rue inventé.

Le numéro doit être un mobile

Le destinataire reçoit un code à quatre chiffres par WhatsApp, et le dicte au livreur à la porte : c’est lui qui prouve que le colis est arrivé à la bonne personne. Un fixe ne peut pas le recevoir, donc nous refusons le colis plutôt que de le livrer sans preuve. Les deux formats béninois passent, à huit chiffres comme à dix.

Transmettre le code vous-même

Sur demande, nous ajoutons la permission codes:read à votre clé et la réponse de création porte alors delivery_code, les quatre chiffres que votre client dictera au livreur. Vous les lui envoyez dans votre canal, à votre marque, au moment que vous choisissez.

{
  "tracking_code": "SDT-COT-PNO-0001250",
  "reference": "CMD-2026-114",
  "status": "REGISTERED",
  "delivery_code": "0421",
  "tracking_url": "https://sendit-bj.com/?code=SDT-COT-PNO-0001250"
}

Il sort UNE SEULE FOIS, à la création. GET /v1/parcels/{code} ne le rend jamais, même avec la permission. Si vous le perdez, appelez-nous.

Suivre un colis

Par son code de suivi. Ajoutez ?timeline=1 pour obtenir l’historique complet des étapes, avec leurs heures.

curl https://api.sendit-bj.com/v1/parcels/SDT-COT-PNO-0001250?timeline=1 \
  -H "Authorization: Bearer sk_live_votre_cle"

Les statuts

Un colis ne recule jamais. Si deux événements vous parviennent dans le désordre, c’est l’heure qui fait foi, pas l’ordre d’arrivée.

StatutOù en est le colis
REGISTERED Enregistré chez nous. Le destinataire a reçu son code.
COLLECTED Pris en charge, chez vous ou au comptoir.
AT_ORIGIN_HUB Au hub de départ, en attente du prochain véhicule.
IN_TRANSIT Sur la route, entre deux villes.
AT_DESTINATION_HUB Arrivé dans la ville de destination.
OUT_FOR_DELIVERY Chez le livreur, en tournée.
DELIVERED Remis. Code dicté ou signature.
DELIVERY_FAILED Présentation sans succès. Une raison est enregistrée.
RETURNING Sur le chemin du retour vers l’expéditeur.
RETURNED Revenu à l’expéditeur.
CANCELLED Annulé.
LOST Perdu. Nous vous aurons appelé avant que vous lisiez ceci.

La liste

Vos colis, les plus récents d’abord. La pagination se fait au curseur, pas par numéro de page : un colis créé pendant que vous paginez ne décale rien.

curl -G https://api.sendit-bj.com/v1/parcels -d limit=50 \
  -H "Authorization: Bearer sk_live_votre_cle"

Le lien de suivi

Chaque réponse porte tracking_url. C’est une page publique, sans clé, que vous pouvez coller telle quelle dans votre e-mail de confirmation. Elle ne montre ni prix, ni numéro de téléphone, ni le nom de l’autre partie.

https://sendit-bj.com/?code=SDT-COT-PNO-0001250

Annuler

Tant que le colis n’a pas quitté le hub de départ. Au-delà, il est sur la route vers une autre ville : il faut un retour, qui est un second trajet, et nous le réglons au téléphone.

curl -X POST https://api.sendit-bj.com/v1/parcels/SDT-COT-PNO-0001250/cancel \
  -H "Authorization: Bearer sk_live_votre_cle"

Un colis déjà en transit répond conflict. Appelez-nous : un retour se règle au téléphone.

Les notifications

Plutôt que d’interroger l’API en boucle, donnez-nous une adresse et nous vous appellerons à chaque changement. Une seule sorte d’événement, parce qu’une seule chose change.

Déclarer une adresse

curl -X POST https://api.sendit-bj.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://votre-boutique.bj/sendit/webhook" }'

Nous vous renvoyons un secret une seule fois, à la création. Gardez-le : c’est avec lui que vous vérifiez que l’appel vient bien de nous.

Ce que vous recevez

{
  "event": "parcel.status_changed",
  "tracking_code": "SDT-COT-PNO-0001250",
  "reference": "CMD-2026-114",
  "status": "OUT_FOR_DELIVERY",
  "occurred_at": "2026-11-04T09:12:04Z",
  "origin": "Cotonou",
  "destination": "Porto-Novo",
  "tracking_url": "https://sendit-bj.com/?code=SDT-COT-PNO-0001250"
}

Vérifiez la signature

Votre adresse de webhook est publique : n’importe qui peut vous envoyer un POST qui ressemble au nôtre. Si votre boutique libère une commande sur « livré », c’est exactement l’appel qu’on voudra vous forger.

L’en-tête porte l’horodatage et la signature. Reconstruisez la chaîne signée, calculez le HMAC-SHA256 avec votre secret, et comparez en temps constant. L’horodatage est signé avec le corps : sans lui, un appel valide capté une fois serait rejouable indéfiniment.

Refusez tout ce qui a plus de 5 minutes, même si la signature est bonne.

X-SendIt-Signature: t=1793491200,v1=5a0f…

PHP

$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SENDIT_SIGNATURE'] ?? '';

// t=<horodatage>,v1=<signature>
parse_str(strtr($header, ',', '&'), $parts);
$timestamp = (int) ($parts['t'] ?? 0);

if (abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

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

if (!hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

http_response_code(200);

Node

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  );
  const timestamp = Number(parts.t);

  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest();
  const given = Buffer.from(parts.v1 ?? '', 'hex');

  // Length first: timingSafeEqual throws on a mismatch instead of returning.
  return expected.length === given.length && timingSafeEqual(expected, given);
}

Si vous ne répondez pas

Tout code 2xx vaut accusé de réception. Sinon nous réessayons six fois, en espaçant de plus en plus, puis nous abandonnons et nous suspendons l’adresse après vingt échecs consécutifs. Répondez vite et traitez ensuite : un webhook n’attend pas que votre base soit à jour.

Lister et supprimer

curl https://api.sendit-bj.com/v1/webhooks -H "Authorization: Bearer sk_live_votre_cle"
curl -X DELETE https://api.sendit-bj.com/v1/webhooks/{id} -H "Authorization: Bearer sk_live_votre_cle"

Le bac à sable

Avec une clé d’essais, tout fonctionne à l’identique, et rien n’existe. Aucun colis réel, aucun WhatsApp, aucune facture, rien dans nos chiffres. Les colis de test sont effacés au bout de trente jours.

Faire avancer un colis

Une chose en plus, que la production n’a pas. Déroulez tout le cycle jusqu’à DELIVERED et voyez votre code le traiter, sans attendre qu’un tricycle arrive à Porto-Novo. La machine à états reste la même : un saut illégal répond conflict.

curl -X POST https://api.sendit-bj.com/v1/parcels/SDT-COT-PNO-0001250/advance \
  -H "Authorization: Bearer sk_test_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "status": "COLLECTED" }'

En production, cet appel répond forbidden. Un colis avance quand un livreur le déplace, pas quand une boutique le déclare.

Pour commencer

  1. Demandez-nous vos clés. Nous avons besoin du nom de la boutique, d’un contact WhatsApp (ce sera l’expéditeur de tous vos colis) et de la ville d’où partent vos envois.
  2. Avec la clé d’essais : les villes, puis un devis, puis un colis, puis advance jusqu’à DELIVERED.
  3. Branchez un webhook sur votre environnement de test et vérifiez la signature.
  4. Dites-nous quand c’est prêt, nous vous remettons la clé de production.

Une question

Écrivez-nous sur WhatsApp, appelez, ou passez au bureau.

Demander mes clés