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à.
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.
| Permission | Ce 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.
| Statut | Où 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
- 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.
- Avec la clé d’essais : les villes, puis un devis, puis un colis, puis advance jusqu’à DELIVERED.
- Branchez un webhook sur votre environnement de test et vérifiez la signature.
- 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