SendIt Back to the site Français

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.

Three online shops, basket, order and payment, call SendIt in JSON. Out of SendIt come a parcel, a doorstep delivery and a WhatsApp notification.

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.

PermissionWhat 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.

StatusWhere 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

  1. 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.
  2. With the test key: the cities, then a quote, then a parcel, then advance to DELIVERED.
  3. Point a webhook at your test environment and verify the signature.
  4. 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