1.1 What the API does for you

Every one of those lookups is cached after first use, is safe to repeat, and never requires you to know an internal primary key.

1.2 Live deployment

The API is deployed and serving.

2.1 Signing in

The API holds no password of its own. Each sign-in is verified against your IMBox account and accepted only if it is valid and the account is an organisation. Two consequences follow: there is no second password for your team to manage, and revoking your IMBox account revokes console access at the same moment.

Sign-in attempts are rate limited to five per minute per source address.

2.2 Overview

The landing page after sign-in contains information about the organisation’s activity and webhook configuration.

2.3 Credentials

Where your developers collect the values their code needs. The page is divided into three independent credentials, each serving a different purpose.

2.4 Webhooks

One destination URL per event. The API posts to these as orders progress.

Send test is the fastest route to a working integration: it exercises your endpoint, your signature verification and your parser before a real parcel is involved.

Press Save all endpoints to persist changes.

2.5 Deliveries

An audit trail of the last fifty callback attempts.

A status of no endpoint means the event occurred and was recorded but no URL was configured for it. The event is still readable through the activity log API, so nothing is lost.

3.1 Collect your credentials

Sign in to the console and open Credentials (see The console section). You need two values:

• Client id — always shown on the page.
• Client secret — press Rotate to reveal it once, then copy it straight into your secret manager.

Export them so the commands below can reuse them:

export BASE="https://ecommerce.api.imbox.solutions"
export CLIENT_ID="<your client id>"
export CLIENT_SECRET="<your client secret>"

3.2 Get an access token

export TOKEN=$(curl -s -X POST "$BASE/oauth2/token/" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  | python -c "import sys, json; print(json.load(sys.stdin)['access_token'])")
echo "$TOKEN"

The token lasts an hour — cache it and reuse it on every call below.

3.3 Create a test order

Send identifiers only. The API resolves the customer and courier, reserves a cell of the requested size, and returns the two access codes.

Note — station_id must be a locker station IMBox has assigned to your organisation. If you do not have one yet, please contact the IMBox team to have a station provisioned and to receive its identifier. The example below uses MALL-MASR-001 for illustration.

curl -s -X POST "$BASE/api/v1/orders/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "station_id": "MALL-MASR-001",
        "customer_id": "CUST-1001",
        "courier_id":  "CR-7",
        "cell_size":   "medium",
        "order_id":    "TEST-0001",
        "idempotency_key": "TEST-0001"
      }'

Response — 201 Created

{
  "order_id": "TEST-0001",
  "status": "CREATED",
  "station_id": "MALL-MASR-001",
  "cell_id": "3",
  "cell_size": "medium",
  "customer_id": "CUST-1001",
  "courier_id": "CR-7",
  "customer_code": "8251372",
  "courier_code": "2875912",
  "codes_available": true
}

The two codes are the heart of the flow: courier_code opens the cell for the courier to deposit the parcel, and customer_code opens it for the recipient to collect it. Distribute them through your own channels.

idempotency_key makes the call safe to retry — replaying the same key returns the original order instead of creating a second one.

3.4 List your orders and their status

curl -s "$BASE/api/v1/orders/?customer_id=CUST-1001" \
  -H "Authorization: Bearer $TOKEN"

Response — 200 OK

{
  "count": 1,
  "pages": 1,
  "results": [
    { "order_id": "TEST-0001", "status": "CREATED", "cell_id": "3", "…": "…" }
  ]
}

status moves through CREATED → DROPPED → PICKED (or EXPIRED / FAILED) as the courier and recipient act at the locker keypad. Combine status=, date=, station_id= and the other filters — see List orders.

3.5 Read one order’s codes and history

curl -s "$BASE/api/v1/orders/TEST-0001/" \
  -H "Authorization: Bearer $TOKEN"

This returns the full order — including customer_code and courier_code — with its event history (create, reserve, sync). If the codes could not be read at creation time (codes_available: false), retrieving the order fetches them again.

3.6 Register a webhook and test it

Rather than polling, let the API call you as the order progresses.

