API Documentation

curl -X POST https://api.areye.app/api/business/book \
  -H "X-Business-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ride",
    "passenger_name": "Jane Smith",
    "passenger_phone": "+267XXXXXXXX",
    "pickup_address": "Plot 64271, Block 3 Industrial, Gaborone",
    "pickup_lat": -24.6282,
    "pickup_lng": 25.9231,
    "dropoff_address": "Molapo Crossing Mall, Gaborone",
    "dropoff_lat": -24.6540,
    "dropoff_lng": 25.9110,
    "vehicle_type_id": 1,   // optional override — prefer declaring the goods (see below)
    "expense_code": "TRAVEL-Q3"
  }'

Choosing the vehicle

Describe what you are sending and Areye dispatches a vehicle that can carry it. You do not need to know our fleet, and you should not hard-code vehicle_type_id — a refrigerator booked as a sedan job is exactly the failure this prevents.

Call GET /business/parcel-sizes first. It returns the live size ladder — size_key, the kilogram range, the eligible vehicle types and the rates for each band. It is the authoritative answer to "which size is my package?" and it changes without notice to this page, so read it rather than hard-coding the bands below.

All four fields are optional. Send whichever you have. Send none and the booking behaves exactly as it always did. They combine freely: a weight and a body type together are both honoured. If parcel_weight_kg and parcel_size disagree — 2 kg declared as oversized, say — the larger of the two wins, so a consignment is never under-served because two declarations contradicted each other.

Field	Values	Use it when
parcel_weight_kg	any number	You know the weight. Simplest option.
parcel_size	small · medium · large · oversized	Shoebox · shopping bag · car boot · TV, bicycle, appliance.
cargo_body_type	closed · open · refrigerated	The load needs a particular body — an open bakkie for building materials, a closed body for anything weatherproof. Refrigerated is commercial cold-chain for bulk consignments; a retail order with frozen items does not need it and should not declare it.
cargo_capacity_class	half_ton · one_ton · three_ton · eight_ton	A minimum capacity, not an exact match.

You are billed for the vehicle your goods require. Areye always dispatches the smallest vehicle that can do the job, so declaring accurately never costs more than the job needs — but over-declaring dispatches and bills a larger vehicle. On a typical route the oversized band costs around four times the small band. Under-declaring causes a failed collection; over-declaring is simply expensive. Declare what you are actually sending.

vehicle_type_id remains an override. When the goods need more vehicle than the class you named, your account decides what happens: by default Areye upgrades and bills the larger class. Accounts can instead cap upgrades at one size, or refuse the order and return 422 with the reason. Declare nothing and nothing changes — existing integrations are unaffected.

Example — a refrigerator

curl -X POST https://api.areye.app/api/business/book \
  -H "X-Business-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "parcel",
    "passenger_name": "Recipient Name",
    "passenger_phone": "+267XXXXXXXX",
    "pickup_address": "Store address",
    "pickup_lat": -24.6282, "pickup_lng": 25.9231,
    "dest_address": "Delivery address",
    "dest_lat": -24.6531, "dest_lng": 25.9089,
    "parcel_weight_kg": 85,
    "cargo_body_type": "closed"
  }'

No vehicle_type_id is sent. Areye resolves 85 kg to the oversized band, sees that a closed body is required, and dispatches a cargo van or bakkie — never a sedan or a motorbike.

Batches — one driver, one vehicle

A batch submitted to POST /business/batches is collected by a single driver in a single vehicle, so Areye fits that vehicle to the largest stop in the run. One oversized item among twenty small ones sends a bakkie, not a motorbike.

Set each stop's size to small, medium, large or oversized (s / m / l / xl are accepted too). Each stop is priced on its own size; the vehicle is chosen for the whole run. cargo_body_type and cargo_capacity_class may be set at the top level to apply to the entire batch — a closed-body run, for example.

The per-stop field is size (not parcel_size — that name belongs to /business/book). A stop may also carry weight_kg, and where a stop gives both, the larger of the two decides that stop — for its own price and for the batch's vehicle.

