For developers
Your shop creates the parcel.
We do the rest.
A REST API, JSON, one key in a header. Your customer pays, your server calls SendIt, the parcel goes out. The recipient follows theirs on WhatsApp, you follow yours by webhook.
Base URL https://api.sendit-bj.com/v1
No subscription, no integration fee. You pay for the deliveries you give us, at the published rate.
We charge for transport and nothing else. The money for the goods does not pass through us: you collect from your customer exactly as you do today.
Your key
We give you two keys: one for testing, one for production.
Test
sk_test_… Nothing real. Separate sandbox, no parcels, no messages, no invoice.
Live
sk_live_… Real parcels, real WhatsApp messages, a real invoice.
It travels in the Authorization header:
Authorization: Bearer sk_live_votre_cle We do not keep your key, only its SHA-256 fingerprint. If you lose it we cannot give it back: we create a new one and revoke the old. If you think it has leaked, tell us, revocation takes under a minute.
Every key carries permissions. The one behind your pricing page only needs quotes:read and will not be able to create parcels.
| Permission | What it opens |
|---|---|
quotes:read | Price a parcel |
parcels:read | Read your parcels and their history |
parcels:write | Create and cancel parcels |
webhooks:manage | Manage your notifications |
codes:read | Receive the delivery code, to pass on yourself |
Errors
Always the same shape, whatever the call. Read the code, not the sentence: the sentence is written for a human and may change.
{
"error": {
"code": "invalid_request",
"message": "Le numéro du destinataire doit être un mobile.",
"param": "recipient.phone"
}
} param names the offending field when there is one, so you can point at it in your own interface.
| Code | HTTP | What it means |
|---|---|---|
unauthorized | 401 | Key missing, invalid or revoked. |
forbidden | 403 | Valid key, but without the permission needed. |
not_found | 404 | That parcel does not exist, or is not yours. |
method_not_allowed | 405 | The path exists, this verb does not. |
invalid_request | 422 | We read your JSON and a field is wrong. param names it. |
unserved_route | 422 | We do not serve that pair yet. |
price_on_request | 422 | Off the grid. Call us, nothing is wrong on your side. |
conflict | 409 | The parcel is in a state that forbids what you asked. |
rate_limited | 429 | Too many calls. The RateLimit-* headers say where you stand. |
payment_required | 402 | Not enough balance. Top up your account: the order was not shipped. |
internal_error | 500 | On our side. Retry, then tell us. |
Where we deliver
One counter, at Godomey, and we collect the parcel wherever it is in the zone: 50 km around that counter. Beyond it the round trip eats a tricycle’s day, so we say no rather than promise.
| Code | Place | Part of | Rate |
|---|---|---|---|
ABC | Abomey-Calavi | published | |
AKA | Akassato | Abomey-Calavi | published |
ALL | Allada | on request | |
COC | Cococodji | Abomey-Calavi | published |
COT | Cotonou | published | |
HEV | Hevié | Abomey-Calavi | published |
OUI | Ouidah | published | |
PAH | Pahou | Ouidah | published |
PNO | Porto-Novo | published | |
TOR | Tori-Bossito | on request |
A neighbourhood is a valid name. Cococodji, Hevié, Akassato and Pahou are priced as their commune: send the name your customer gave you, and the neighbourhood stays in the address, where the rider reads it.
Two communes in the zone have no published rate yet. We go there, but the quote answers price_on_request: call us and we will set it.
curl https://api.sendit-bj.com/v1/cities -H "Authorization: Bearer sk_live_votre_cle" Call /v1/cities rather than copying this list. It will grow, and your form will follow without you touching it.
Outside the zone it is a refusal, not an invitation to call: Comé is 61 km from the counter, Lokossa 90, Bohicon 114. A tricycle that has to be home by evening does not go.
Price a parcel
Before creating it, to show in the basket. The price this returns is exactly the price that will be charged: it is the same function on both sides, so your checkout cannot quote an amount the counter would refuse.
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
} Size is named, or measured. If you know your boxes in centimetres, send length, width and height and we pick the bracket.
collection is BRANCH if you bring the parcel to our Godomey counter, HOME if we come and collect. From anywhere but Calavi, HOME is the default: there is only one counter. The second costs more, and the grid says how much.
Amounts are whole CFA francs. The CFA franc has no minor unit: none of our amounts has a decimal, anywhere.
Create a parcel
One call and the parcel exists. We return its tracking code and the link you can drop into your order confirmation.
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"
} The fields
| Field | Type | What it is |
|---|---|---|
reference | ≤ 64 | Your order number. Required. |
recipient | { name, phone } | The recipient name and number. |
destination | { city, address } | Delivery city and address. |
origin | { city } | Departure city. Defaults to yours. |
size | enum | XS_S, MEDIUM, LARGE or XL. Or dimensions_cm instead. |
dimensions_cm | { length, width, height } | Length, width, height in centimetres. |
collection | enum | BRANCH (you drop off at Godomey) or HOME (we collect). |
description | ≤ 280 | What is inside. For you and for the counter. |
reference is your protection against shipping twice
Your order number is the idempotency key. If your server retries because the connection dropped, we hand back the parcel already created, with a 200 instead of a 201. We do not ship the same order twice, and you write nothing special for that.
The address
In Benin an address is a landmark: "opposite the Sainte-Marie pharmacy", "Gbegnigan junction, blue gate". Write what your customer gave you. The rider will call anyway, and a true landmark beats an invented street number.
The number must be a mobile
The recipient gets a four-digit code on WhatsApp and reads it out to the rider at the door: that is what proves the parcel reached the right person. A landline cannot receive it, so we refuse the parcel rather than deliver it without proof. Both Benin formats work, eight digits and ten.
Pass the code on yourself
On request we add the codes:read permission to your key, and the create response then carries delivery_code, the four digits your customer will read out to the rider. You send them in your own channel, under your own brand, when you choose.
{
"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"
} It comes out ONCE, at creation. GET /v1/parcels/{code} never returns it, even with the permission. If you lose it, call us.
Track a parcel
By its tracking code. Add ?timeline=1 for the full history of stages, with times.
curl https://api.sendit-bj.com/v1/parcels/SDT-COT-PNO-0001250?timeline=1 \
-H "Authorization: Bearer sk_live_votre_cle" The statuses
A parcel never moves backwards. If two events reach you out of order, the time decides, not the order of arrival.
| Status | Where the parcel is |
|---|---|
REGISTERED | Registered with us. The recipient has their code. |
COLLECTED | Picked up, from you or at the counter. |
AT_ORIGIN_HUB | At the departure hub, waiting for the next vehicle. |
IN_TRANSIT | On the road, between two cities. |
AT_DESTINATION_HUB | Arrived in the destination city. |
OUT_FOR_DELIVERY | With the rider, on the round. |
DELIVERED | Handed over. Code read out, or signature. |
DELIVERY_FAILED | Attempted without success. A reason is recorded. |
RETURNING | On its way back to the sender. |
RETURNED | Back with the sender. |
CANCELLED | Cancelled. |
LOST | Lost. We will have called you before you read this. |
The list
Your parcels, newest first. Pagination is by cursor, not page number: a parcel created while you page through shifts nothing.
curl -G https://api.sendit-bj.com/v1/parcels -d limit=50 \
-H "Authorization: Bearer sk_live_votre_cle" The tracking link
Every response carries tracking_url. It is a public page, no key, that you can drop straight into your confirmation email. It shows no price, no phone number and no counterparty name.
https://sendit-bj.com/?code=SDT-COT-PNO-0001250 Cancel
While the parcel has not left the departure hub. After that it is on the road to another city: it needs a return, which is a second journey, and we settle that on the phone.
curl -X POST https://api.sendit-bj.com/v1/parcels/SDT-COT-PNO-0001250/cancel \
-H "Authorization: Bearer sk_live_votre_cle" A parcel already in transit answers conflict. That is not a final refusal, it is a conversation to have.
Notifications
Rather than polling the API, give us a URL and we will call you on every change. One kind of event, because one thing changes.
Register a URL
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" }' We return a secret once, at creation. Keep it: it is what you verify the call with.
What you receive
{
"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"
} Verify the signature
Your webhook URL is public: anyone can send you a POST that looks like ours. If your shop releases an order on "delivered", that is exactly the call someone will want to forge.
The header carries the timestamp and the signature. Rebuild the signed string, compute HMAC-SHA256 with your secret, and compare in constant time. The timestamp is signed together with the body: without it, one valid call captured once would be replayable for ever.
Refuse anything older than 5 minutes, even with a good signature.
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);
} If you do not answer
Any 2xx counts as received. Otherwise we retry six times, spacing them out, then give up, and we suspend the URL after twenty consecutive failures. Answer fast and process afterwards: a webhook does not wait for your database.
List and delete
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" The sandbox
With a test key everything works identically, and nothing exists. No real parcel, no WhatsApp, no invoice, nothing in our figures. Test parcels are deleted after thirty days.
Move a parcel along
One thing production does not have. Walk the whole cycle to DELIVERED and watch your code handle it, without waiting for a tricycle to reach Porto-Novo. The state machine is the same: an illegal jump answers 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" }' In production this call answers forbidden. A parcel moves when a rider moves it, not when a shop says so.
Getting started
- Ask us for your keys. We need the shop name, a WhatsApp contact (it will be the sender of all your parcels) and the city your parcels leave from.
- With the test key: the cities, then a quote, then a parcel, then advance to DELIVERED.
- Point a webhook at your test environment and verify the signature.
- Tell us when you are ready and we hand over the live key.
A question
Message us on WhatsApp, call, or come to the office.
Request my keys