1. In the console, open Webhooks (see The console).
2. Enter your HTTPS endpoint for the events you care about — order.created, order.dropped, customer.notified, order.picked, order.expired and order.failed.
3. Press Send test. The API immediately POSTs a representative payload and reports the status code, latency and response body — so you validate your endpoint, your signature check and your parser before a real parcel is involved.

Every callback is signed. Verify it against the raw body, before any JSON parsing:

import hmac, hashlib, time

def verify(secret, headers, raw_body):
    timestamp = headers.get("X-IMBox-Timestamp", "")
    signature = headers.get("X-IMBox-Signature", "")
    if not timestamp or not signature:
        return False
    if abs(time.time() - int(timestamp)) > 300:      # reject stale replays
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

The webhook signing secret is on the Credentials page; the full payload and header reference is in Webhooks.

3.7 Force a status refresh (optional)

The API keeps statuses current on its own. To pull the latest immediately — handy while testing — call:

curl -s -X POST "$BASE/api/v1/orders/sync/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

Any status change it discovers dispatches the matching webhook. You have now created an order, read its codes, listed it, and wired up callbacks — the whole integration in miniature.

4.1 Requesting a token

POST /oauth2/token/

Send your client id and secret using Basic authentication.

curl -X POST https://ecommerce.api.imbox.solutions/oauth2/token/ \
  -u "<client_id>:<client_secret>" \
  -d grant_type=client_credentials

Response — 200 OK

{
  "access_token": "Q5nHSrdYTtIc9m2K0pLxWvB3aRt7Ye",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "orders:read orders:write stations:read logs:read"
}

Response — 401 Unauthorized — the client id or secret is wrong.

4.2 Scopes

4.3 Optional request signing

Where payload integrity and replay protection are required, the API also accepts IMBOX-HMAC-SHA256 request signatures alongside the bearer token. Four additional headers are sent: X-IMBox-Key, X-IMBox-Timestamp, X-IMBox-Nonce and X-IMBox-Signature. The signature covers the method, path, canonical query string, body digest, timestamp, nonce and OAuth2 client id, so a captured signature cannot be replayed, redirected to another endpoint, or used by another organisation. Contact the IMBox team to enable enforcement for your organisation.

5.1 Create an order

POST /api/v1/orders/ — scope orders:write

Creates a parcel order from identifiers alone. The API resolves the customer, courier, billing plan and notification template — creating any that do not yet exist — reserves a cell of the requested size at the station, and returns the access codes for the courier and the customer.

curl -X POST https://ecommerce.api.imbox.solutions/api/v1/orders/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "station_id":      "MALL-MASR-001",
        "customer_id":     "CUST-9917",
        "courier_id":      "CR-42",
        "cell_size":       "small",
        "order_id":        "VF-2026-0001",
        "idempotency_key": "VF-2026-0001"
      }'

{
  "order_id": "VF-2026-0001",
  "status": "CREATED",
  "station_id": "MALL-MASR-001",
  "cell_id": "2",
  "cell_size": "small",
  "customer_id": "CUST-9917",
  "courier_id": "CR-42",
  "billing_id": "STANDARD",
  "notification_id": "DEFAULT",
  "customer_code": "8251372",
  "courier_code": "2875912",
  "codes_available": true,
  "dropped_date": "2026-08-26",
  "picked_date": "2026-08-29",
  "upstream_order_id": "28",
  "failure_reason": "",
  "created_at": "2026-08-26T09:14:02.113Z",
  "dropped_at": null,
  "picked_at": null
}

{
  "error": "validation_error",
  "detail": "One or more fields are invalid.",
  "request_id": "c014d4147a2c47fb88e3228724a99027",
  "fields": {
    "customer_name":  ["Unknown field. Send identifiers only - no personal data."],
    "customer_phone": ["Unknown field. Send identifiers only - no personal data."]
  }
}

5.2 List orders

GET /api/v1/orders/ — scope orders:read

Returns your organisation’s orders, newest first. Every parameter is optional and they combine.

curl "https://ecommerce.api.imbox.solutions/api/v1/orders/?customer_id=CUST-9917&status=CREATED" \
  -H "Authorization: Bearer $TOKEN"

