Operator integrations · API

One window for every parcel.

Push delivery events from your operations system into NIBANDHAK with a signed M2M API. Every successful delivery feeds the regulator's monthly levy (0.20 BDT/parcel) — invoices are auto-generated on the 1st of every month.

1 · Get your API key

One company can hold multiple keys (prod, staging, ops team). The plaintext key + HMAC secret are shown once — store them in your integration vault immediately.

Key label

Your existing keys

Loading…

2 · Sign your requests

Every request carries an X-Api-Key header and an X-Signature computed from the body. Constant-time compare on the server prevents timing attacks; replaying a request with a tampered body is rejected.

Signature formula

signature = hex( SHA256( secretHash + ":" + raw_request_body ) )

# secretHash = hex( SHA256(plaintext_hmac_secret) )
# raw_request_body = exact bytes you POST

import { createHash } from 'node:crypto';

const API_KEY = process.env.NIBANDHAK_API_KEY;       // nbd_live_...
const HMAC_SECRET = process.env.NIBANDHAK_HMAC;      // shown once at creation
const secretHash = createHash('sha256').update(HMAC_SECRET).digest('hex');

export async function pushDelivery(payload) {
  const body = JSON.stringify(payload);
  const signature = createHash('sha256')
    .update(`${secretHash}:${body}`)
    .digest('hex');

  const res = await fetch('https://nibandhak.ticonsys.com/api/m2m/deliveries', {
    method: 'POST',
    headers: {
      'X-Api-Key': API_KEY,
      'X-Signature': signature,
      'Content-Type': 'application/json',
    },
    body,
  });
  if (!res.ok) throw new Error(`Push failed: ${res.status} ${await res.text()}`);
  return res.json();
}

3 · Endpoints

POST/api/m2m/deliveries

Push a single parcel event.

Request

{
  "tracking_code": "AWB-2026-0001",
  "status": "delivered",
  "origin_district_id": 1,
  "destination_district_id": 13,
  "value_paisa": "50000",
  "weight_grams": 750,
  "shipped_at": "2026-05-18T11:00:00Z"
}

Response

{ "data": { "id": "uuid", "accepted": 1 } }

status: one of: created · processed · in_transit · delivered · failed · returned
levy: each "delivered" event accrues 0.20 BDT to your monthly invoice

POST/api/m2m/deliveries/batch

Push up to 500 events in one request.

Request

{
  "events": [
    { "tracking_code": "AWB-2026-0001", "status": "delivered" },
    { "tracking_code": "AWB-2026-0002", "status": "delivered" },
    ...
  ]
}

Response

{ "data": { "accepted": 247 } }

limit: 500 events per request; chunk larger batches
idempotency: duplicate tracking_codes are NOT deduped — your system is the source of truth

GET/api/m2m/whoami

Probe endpoint — confirm your key + signing pipeline.

Request

(empty body; sign empty string)

Response

{ "data": { "company_id": "your-uuid" } }

use: integration tests / monitoring health-check

4 · How the levy works

The regulator's revenue stream is fully automated from your ingested data — no extra reporting forms.

You push events

Every successful delivery flows through the M2M API.

Monthly cron runs

On the 1st of the next month, NIBANDHAK aggregates count × rate.

Invoice issued

You receive a levy invoice payable within 15 days.

Dispute or pay

Dispute the count from your dashboard, or pay via existing EPS rail.

Current rate: 0.20 BDT per successfully booked parcel. View your invoices anytime at your operator dashboard.

5 · Limits & gotchas

Rate limit: 100 req/min/key, 500 events per batch.
Body size: 1 MB max — chunk larger payloads.
Auth: X-Api-Key + X-Signature both required; missing either → 401.
Clock: use ISO-8601 UTC for shipped_at. Asia/Dhaka offsets accepted but converted server-side.
Errors: consistent JSON envelope { "error": { "code", "message" } }.
Audit: every successful POST is logged with payload SHA-256 — useful in disputes.

Hit a wall? Email helpdesk@mocsla.gov.bd with your key prefix and the request payload hash.