# Changelogs

# Change Log — 2026-11-17

**Author**: Josh S. Sakweli, Backend Lead Team  
**Version**: v1.0

**Short Description**: Who is bringing the parcel, and voice calls about a parcel between the buyer, the shop and whoever delivers it. **Nothing here is breaking**: fields were only added, no field changed shape or was removed.

---

## 1. Order details: who is bringing it

**ADDED** `fulfillment.shippers[].assignedTo`, on every order response that already carries `fulfillment`.

```json
"shippers": [
  { "leg": 0, "businessId": "…", "name": "EMS Courier", "phone": "+255…",
    "assignedTo": { "accountId": "…", "name": "Mama Yoyo", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } } }
]

```

- The person the shipper assigned to that leg; **absent** while nobody is assigned (the shipper itself is delivering). It follows the job: moved to Juma → Juma.
- Buyer: "Mama Yoyo · EMS Courier is delivering". Shop: "Mama Yoyo · EMS Courier is coming to collect".
- **Never the assigned person's phone number.** To reach them, use the NexGate call (section 2). `phone` is still the business's.
- Pictures follow the standard: `userProfileMedia` (`fileId`, `status`, `thumbUrl`, `mimeType`), never a bare URL.

## 2. Calls about a parcel (new)

Voice calls between the **buyer**, the **shop** and **whoever delivers** one order, open from the moment a shipper accepts until the order is **completed or cancelled**. Full API: `docs/team/api/nexgate_app_team_api.md` Part 8.

**NexGate app (buyer):** on the order page show **two buttons**:

- **Call shop**: unchanged, `POST /calls` with `targetShopId` (any time).
- **Call delivery** (only while the delivery is going on): `POST /work-calls` with `{ "orderId": "…", "to": "DELIVERY" }`. It rings the shipper: the person assigned to the job now, or the shipper itself. The answer carries the room token and `calling` (who is being rung) and `allLinesBusy` ("Everyone is on another call. Please wait, or call back later").

**NexGate app (shop owner):** the same **Call delivery** with `"shopId"` added, to call as the shop.

**Who is on the other side** (`calling`, `other`, `caller` in every call response):

```json
{ "role": "SHIPPER", "name": "EMS Courier", "businessLogoMedia": { … },
  "assignedTo": { "accountId": "3213…", "name": "Mama Yoyo", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } },
  "orderNumber": "ORD-2026-23424", "parcelNumber": "NX-SQAW-ZL", "orderId": "0f05…" }

```

`role` is `BUYER`, `SHOP` or `SHIPPER`. A shipper is always the business; `assignedTo` is the person it assigned to the job (absent when the business itself is on the call). Pictures: `userProfileMedia`, `shopLogoMedia`, `businessLogoMedia`.

**Calls list:** `GET /work-calls` (my calls as a buyer) or `GET /work-calls?shopId=` (the shop's). Each row has `other`(who), `missed`, and `callBack` (what to send as `to` to call back; absent once the order's calls are closed). **Work calls do not appear in `GET /calls`**, which stays chat calls only: show both lists, or merge them by time.

**Answer / hang up:** `POST /work-calls/{callId}/join` and `/end` (`?shopId=` when acting as the shop).

## 3. Caller identification on rings

**ADDED, all optional,** to the `CALL_INCOMING` / `CALL_ENDED` pushes and the `call.incoming` live event (`docs/notifications/push_contracts_api_doc.md` v1.3 §4.2, §4.3, §4.8). Ordinary chat calls look exactly as before.

<table id="bkmrk-key-meaning-work-%22tr"><thead><tr><th>Key</th><th>Meaning</th></tr></thead><tbody><tr><td>`work`</td><td>`"true"` = a call about a parcel (no chat behind it, no `conversationId`)</td></tr><tr><td>`answerAs`</td><td>`ME` (token included, answer at once), `SHOP` or `BUSINESS` (no token: answer with the join endpoint, first one wins)</td></tr><tr><td>`shopId`, `shopName`</td><td>a call to the shop; now also reach the owner's phone (they were dropped before)</td></tr><tr><td>`callerRole`</td><td>`BUYER`, `SHOP`, `SHIPPER` (the delivery business)</td></tr><tr><td>`callerName`, `callerAvatar`</td><td>the buyer, the shop, or the shipper (business name and logo)</td></tr><tr><td>`assignedToAccountId`, `assignedToName`, `assignedToAvatar`</td><td>`SHIPPER` only: the person the shipper assigned to the job, who is calling</td></tr><tr><td>`parcelNumber`</td><td>always on a work call</td></tr><tr><td>`orderNumber`, `orderId`</td><td>**only to the buyer and the shop**, never to a shipper</td></tr></tbody></table>

Draw the line yourselves, e.g. "EMS Courier · Mama Yoyo · order ORD-2026-23424". The server sends fields, never a sentence.

## 4. New notifications

- `ORDER_MISSED_CALL` (bell + push, opens the order): "Missed call about order ORD-…", with `caller.name`, `call.time`, `orderNumber`, `parcelNumber`.
- Shipper app only: `WORK_CALL_INCOMING`, `WORK_CALL_ENDED`, `WORK_CALL_MISSED`.

## 5. Errors you may see on `POST /work-calls`

All `409` with a `code`: `NO_SHIPPER_YET` (no shipper accepted yet), `CALLS_CLOSED` ("This delivery is finished"), `BUSY` (they are on another call), `USE_SHOP_CALLS` (buyer ↔ shop goes through `POST /calls`), `SAME_PERSON` / `OWN_SHOP` / `OWN_BUSINESS` (nobody else would answer: e.g. buying from your own shop), `NOT_ON_THIS_ORDER`.