{
  "count": 12,
  "pages": 1,
  "page": 1,
  "page_size": 50,
  "next": null,
  "previous": null,
  "results": [ { "order_id": "VF-2026-0001", "status": "CREATED", "…": "…" } ]
}

5.3 Retrieve one order

GET /api/v1/orders/{order_id}/ — scope orders:read

Returns a single order together with its full history.

curl https://ecommerce.api.imbox.solutions/api/v1/orders/VF-2026-0001/ \
  -H "Authorization: Bearer $TOKEN"

{
  "order_id": "VF-2026-0001",
  "status": "DROPPED",
  "events": [
    { "action": "create",  "to_status": "CREATED", "note": "Order accepted",
      "occurred_at": "2026-08-26T09:14:02Z" },
    { "action": "reserve", "to_status": "CREATED", "note": "Cell 2 reserved",
      "occurred_at": "2026-08-26T09:14:07Z" },
    { "action": "sync",    "from_status": "CREATED", "to_status": "DROPPED",
      "note": "Status changed at the locker",
      "occurred_at": "2026-08-26T11:20:14Z" }
  ]
}

5.4 Refresh order statuses

POST /api/v1/orders/sync/ — scope orders:write

The courier and the recipient act at the locker keypad, not through this API, so the API discovers those transitions on its own. This runs automatically every two minutes. Call this endpoint to force an immediate refresh.

curl -X POST https://ecommerce.api.imbox.solutions/api/v1/orders/sync/ \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

{ "synced": 3 }

5.5 Activity log

GET /api/v1/logs/ — scope logs:read

An append-only record of everything that has happened to your orders and stations, filterable on every identifier you already hold.

curl "https://ecommerce.api.imbox.solutions/api/v1/logs/?station_id=MALL-MASR-001&date=last_week" \
  -H "Authorization: Bearer $TOKEN"

{
  "count": 3,
  "results": [
    {
      "occurred_at": "2026-08-26T09:14:07Z",
      "event_type": "ORDER_CREATED",
      "station_id": "MALL-MASR-001",
      "cell_id": "2",
      "order_id": "VF-2026-0001",
      "customer_id": "CUST-9917",
      "courier_id": "CR-42",
      "organization_id": "12",
      "message": "Order VF-2026-0001 is CREATED",
      "request_id": "c014d4147a2c47fb88e3228724a99027"
    }
  ]
}

5.6 List locker stations

GET /api/v1/stations/ — scope stations:read

curl https://ecommerce.api.imbox.solutions/api/v1/stations/ \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "station_id": "MALL-MASR-001",
    "name": "Mall Masr",
    "location": "6th of October",
    "status": "ACTIVE",
    "cells_total": 6,
    "cells_free": 2,
    "cells_occupied": 1,
    "cells_reserved": 3
  }
]

5.7 Retrieve one station

GET /api/v1/stations/{station_id}/ — scope stations:read

Returns the single station object shown above.

Other responses: 404 not_found.

5.8 List cells at a station

GET /api/v1/stations/{station_id}/cells/ — scope stations:read

curl "https://ecommerce.api.imbox.solutions/api/v1/stations/MALL-MASR-001/cells/?status=free" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "cell_id": "2",
    "station_id": "MALL-MASR-001",
    "station_name": "Mall Masr",
    "size": "small",
    "status": "free",
    "state": "active"
  }
]

5.9 Customers and couriers

GET /api/v1/customers/, GET /api/v1/couriers/ — scope orders:read

The identifiers your organisation has used, with per-party counters. No personal attribute is returned, because none is held.

GET /api/v1/customers/{customer_id}/, GET /api/v1/couriers/{courier_id}/ return one record.

{
  "id": "CUST-9917",
  "kind": "customer",
  "provisioned": true,
  "first_seen": "2026-08-01T09:14:22Z",
  "last_seen": "2026-08-26T09:14:02Z",
  "orders_total": 14,
  "orders_open": 1,
  "orders_picked": 12
}

5.10 Health

GET /api/v1/health/ — no authentication required

curl https://ecommerce.api.imbox.solutions/api/v1/health/