curl -X POST https://api.areye.app/api/business/batches \
  -H "X-Business-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "parcel",
    "stops": [
      {
        "recipient_name": "First Recipient",
        "recipient_phone": "+267XXXXXXXX",
        "pickup_address": "Store", "pickup_lat": -24.6282, "pickup_lng": 25.9231,
        "dest_address": "Drop 1",  "dest_lat": -24.6531,  "dest_lng": 25.9089,
        "size": "small"
      },
      {
        "recipient_name": "Second Recipient",
        "recipient_phone": "+267XXXXXXXX",
        "pickup_address": "Store", "pickup_lat": -24.6282, "pickup_lng": 25.9231,
        "dest_address": "Drop 2",  "dest_lat": -24.6402,  "dest_lng": 25.9155,
        "weight_kg": 85
      }
    ]
  }'

The first stop is priced as a small parcel and the second as oversized, but the whole run is collected by a vehicle able to carry the 85 kg item.

If no vehicle can satisfy the batch, the request is rejected with 422 and nothing is created — a batch fails whole, never part-way through.

Verifying what Areye decided

The 201 response, GET /business/trips and GET /business/trips/{reference} all echo what you declared and what we resolved, so you never have to infer it from the fare:

{
  "parcel_size": "oversized",
  "parcel_size_label": "Oversized",
  "parcel_weight_min_kg": 30.0,
  "parcel_weight_max_kg": 500.0,
  "cargo_body_type": "closed",
  "cargo_capacity_class": null,
  "volumetric_weight_kg": null,
  "vehicle_class": {
    "id": 5, "name": "Cargo Van",
    "body_type": "closed", "capacity_class": "one_ton"
  },
  "vehicle_upgraded": true,
  "vehicle_upgrade_reason": "Budget cannot carry this consignment (Oversized) — dispatched Cargo Van instead.",
  "test": false
}

vehicle_class is the class the order will actually be sent. vehicle_upgraded tells you whether we sent something larger than your request implied, and why.

Custody scanning — proving which bag

A collection photo and a driver signature prove that a handover happened. They do not prove which bag moved — so an unlabelled bag handed to the wrong driver still produces a perfect-looking record. Custody scanning closes that gap, and it is a premium add-on: ask Areye to enable it on your account.

When it is enabled, every merchant order comes back with a scan_code and a scan_label_url. Nothing else about your integration changes.

{
  "reference": "BIZ-1A7DED",
  "scan_code": "4EY2-Y6GD",
  "scanned_at": null,
  "scan_label_url": "https://api.areye.app/api/business/trips/BIZ-1A7DED/label"
}

What your picker app does

1. Finish picking and packing the order as you do today.
2. Fetch scan_label_url — an A6 PDF label carrying the QR (encoding scan_code) with your order number printed underneath it. Print it and stick it on the bag.
3. Show the same code on your handover screen, so the person releasing the bag can match the physical label to the electronic one before the driver takes it.

The QR is Areye's custody token; the order number is for your staff and the driver reading it by eye. Two audiences, one sticker. If you would rather generate the label yourself, encode scan_code verbatim as a QR — the driver's scanner accepts it with or without the hyphen, and in any case.

What the driver does

The driver scans the label (or types the code beneath it) before collecting. They cannot mark the order collected until that scan matches. Scanning a label from a different order is rejected with “that label belongs to a different order” — which is the whole point: the mismatch surfaces while the driver is still standing in your store, not at a customer's door.

Labels do get torn and printers do jam, so a driver may force collection through. That is never silent: the override and its reason are recorded on the order, and scanned_at stays null so a forced collection is always distinguishable from a real scan.

Field	Meaning
scan_code	The custody token to encode as a QR. Absent when the add-on is off.
scan_label_url	A ready-made A6 PDF label. Same auth header as any other call.
scanned_at	When the driver matched the bag. Null until then — and stays null on a forced collection.

Sandbox bookings

A booking with "test": true moves no money and is dispatched to nobody. Every trip representation carries "test": true|false, and GET /business/trips?test=0 hides sandbox trips from your live list (?test=1 shows only them; omit it for everything).

{
  "success": true,
  "data": {
    "reference": "ARY-8F3A21",
    "status": "pending",
    "type": "ride",
    "fare": 85.00,
    "currency": "BWP",
    "tracking_url": "https://api.areye.app/api/trip-track/ARY-8F3A21"
  }
}