{
  "status": "ok",
  "version": "1.3.16",
  "database": "ok",
  "upstream": {
    "reachable": true,
    "authenticated": true,
    "configured": true
  },
  "codes_readable": true,
  "hmac_required": false
}

6.1 Events

6.2 Payload

Every event uses the same envelope.

{
  "event": "order.dropped",
  "event_id": "evt_9c1e77a30b5d4f62",
  "occurred_at": "2026-08-26T11:20:14Z",
  "data": {
    "order_id": "VF-2026-0001",
    "status": "DROPPED",
    "station_id": "MALL-MASR-001",
    "cell_id": "2",
    "cell_size": "small",
    "customer_id": "CUST-9917",
    "courier_id": "CR-42",
    "billing_id": "STANDARD",
    "notification_id": "DEFAULT",
    "customer_code": "8251372",
    "courier_code": "2875912"
  }
}

Identifiers and codes only — the same rule applies outbound as inbound.

6.3 Headers

6.4 Verifying a callback

import hmac, hashlib, time

def verify(secret, headers, raw_body):
    timestamp = headers.get("X-IMBox-Timestamp", "")
    signature = headers.get("X-IMBox-Signature", "")
    if not timestamp or not signature:
        return False
    if abs(time.time() - int(timestamp)) > 300:      # reject stale replays
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Verify against the raw body, before any JSON parsing — re-serialising changes the bytes and the signature will not match.

6.5 Delivery behaviour

Delivery never blocks the API call that triggered it. Every attempt is visible on the console’s Deliveries page. If no endpoint is configured, the event is still recorded and remains readable through the activity log.

7.1 Status codes

7.2 Error codes

8.1 What is refused

The order endpoint accepts a closed set of fields. Anything outside it is rejected with 400 and the offending field names returned. customer_name, customer_phone, address, email are not “ignored” — they cause the request to fail. Your integration cannot accidentally leak personal data into the API, because there is no code path that accepts it.

8.2 What is stored

The API’s schema contains no column for a name, telephone number, email address or postal address. The complete record of a party is:

There is nowhere to put personal data even if someone tried.

8.3 How a party is represented

A party record requires a name, an email address and a telephone number, unique across the system. The API satisfies those constraints without involving a real person, by deriving every value from a pseudonym:

pseudonym = HMAC-SHA256(server_key, "customer:CUST-9917")[:12]
          = "b039cbaa1024"

The mapping is deterministic, so the same identifier always resolves to the same record and no duplicate is ever created. It is keyed, so your identifiers cannot be recovered from anything the API holds. And the addresses are undeliverable by construction, so no message can escape to a real recipient.

8.4 Consequences

• The link between an identifier and a person exists only in your systems.
• The API cannot re-identify anyone.
• A database disclosure exposes identifiers, not people.
• Your obligations under data-protection regimes are materially narrowed, because the personal data never leaves your control in the first place.

9.1 A contract that does not move

Cell sizes, station types, billing models and status vocabularies evolve over time. The API keeps a stable contract over all of it: statuses are mapped to a fixed set, size names are canonicalised, and internal identifiers are never exposed. Such changes never reach your integration.

9.2 Adding capability

New capabilities reach you by extension, not migration:

• A new station type appears in GET /api/v1/stations/ with no client change at all.
• A new cell size becomes an additional accepted value for cell_size.
• A new identifier kind — a locker bank, a contract, a cost centre — follows the same resolution pattern already used for customers, couriers, billing plans and templates: send an identifier, get a resolved record.
• A new event is added to the webhook set; endpoints you have not configured are simply not called.

Additive changes do not break existing clients. Fields are added, never repurposed, and the API is versioned under /api/v1/ so a breaking change would arrive as /api/v2/ alongside it.

9.3 Multiple organisations

Each organisation is issued its own credentials, scopes, webhook endpoints and activity log. Data is partitioned per organisation at the query layer: one organisation cannot read another’s orders, and identifier collisions between organisations are impossible because mappings are namespaced. Onboarding a new partner requires no deployment.

9.4 Availability

The API keeps its own record of every order it creates. Order history, identifier mappings and the activity log stay queryable, and read endpoints serve stored data — so your reporting does not depend on any single component being reachable.