# Endpoints

# NexGate App — Team APIs

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated**: 2026-11-17  
**Version**: v1.0

**Base URL**: `https://api.nexgate.co/api/v1`

**Short Description**: Everything the NexGate app (Android, iOS, web) needs for teams: a **shop owner** builds her team,
roles and shop computers and takes calls; **anyone** answers invites and adds themselves to a shop computer; a **buyer**
sees who is bringing the parcel and can call the delivery. Read [`README.md`](README.md) first for roles, rights and
terminals.

**Hints**:
- Every call here uses the person's normal login: `Authorization: Bearer <access token>`.
- Shop-owner screens use `{kind}` = `shops` and `{placeId}` = the shop id.
- Find people with the existing user search / username lookup (it shows photo and name), then send their **`accountId`**.
- When the team feature is off, team endpoints answer **404**: hide the Team entry.
- Coded refusals are **409** with `data.code` (full list in the README).

---

## Contents

- Part 1 — How it works (flows)
- Part 2 — Shop owner: the team (1–7)
- Part 3 — Shop owner: roles (8–11)
- Part 4 — Activity (12–13)
- Part 5 — Shop owner: shop computers (14–19)
- Part 6 — Shop owner: orders, chat and calls with staff (20–28)
- Part 7 — Any person: my teams (29–33)
- Part 8 — Calls about a parcel (buyer and shop) (34–39)
- Part 9 — Additions to existing responses and pushes
- Part 10 — Notifications

---

# Part 1 — How it works

## 1.1 Inviting someone

```
 OWNER (NexGate app)                         SERVER                                 JANE (NexGate app)
 ───────────────────                         ──────                                 ──────────────────
 search "jane" ─► user search ─► picks Jane
 POST /team/shops/{shopId}/invites ────────► member row: INVITED (6 hours)
   { accountId, shopRoleId }                  push + bell TEAM_INVITE ────────────► "Mama Yoyo invited you
                                                                                      to My Shop With Banner"
                                                                                    GET /team/me
                                                                                      → invites[ … ]
                                              ◄──────────────────────────────────── POST /team/invites/{id}/accept
 bell TEAM_INVITE_ANSWERED ◄──────────────── member row: ACTIVE
 GET /team/shops/{shopId}/members → Jane ACTIVE
```

- **By phone number** instead: send `phone`. Someone not on NexGate gets an SMS to sign up with that number; the invite
  waits for them. The owner sees only the number she typed until they accept: it never reveals who owns a number.
- Invites end after **6 hours**. The owner can withdraw one before it's answered.

## 1.2 Linking a shop computer

```
 COUNTER PC (terminal app)                SERVER                             OWNER (NexGate app)
 ─────────────────────────                ──────                             ───────────────────
 POST /team/terminal-link/start ───────► code K7Q-4MX (30 s)
 shows K7Q-4MX big + QR
                                                                             scans QR / types K7Q-4MX
                                          ◄──────────────────────────────── GET /team/terminal-codes/K7Q-4MX
                                          "Link this Windows computer?" ───►
                                          ◄──────────────────────────────── POST /team/shops/{id}/terminals/link
                                                                              { userCode, label, permissions }
 POST /team/terminal-link/poll ────────► approved + terminal key (once)
 "Linked to My Shop With Banner"
```

## 1.3 A staff member adds themselves to the computer

```
 COUNTER PC                               SERVER                             JANE (her NexGate app)
 ──────────                               ──────                             ──────────────────────
 "Add me" → POST …/enrol/start ────────► code P2D-8WK
 shows QR                                                                    scans
                                          ◄──────────────────────────────── GET /team/terminal-codes/P2D-8WK
                                          "Add yourself to Counter PC?" ───►
                                          ◄──────────────────────────────── POST /team/terminal-codes/P2D-8WK/add-me
 polls → approved, "Hi Jane"
 Jane picks her PIN on the PC ─────────► Jane is on this computer, signed in
```

Only an **active member of that shop** can add themselves (owner and staff). Riders never sit at a computer.

## 1.4 Who rings when a customer calls the shop

```
 Customer taps Call shop
        │
        ▼
 Shop has computers ticked "Receive calls"? ──no──► the owner's phone rings (as before)
        │ yes
        ▼
 every such computer rings (people with Answer calls can pick up, even when locked)
        +
 owner's phone rings depending on her setting (Part 6):
     ALWAYS                 → rings
     WHEN_NOBODY_AT_SHOP    → rings only if nobody free is signed in at a computer   (default)
     NEVER                  → never rings
        │
        ▼
 first to answer has the call; the others stop ("Answered by Jane")
 nobody in 45 s → missed: card in the chat, missed-calls list, notice to the owner
```

## 1.5 Calls about a parcel

```
 Order: Amina bought from My Shop With Banner; EMS Courier delivers; Mama Yoyo rides it.

            ┌──────── open from "shipper accepted" until the order is completed or cancelled ────────┐
 Amina  ── Call delivery ──► the shipper: the person assigned to the job now (Mama Yoyo)
                              nobody assigned → EMS Courier itself: office computers + owner
 Shop   ── Call delivery ──► same
 EMS (Mama Yoyo, assigned) ── Call buyer ──► Amina's NexGate app
 EMS (Mama Yoyo, assigned) ── Call shop  ──► the shop's computers + owner (as 1.4)

 Amina ── Call shop ──► NOT a work call: the usual POST /calls (any time)
 Shop  ── call Amina ──► NOT a work call: from chat (24-hour window)
```

---

# Part 2 — Shop owner: the team

## 1. Invite someone
**Purpose**: Invite a NexGate user (by `accountId`) or a phone number to the shop, with a shop role.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/invites`

**Access Level**: 🔒 Protected (shop owner only)

**Authentication**: Bearer token

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | The shop | must be the caller's shop |

**Request JSON Sample**:
```json
{ "accountId": "5b0c8e1a-7a3e-4f0e-9c21-0d6f7e2a1b11", "shopRoleId": "c2a1f0d4-1e7b-4b5a-8f0e-2d9a6b3c4e55" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| accountId | UUID | One of accountId / phone | The person, from the user search | not the owner |
| phone | string | One of accountId / phone | Any format: `0754…`, `255754…`, `+255754…` | max 20; must be a valid number |
| shopRoleId | UUID | Yes | One of the shop's roles (Part 3) | must belong to this shop |
| role | string | No | Leave out for shops (always `STAFF`) | sending a business role → `ROLE_NOT_FOR_SHOPS` |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Invite sent", "action_time": "2026-11-17T10:30:45",
  "data": {
    "memberId": "b2e4…", "accountId": "5b0c…", "userName": "jane_k", "displayName": "Jane Kimaro",
    "avatarUrl": "https://…/thumb.jpg", "role": "STAFF", "shopRoleId": "c2a1…", "shopRoleName": "Order staff",
    "status": "INVITED", "inviteChannel": "ACCOUNT", "invitedPhone": null,
    "invitedAt": "2026-11-17T10:30:45", "inviteExpiresAt": "2026-11-17T16:30:45", "acceptedAt": null, "onDuty": false
  }
}
```

**Success Response Fields**: the member, as in [2. The team](#2-the-team).

**Errors**: `NOT_THE_OWNER`, `INVITE_WHO`, `SHOP_ROLE_REQUIRED`, `ROLE_NOT_FOR_SHOPS`, `CANNOT_INVITE_YOURSELF`,
`ALREADY_INVITED`, `TOO_MANY_INVITES` (20 per hour), `TOO_MANY_PHONE_INVITES` (5 per hour), `PHONE_INVALID`.

The person gets a push and a bell item (`TEAM_INVITE`). A phone invite to a number not on NexGate sends an SMS.

---

## 2. The team
**Purpose**: The owner first, then everyone invited, active or locked, oldest first.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/members`

**Access Level**: 🔒 Protected (shop owner only)

**Authentication**: Bearer token

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Team", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "memberId": "a1…", "accountId": "304e…", "userName": "joshua", "displayName": "Joshua Sakweli", "avatarUrl": "https://…",
      "role": "OWNER", "shopRoleId": null, "shopRoleName": null, "status": "ACTIVE", "inviteChannel": null,
      "invitedPhone": null, "invitedAt": null, "inviteExpiresAt": null, "acceptedAt": null, "onDuty": false },
    { "memberId": "b2…", "accountId": null, "userName": null, "displayName": null, "avatarUrl": null,
      "role": "STAFF", "shopRoleId": "c2a1…", "shopRoleName": "Order staff", "status": "INVITED",
      "inviteChannel": "PHONE", "invitedPhone": "+255754000111", "invitedAt": "2026-11-17T10:00:00",
      "inviteExpiresAt": "2026-11-17T16:00:00", "acceptedAt": null, "onDuty": false }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| memberId | The row to act on (role, lock, remove…) |
| accountId, userName, displayName, avatarUrl | The person; all `null` on a phone invite until it's accepted |
| role | `OWNER` or `STAFF` |
| shopRoleId, shopRoleName | The shop role |
| status | `INVITED`, `ACTIVE`, `LOCKED` |
| inviteChannel | `ACCOUNT` or `PHONE` |
| invitedPhone | Only the number the owner typed (phone invites) |
| invitedAt, inviteExpiresAt, acceptedAt | Invite times |
| onDuty | Riders only (shipper app); always `false` for shops |

---

## 3. Withdraw an invite
**Purpose**: Cancel an invite not yet answered. It disappears for the person; no push.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/members/{memberId}/withdraw`

**Access Level**: 🔒 Protected (shop owner only)

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| shopId | UUID | Yes | The shop |
| memberId | UUID | Yes | The invite row |

**Success Response**: `message` "Invite withdrawn", `data` = the member (status no longer `INVITED`).

**Errors**: `NOT_THE_OWNER`, `INVITE_NOT_OPEN`.

---

## 4. Change someone's role
**Purpose**: Give a staff member another shop role.

**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/team/shops/{shopId}/members/{memberId}/role`

**Access Level**: 🔒 Protected (shop owner only)

**Request JSON Sample**:
```json
{ "shopRoleId": "9d7e…" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopRoleId | UUID | Yes | The new role | one of this shop's roles |

**Success Response**: `message` "Role changed", `data` = the member. Their terminals re-read their rights at once.

**Errors**: `NOT_THE_OWNER`, `OWNER_ROLE_FIXED`, `SHOP_ROLE_REQUIRED`, `NOT_ON_TEAM`.

---

## 5. Lock someone
**Purpose**: Pause an active member. They are signed out of every shop computer at once.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/members/{memberId}/lock`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "Member locked", `data` = the member (`status` `LOCKED`). Calling twice is harmless.

**Errors**: `NOT_THE_OWNER`, `OWNER_CANNOT_BE_REMOVED`, `MEMBER_STATE`.

---

## 6. Unlock someone
**Purpose**: Let a locked member back in.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/members/{memberId}/unlock`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "Member unlocked", `data` = the member (`status` `ACTIVE`).

**Errors**: `NOT_THE_OWNER`, `MEMBER_STATE`.

---

## 7. Remove someone
**Purpose**: End a membership at once. History stays.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/members/{memberId}/remove`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "Member removed", `data` = the member. The person gets `TEAM_REMOVED` and is signed out of
every shop computer; their packing tags are cleared.

**Errors**: `NOT_THE_OWNER`, `OWNER_CANNOT_BE_REMOVED`, `NOT_ON_TEAM`.

---

# Part 3 — Shop owner: roles

## 8. List roles
**Purpose**: The shop's roles, with how many people have each. The three ready-made roles appear on first call.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/roles`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Shop roles", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "roleId": "c2a1…", "name": "Order staff", "rights": ["SEE_ORDERS", "HANDLE_ORDERS"], "readyMade": true, "members": 2 },
    { "roleId": "d3b2…", "name": "Customer care", "rights": ["SEE_ORDERS", "CUSTOMER_CHAT", "ANSWER_CALLS"], "readyMade": true, "members": 1 }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| roleId | The role |
| name | Shown to the owner and on the member's row |
| rights | Shop rights (README) |
| readyMade | Created by NexGate on first use; still editable |
| members | Active or invited people with this role |

---

## 9. Create a role
**Purpose**: A new role from the shop rights.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/roles`

**Access Level**: 🔒 Protected (shop owner only)

**Request JSON Sample**:
```json
{ "name": "Night shift", "rights": ["SEE_ORDERS", "HANDLE_ORDERS"] }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| name | string | Yes | Role name | 1–40 characters, unique in the shop |
| rights | array | Yes | Shop rights | at least one; enum: `SEE_ORDERS`, `HANDLE_ORDERS`, `CUSTOMER_CHAT`, `PRICE_OFFERS`, `ANSWER_CALLS`, `PRODUCTS`, `STOCK` |

**Success Response**: `message` "Role created", `data` = the role (shape as in 8).

**Errors**: `NOT_THE_OWNER`, `ROLE_NAME_TAKEN`, `ROLE_EMPTY`.

---

## 10. Change a role
**Purpose**: Rename or change rights. Everyone with the role gets the new rights at once (terminals re-read them).

**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/team/shops/{shopId}/roles/{roleId}`

**Access Level**: 🔒 Protected (shop owner only)

**Request JSON Sample**: same as 9.

**Success Response**: `message` "Role updated", `data` = the role.

**Errors**: `NOT_THE_OWNER`, `ROLE_NAME_TAKEN`, `ROLE_EMPTY`.

---

## 11. Delete a role
**Purpose**: Remove a role nobody has.

**Endpoint**: <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `{base_url}/team/shops/{shopId}/roles/{roleId}`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "Role deleted", `data` `null`.

**Errors**: `NOT_THE_OWNER`, `ROLE_IN_USE` (give those people another role first).

---

# Part 4 — Activity

## 12. Who did what
**Purpose**: The activity log, newest first. The owner sees everyone (or one person); a member sees only their own.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/{kind}/{placeId}/activity`

**Access Level**: 🔒 Protected (owner: everyone; member: own rows only)

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| memberId | UUID | No | One person (owner only) | a member must pass their own | all |
| action | string | No | One action (list below) | enum | all |
| page | integer | No | Page, from 1 | ≥ 1 | 1 |
| size | integer | No | Rows per page | max 50 | 20 |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Team activity", "action_time": "2026-11-17T10:30:45",
  "data": {
    "content": [
      { "activityId": "e5…", "at": "2026-11-17T10:58:00", "memberId": "b2…", "accountId": "5b0c…",
        "displayName": "Jane Kimaro", "action": "ORDER_READY", "targetType": "ORDER", "targetId": "0f05…",
        "summary": "ORD-2026-23424", "terminalId": "9b1c…" }
    ],
    "totalElements": 1, "totalPages": 1, "number": 0, "size": 20
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| at | When |
| memberId, accountId, displayName | Who |
| action | What (below) |
| targetType, targetId | What it was about (`TEAM_MEMBER`, `ORDER`, `JOB`, `PRODUCT`, `TERMINAL`, `CALL`…) |
| summary | Short text, e.g. an order or parcel number |
| terminalId | The computer it was done on; `null` from a phone |

Actions: `MEMBER_INVITED`, `INVITE_WITHDRAWN`, `INVITE_ACCEPTED`, `INVITE_DECLINED`, `MEMBER_REMOVED`, `MEMBER_LEFT`,
`MEMBER_LOCKED`, `MEMBER_UNLOCKED`, `MEMBER_ROLE_CHANGED`, `ROLE_CREATED`, `ROLE_UPDATED`, `ROLE_DELETED`,
`TERMINAL_LINKED`, `TERMINAL_CHANGED`, `TERMINAL_REMOVED`, `ADDED_TO_TERMINAL`, `REMOVED_FROM_TERMINAL`, `PIN_RESET`,
`PIN_LOCKED`, `SIGNED_IN`, `ORDER_ACCEPTED`, `ORDER_TAKEN`, `ORDER_RELEASED`, `ORDER_READY`, `PICKUP_TIME_SET`,
`ORDER_HANDED_OVER`, `ORDER_HANDED_TO_RIDER`, `ORDER_COLLECTED`, `PRODUCT_CREATED`, `PRODUCT_UPDATED`,
`PRODUCT_PUBLISHED`, `STOCK_UPDATED`, `CALL_ANSWERED`, `CALL_MADE`.

**Errors**: `OWN_ACTIVITY_ONLY` (a member asked for someone else), `NOT_ON_TEAM`.

---

## 13. A member's day
**Purpose**: Today's counts for one person ("Jane: 12 orders ready, 3 calls answered").

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/{kind}/{placeId}/members/{memberId}/day`

**Access Level**: 🔒 Protected (owner: anyone; member: themselves)

**Query Parameters**:
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| date | string | No | `YYYY-MM-DD` | today |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "A member's day", "action_time": "2026-11-17T18:00:00",
  "data": { "memberId": "b2…", "accountId": "5b0c…", "displayName": "Jane Kimaro", "day": "2026-11-17",
            "counts": [ { "action": "ORDER_READY", "count": 12 }, { "action": "CALL_ANSWERED", "count": 3 } ] }
}
```

**Errors**: `MEMBER_REQUIRED`, `OWN_ACTIVITY_ONLY`.

---

# Part 5 — Shop owner: shop computers

## 14. What is this code?
**Purpose**: The owner (or a staff member, for 33) scanned a computer's code: show what it is before acting.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal-codes/{userCode}`

**Access Level**: 🔒 Protected (any signed-in person)

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| userCode | string | Yes | e.g. `K7Q-4MX` | dash and letter case don't matter |

**Success Response JSON Sample** (a new computer):
```json
{
  "success": true, "httpStatus": "OK", "message": "Code", "action_time": "2026-11-17T10:30:45",
  "data": { "purpose": "LINK_TERMINAL", "platform": "WINDOWS", "placeKind": null, "placeId": null, "placeName": null,
            "terminalLabel": null, "expiresIn": 21 }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| purpose | `LINK_TERMINAL` → show "Link this Windows computer?" and go to 15. `ADD_MEMBER` → show "Add yourself to Counter PC at My Shop With Banner?" and go to 33 |
| platform | What the computer said it is |
| placeKind, placeId, placeName, terminalLabel | `ADD_MEMBER` only: where the computer is |
| expiresIn | Seconds left; the computer shows a new code every 30 s |

**Errors**: `404` (unknown or expired code).

---

## 15. Link the computer to the shop
**Purpose**: Approve a new computer for the shop and choose what it may do.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/terminals/link`

**Access Level**: 🔒 Protected (shop owner only, from her own phone)

**Request JSON Sample**:
```json
{ "userCode": "K7Q-4MX", "label": "Counter PC", "permissions": ["HANDLE_ORDERS", "ORDER_ALERTS", "CUSTOMER_CHAT", "RECEIVE_CALLS"] }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| userCode | string | Yes | The code on the computer | max 12 |
| label | string | Yes | Name shown everywhere | 1–40 |
| permissions | array | No | What the computer may do. Left out = all shop permissions | enum: `ORDER_ALERTS`, `RECEIVE_CALLS`, `CUSTOMER_CHAT`, `HANDLE_ORDERS`, `PRODUCTS_STOCK` |

**Success Response**: `message` "Approved. The computer finishes linking in a few seconds", `data` `null`. The computer
picks it up on its next poll.

**Errors**: `NOT_THE_OWNER`, `CODE_USED`, `TOO_MANY_TERMINALS` (20 per shop), `PERMISSION_NOT_HERE` (a business
permission), `404` (expired code).

---

## 16. List the shop's computers
**Purpose**: Every computer, who is on it, and whether it is open now.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/terminals`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Terminals", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "terminalId": "9b1c…", "label": "Counter PC", "platform": "WINDOWS", "job": "SHOP_COUNTER",
      "permissions": ["HANDLE_ORDERS", "ORDER_ALERTS", "RECEIVE_CALLS"], "linkedAt": "2026-11-16T09:00:00",
      "lastSeenAt": "2026-11-17T10:30:20", "appVersion": "0.1.0", "online": true,
      "people": [
        { "enrolmentId": "e1…", "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro", "avatarUrl": null,
          "signedIn": true, "pinLockedUntil": null } ] }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| online | The computer's app holds its live connection now |
| people[].enrolmentId | Use for reset PIN (19) |
| people[].signedIn | Signed in there now |
| people[].pinLockedUntil | Set after 5 wrong PINs (15 minutes) |

---

## 17. Change a computer
**Purpose**: Rename it or change what it may do. The computer is told at once and re-reads its settings.

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span> `{base_url}/team/shops/{shopId}/terminals/{terminalId}`

**Access Level**: 🔒 Protected (shop owner only)

**Request JSON Sample**:
```json
{ "label": "Back office", "permissions": ["CUSTOMER_CHAT", "RECEIVE_CALLS"] }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| label | string | No | New name | 1–40 |
| permissions | array | No | Replaces the whole set | shop permissions only |

Only the fields sent change. **Success Response**: `message` "Terminal updated", `data` = the computer (shape as in 16).

**Errors**: `NOT_THE_OWNER`, `PERMISSION_NOT_HERE`, `404`.

---

## 18. Remove a computer
**Purpose**: Lost or stolen computer: it stops working at once; everyone on it is signed out and removed from it.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/terminals/{terminalId}/remove`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "Terminal removed", `data` `null`.

---

## 19. Reset a person's PIN on a computer
**Purpose**: Someone forgot their PIN or was locked out. They must add themselves again (33) and choose a new PIN. The
owner never sees a PIN.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/terminals/{terminalId}/people/{enrolmentId}/reset-pin`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response**: `message` "PIN reset. They add themselves to that computer again", `data` `null`. The person gets
`TERMINAL_PIN_RESET`.

---

# Part 6 — Shop owner: orders, chat and calls with staff

The owner uses the same shop screens as before. These calls add what a team needs. They work from her phone (person
token) and from a shop computer (terminal app doc).

## 20. Packing tags
**Purpose**: "Packing · Jane" on the order list: who is working on which order.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/orders/tags`

**Access Level**: 🔒 Protected (owner, or `SEE_ORDERS`)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Who is packing what", "action_time": "2026-11-17T10:30:45",
  "data": [ { "orderId": "0f05…", "memberId": "b2…", "name": "Jane Kimaro", "takenAt": "2026-11-17T10:12:00", "mine": false } ]
}
```

---

## 21. Take an order
**Purpose**: Mark "I'm packing this". First to take it wins. The owner can take over anyone's.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/orders/{orderId}/take`

**Access Level**: 🔒 Protected (owner, or `HANDLE_ORDERS`)

**Success Response**: `message` "You are packing this order", `data` = the tag (shape as in 20).

**Errors**: `ORDER_TAKEN` (message names who has it), `ORDER_FINISHED`.

Tags clear by themselves when the order is ready, handed over or collected, and when the person leaves the team.

---

## 22. Release an order
**Purpose**: Drop your own tag (the owner: anyone's).

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/orders/{orderId}/release`

**Access Level**: 🔒 Protected (owner, or `HANDLE_ORDERS`)

**Success Response**: `message` "Back in the shared list", `data` `null`.

---

## 23. Who did each step of an order
**Purpose**: The order's steps with names: "Ready · Peter M · Counter PC · 10:58".

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/orders/{orderId}/steps`

**Access Level**: 🔒 Protected (owner, or `SEE_ORDERS`)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Who did what", "action_time": "2026-11-17T11:00:00",
  "data": [
    { "action": "ORDER_ACCEPTED", "accountId": "304e…", "name": "Joshua Sakweli", "at": "2026-11-17T10:05:00",
      "terminalId": null, "terminalLabel": null, "summary": "ORD-2026-23424" },
    { "action": "ORDER_READY", "accountId": "7a1d…", "name": "Peter M", "at": "2026-11-17T10:58:00",
      "terminalId": "9b1c…", "terminalLabel": "Counter PC", "summary": "ORD-2026-23424" }
  ]
}
```

Actions: `ORDER_ACCEPTED`, `ORDER_TAKEN`, `ORDER_RELEASED`, `ORDER_READY`, `ORDER_HANDED_OVER`, `ORDER_HANDED_TO_RIDER`,
`ORDER_COLLECTED`.

---

## 24. Who wrote each shop message
**Purpose**: Name tags under the shop's messages ("— Jane"), shop side only. Customers never receive this.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/chat/conversations/{conversationId}/senders`

**Access Level**: 🔒 Protected (owner, or `CUSTOMER_CHAT`)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Who sent the shop's messages", "action_time": "2026-11-17T10:30:45",
  "data": [ { "messageId": "m-81…", "accountId": "5b0c…", "name": "Jane Kimaro" } ]
}
```

Covers the shop's last 200 messages in that conversation.

---

## 25. "Jane is replying…"
**Purpose**: Tell the rest of the shop someone is typing to this customer.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/shops/{shopId}/chat/conversations/{conversationId}/typing`

**Access Level**: 🔒 Protected (owner, or `CUSTOMER_CHAT`)

Send while typing, at most every 3 seconds. The shop side gets `shop.typing`
`{ conversationId, shopId, accountId, name, untilMs }` on its live stream (`/events` in the app). Hide it after `untilMs`.

---

## 26. Shop calls setting
**Purpose**: Whether the owner's phone rings for calls to the shop once the shop has computers.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/calls`

**Access Level**: 🔒 Protected (shop owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Shop calls", "action_time": "2026-11-17T10:30:45",
  "data": { "hasTerminals": true, "ringMode": "WHEN_NOBODY_AT_SHOP", "somebodyAtShop": true, "phoneRingsNow": false, "nobodyRings": false }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| hasTerminals | Show the setting only when `true` (no computers: the phone rings as before) |
| ringMode | `ALWAYS`, `WHEN_NOBODY_AT_SHOP` (default), `NEVER` |
| somebodyAtShop | Someone with Answer calls is signed in on an open computer ticked Receive calls, and not already on a call |
| phoneRingsNow | Whether a call right now would ring the owner |
| nobodyRings | `NEVER` and nobody free at the shop: warn "Calls won't ring anywhere" |

---

## 27. Change the shop calls setting
**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/team/shops/{shopId}/calls/ring-mode`

**Access Level**: 🔒 Protected (shop owner only)

**Request JSON Sample**:
```json
{ "mode": "WHEN_NOBODY_AT_SHOP" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| mode | string | Yes | Ring mode | enum: `ALWAYS`, `WHEN_NOBODY_AT_SHOP`, `NEVER` |

**Success Response**: `message` "Saved", `data` as in 26.

---

## 28. Missed calls to the shop
**Purpose**: Customers' chat calls nobody answered, last 7 days, with whether the shop may still call back.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/shops/{shopId}/calls/missed`

**Access Level**: 🔒 Protected (owner, or `ANSWER_CALLS`)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Missed calls", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "callId": "k-55…", "conversationId": "c-12…", "customerName": "Amina", "customerAvatar": "https://…",
      "at": "2026-11-17T09:14:03+03:00", "callBackUntil": "2026-11-18T09:14:03+03:00", "canCallBack": true, "handled": false }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| callBackUntil, canCallBack | The 24-hour reply window: call back with `POST /calls` and `shopId` while it's open |
| handled | Someone called back, or a later call from this customer was answered |

Calls about a parcel are not here; they are in 38 with `shopId`.

---

# Part 7 — Any person: my teams

## 29. My teams and invites waiting
**Purpose**: The places I work at and the invites waiting for me (also those sent to my phone number before I signed up).

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/me`

**Access Level**: 🔒 Protected (any signed-in person)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "My teams", "action_time": "2026-11-17T10:30:45",
  "data": {
    "memberships": [
      { "memberId": "b2…", "placeKind": "SHOP", "placeId": "cfb6…", "placeName": "My Shop With Banner", "role": "STAFF",
        "shopRoleName": "Order staff", "status": "ACTIVE", "onDuty": false }
    ],
    "invites": [
      { "memberId": "d4…", "placeKind": "BUSINESS", "placeId": "2a19…", "placeName": "EMS Courier", "role": "RIDER",
        "shopRoleName": null, "invitedByName": "Joshua Sakweli", "expiresAt": "2026-11-17T16:30:45" }
    ]
  }
}
```

Places the person owns are not listed. A rider invite is answered here too, but the rider then works in the shipper app.

---

## 30. Accept an invite
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/invites/{memberId}/accept`

**Access Level**: 🔒 Protected (the invited person)

**Success Response**: `message` "You joined the team", `data` = the membership (as in 29). The owner gets
`TEAM_INVITE_ANSWERED`. Accepting twice is harmless.

**Errors**: `INVITE_NOT_OPEN`, `INVITE_EXPIRED`, `ALREADY_ON_TEAM`, `404` (an invite meant for someone else).

---

## 31. Decline an invite
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/invites/{memberId}/decline`

**Access Level**: 🔒 Protected (the invited person)

**Success Response**: `message` "Invite declined", `data` `null`. The owner gets `TEAM_INVITE_ANSWERED`.

---

## 32. Leave a team
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/memberships/{memberId}/leave`

**Access Level**: 🔒 Protected (the member)

**Success Response**: `message` "You left the team", `data` `null`. The owner gets `TEAM_MEMBER_LEFT`; the person is signed
out of that place's computers.

**Errors**: `OWNER_CANNOT_LEAVE`, `PARCEL_IN_HAND` (a rider holding a parcel), `NOT_ON_TEAM`.

---

## 33. Add me to this computer
**Purpose**: A staff member scanned the "Add me" code on a shop computer (after 14 showed `purpose` = `ADD_MEMBER`).

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal-codes/{userCode}/add-me`

**Access Level**: 🔒 Protected (an active member of that shop: owner or staff)

**Success Response**: `message` "Now choose your PIN on the computer", `data` = the person as the computer will show them
(`enrolmentId`, `memberId`, `userName`, `displayName`, `avatarUrl`, `signedIn`, `pinLockedUntil`). The computer greets
them and asks for their PIN.

**Errors**: `ROLE_NOT_FOR_TERMINAL`, `NOT_ACTIVE_HERE` (not an active member of that place), `CODE_USED`, `404`.

---

# Part 8 — Calls about a parcel (buyer and shop)

Voice only. Open from the moment a shipper accepts the delivery until the order is completed or cancelled. The call is a
normal LiveKit room; the token in the answer joins it.

## 34. Call the delivery
**Purpose**: The buyer (or the shop) calls the shipper. It rings the person the shipper assigned to the job **now**, else
the shipper itself. Moved to Juma → the next call rings Juma.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls`

**Access Level**: 🔒 Protected (the order's buyer; or the shop with `shopId`: owner or `ANSWER_CALLS`)

**Request JSON Sample** (buyer):
```json
{ "orderId": "0f059667-6e07-4230-bc6b-a94185cfce0c", "to": "DELIVERY" }
```

**Request JSON Sample** (shop owner, as the shop):
```json
{ "orderId": "0f059667-6e07-4230-bc6b-a94185cfce0c", "to": "DELIVERY", "shopId": "cfb66092-69cb-4d32-9a7b-e3fb876f3ab4" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| orderId | UUID | Yes | The order | must be open for calls |
| to | string | Yes | `DELIVERY` from this app | `BUYER` / `SHOP` are for shippers (`USE_SHOP_CALLS` otherwise) |
| shopId | UUID | No | Call as the shop | the order's shop; owner or `ANSWER_CALLS` |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Calling", "action_time": "2026-11-17T10:30:45",
  "data": {
    "call": { "callId": "6fb0…", "roomName": "call_6fb0…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" },
    "calling": { "role": "SHIPPER", "name": "EMS Courier", "businessLogoMedia": { "fileId": "a91f…", "status": "COMPLETED", "thumbUrl": "https://…/logo-thumb.png", "mimeType": "image/png" },
                 "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…" },
    "allLinesBusy": false
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| call.token, call.url | Join the room now (microphone only) and wait for them |
| calling | Who is being rung: always the **shipper** (`role` `SHIPPER`, `name` = the business, `businessLogoMedia`) |
| calling.assignedTo | The person the shipper assigned to this job (`accountId`, `name`, `userProfileMedia`); absent when nobody is assigned and the business itself answers. Show "Calling EMS Courier · Mama Yoyo" |
| allLinesBusy | Everyone at the business's office is on another call; the call still waits. Show "Everyone is on another call. Please wait, or call back later." |

**Errors**: `NO_SHIPPER_YET`, `CALLS_CLOSED` ("This delivery is finished"), `BUSY` (the person assigned is on another call),
`SAME_PERSON`, `OWN_BUSINESS` / `OWN_SHOP` (nobody else would answer, e.g. buying from your own business with no office),
`NOT_ON_THIS_ORDER`, `NOT_YOUR_SHOP`, `USE_SHOP_CALLS`.

The buyer's **Call shop** button stays the existing `POST /calls` with `targetShopId`.

---

## 35. Answer a call about a parcel
**Purpose**: Join a ringing work call: as yourself (buyer) or as the shop (`shopId`).

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/join`

**Access Level**: 🔒 Protected (a person on the call; the shop: owner or `ANSWER_CALLS`)

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| shopId | UUID | No | Answer as the shop (the ring said `answerAs: SHOP`) |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Joined", "action_time": "2026-11-17T10:30:50",
  "data": { "callId": "6fb0…", "roomName": "call_6fb0…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" }
}
```

A buyer's ring already carries the token: the app may join the room straight away; this call is the fallback.

**Errors**: `ANSWERED_ELSEWHERE` ("Answered by Jane": someone else at the shop took it), `CALL_ENDED`, `NOT_ON_THIS_CALL`.

---

## 36. Hang up, decline or cancel
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/end`

**Access Level**: 🔒 Protected (a person on the call; `shopId` as in 35)

**Success Response**: the call row (as in 38). The server decides whether it was completed, declined or cancelled.

---

## 37. One call
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/{callId}`

**Access Level**: 🔒 Protected (a person on the call; `shopId` as in 35)

**Success Response**: one row, as in 38.

---

## 38. Calls about my orders (call history)
**Purpose**: The buyer's calls about parcels, or the shop's (`shopId`), newest first, with Call back.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls`

**Access Level**: 🔒 Protected

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| shopId | UUID | No | The shop's calls (owner or `ANSWER_CALLS`) | | my calls as a buyer |
| limit | integer | No | How many | max 50 | 30 |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Calls", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "callId": "6fb0…", "outgoing": false, "state": "ENDED", "outcome": "MISSED", "missed": true,
      "at": "2026-11-17T10:12:00+03:00", "durationSeconds": null,
      "other": { "role": "SHIPPER", "name": "EMS Courier", "businessLogoMedia": { "fileId": "a91f…", "status": "COMPLETED", "thumbUrl": "https://…/logo-thumb.png", "mimeType": "image/png" },
                 "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…" },
      "callBack": "DELIVERY" }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| outgoing | I made it |
| outcome | `COMPLETED`, `MISSED`, `DECLINED`, `CANCELLED`, `BUSY` |
| missed | Incoming and nobody here answered, or it found me busy: show red |
| other | The other side (shape as `calling` in 34) |
| callBack | Send this as `to` in 34 to call back; **absent** once the order's calls are closed |

**Work calls are not in `GET /calls`** (chat calls). Show the two lists side by side, or merge them by `at`.

---

## 39. Calls waiting at the shop
**Purpose**: The shop's queue: calls still ringing, oldest first, so the owner can pick one.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/waiting?shopId={shopId}`

**Access Level**: 🔒 Protected (owner, or `ANSWER_CALLS`)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Waiting calls", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "callId": "k-90…", "work": false, "conversationId": "c-12…", "since": "2026-11-17T10:30:10+03:00", "waitedSeconds": 35,
      "caller": { "role": "BUYER", "name": "Amina", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } } },
    { "callId": "6fb1…", "work": true, "since": "2026-11-17T10:30:30+03:00", "waitedSeconds": 15,
      "caller": { "role": "SHIPPER", "name": "EMS Courier", "businessLogoMedia": { "fileId": "a91f…", "status": "COMPLETED", "thumbUrl": "https://…/logo-thumb.png", "mimeType": "image/png" },
                 "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…" } }
  ]
}
```

`work: false` = a customer's chat call: answer with `POST /calls/{callId}/join?shopId=`. `work: true`: answer with 35.

---

# Part 9 — Additions to existing responses and pushes

Nothing was removed or renamed.

| Where | Added | Meaning |
|---|---|---|
| Order details: `fulfillment.shippers[]` | `assignedTo` `{ accountId, name, userProfileMedia }` | The person the shipper assigned to that leg. Absent while nobody is on it. **Never a phone**: call through 34 |
| `GET /calls` | (behaviour) | Work calls are left out; they are in 38 |
| Ring push / `call.incoming` | `answerAs`, `shopId`, `shopName`, `work`, `callerRole`, `assignedToAccountId`, `assignedToName`, `assignedToAvatar`, `parcelNumber`, `orderNumber`, `orderId` | See `push_contracts_api_doc.md` §4.2. `answerAs: SHOP` → no token, answer with `?shopId=`; first to answer wins |
| `call.updated`, `CALL_ENDED` | `answeredBy`, `work` | `ANSWERED_ELSEWHERE` + `answeredBy`: stop ringing; ignore it if you are the one in the call |
| Shop live stream (`/events`) | `shop.typing` | 25 |
| `DELETE /account/devices/{id}` | (behaviour) | Removing a device also ends its sessions |

```json
"shippers": [
  { "leg": 1, "businessId": "2a19…", "name": "EMS Courier", "phone": "+255…",
    "assignedTo": { "accountId": "3213…", "name": "Mama Yoyo", "userProfileMedia": { "fileId": "8c2e…", "status": "COMPLETED", "thumbUrl": "https://…/thumb.jpg", "mimeType": "image/jpeg" } } }
]
```

---

# Part 10 — Notifications

| Type | To | Channels | Opens |
|---|---|---|---|
| `TEAM_INVITE` | the invited person | bell + push | My teams (29) |
| `TEAM_INVITE_ANSWERED` | the owner | bell | the team (2) |
| `TEAM_REMOVED` | the removed person | bell + push | My teams |
| `TEAM_MEMBER_LEFT` | the owner | bell + push | the team |
| `TERMINAL_PIN_ALERT` | the owner | bell + push | the computer (16): 5 wrong PINs (locked 15 min) or 10 (removed) |
| `TERMINAL_PIN_RESET` | the member | bell + push | "Add yourself to the computer again" |
| `CHAT_INCOMING_CALL` | buyer / shop owner | push (rings) | the call screen; work calls carry `work: "true"` |
| `CHAT_CALL_ENDED` | same | push (silent) | stop ringing |
| `ORDER_MISSED_CALL` | buyer / shop owner | bell + push | the order: "Missed call about order ORD-…" (`caller.name`, `call.time`, `orderNumber`, `parcelNumber`) |

# Shipper App — Team APIs

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated**: 2026-11-17  
**Version**: v1.0

**Base URL**: `https://api.nexgate.co/api/v1`

**Short Description**: Everything the shipper app needs for teams: a **business owner** builds the team, gives jobs to
riders, links office computers, sets how calls ring and reads reports; a **rider** sees only the jobs given to them,
goes on and off duty, and calls the buyer or the shop about a parcel. Read [`README.md`](README.md) first for roles,
rights and terminals. The shipper app's offer and job calls are in `docs/shipping/shipper_app_api_doc.md`.

**Hints**:
- Every call uses the person's normal login: `Authorization: Bearer <access token>`.
- Team paths use `{kind}` = `businesses` and `{placeId}` = the delivery business id.
- **A rider never sees money.** Everything a rider receives has `cost`, `commission`, `payout`, `payoutStatus` = `null`.
- **A rider's phone is the rider's own**, not the business's: it is linked to the shipper app without a business
  (`app = SHIPPERS`, no `businessId`). Rider rings reach it; the business's offer rings never do.
- **Shippers never get an order number or order id.** Calls and jobs carry `jobId` and `parcelNumber`.
- When the team feature is off, team endpoints answer **404**: hide Team, Riders, Office, Reports.

---

## Contents

- Part 1 — How it works (flows)
- Part 2 — Owner: the team (1–7)
- Part 3 — Owner: riders and jobs (8–10)
- Part 4 — Owner: office computers (11–16)
- Part 5 — Owner: ring settings (17–20)
- Part 6 — Activity and reports (21–23)
- Part 7 — Rider: my teams, duty, my jobs (24–31)
- Part 8 — Calls about a parcel (32–37)
- Part 9 — Additions to existing responses
- Part 10 — Pushes and notifications

---

# Part 1 — How it works

## 1.1 A job reaches a rider

```
 OFFER rings (owner's phone / office PC)
        │ accept (first tap wins)
        ▼
 job ACCEPTED by EMS Courier ───────────────────────────────────────────────────────────┐
        │                                                                                │
        │ owner or dispatcher: GET …/riders → picks Mama Yoyo                            │ nobody assigned:
        ▼                                                                                │ the owner's phones
 POST /shipping/jobs/{jobId}/assign { memberId, ring }                                   │ carry it as before
        │
        ├── Mama Yoyo on duty ─────────► rings her shipper app (JOB_ASSIGNED, button View)
        ├── off duty, ring left out ───► 409 RIDER_OFF_DUTY → owner chooses "Send quietly" / "Ring anyway"
        │                                   ring=QUIET → JOB_ASSIGNED_QUIET (normal notice)   ring=RING → rings
        ▼
 Mama Yoyo: GET /shipping/jobs/assigned → the job → usual steps (heading, check-parcel, deliver …)
        │                                each step lands in EMS Courier's activity under her name
        ▼
 given to Juma instead ──► Mama Yoyo gets JOB_UNASSIGNED (silent: stop ring, drop the job), Juma gets JOB_ASSIGNED
```

## 1.2 Who rings for an offer (owner's "Ring on my phone")

```
 Offer for EMS Courier
        │
        ▼
 Office computer linked? ──no──► owner's phones ring (as before)
        │ yes
        ▼
 office PCs ticked "Get offers" ring  +  owner's phones per ringMode:
     ALWAYS                  → ring
     WHEN_NOBODY_AT_OFFICE   → ring only if no owner/dispatcher is signed in at an open office PC   (default)
     NEVER                   → never (warning: offers may ring nowhere and the business may get paused)
```

## 1.3 Calls about a parcel

```
 Open from "shipper accepted" until the order is completed or cancelled.

 Amina (buyer) ── Call delivery ──► Mama Yoyo's shipper app (she holds the job)
                                     │ no answer in 20 s and the owner turned on "Ring the business when a rider
                                     │ doesn't answer" (19) ──► office PCs + owner's phones ring too, until 45 s
                                     │ first to answer wins
                                     ▼
                                    no rider on the job ──► the business rings (office PCs + owner's phones)

 Mama Yoyo ── Call buyer ──► Amina's NexGate app       (shows "Mama Yoyo · rider for EMS Courier · parcel NX-SQAW-ZL")
 Mama Yoyo ── Call shop  ──► the shop's computers + the shop owner
 Owner     ── Call buyer / Call shop on his job page ──► same, shown as "EMS Courier"
```

- One call at a time per person: a rider already on a call → the caller hears `BUSY`, the rider gets a missed-call
  notice.
- Nobody's own phone rings for their own call. If nobody else could answer, the call is refused (`SAME_PERSON`,
  `OWN_BUSINESS`, `OWN_SHOP`).

---

# Part 2 — Owner: the team

## 1. Invite someone
**Purpose**: Invite a NexGate user (by `accountId`) or a phone number as a rider or a dispatcher.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/invites`

**Access Level**: 🔒 Protected (business owner only)

**Authentication**: Bearer token

**Request JSON Sample**:
```json
{ "accountId": "3213c20e-074b-4f4e-8adb-e1167aac5425", "role": "RIDER" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| accountId | UUID | One of accountId / phone | The person, from the user search (type-ahead, photo + name) | not the owner |
| phone | string | One of accountId / phone | Any format: `0754…`, `255754…`, `+255754…` | max 20 |
| role | string | Yes | `RIDER` or `DISPATCHER` | `OWNER` / a shop role → `ROLE_NOT_FOR_BUSINESSES` |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Invite sent", "action_time": "2026-11-17T10:30:45",
  "data": {
    "memberId": "d4a1…", "accountId": "3213…", "userName": "mama_yoyo", "displayName": "Mama Yoyo", "avatarUrl": "https://…",
    "role": "RIDER", "shopRoleId": null, "shopRoleName": null, "status": "INVITED", "inviteChannel": "ACCOUNT",
    "invitedPhone": null, "invitedAt": "2026-11-17T10:30:45", "inviteExpiresAt": "2026-11-17T16:30:45",
    "acceptedAt": null, "onDuty": false
  }
}
```

**Errors**: `NOT_THE_OWNER`, `INVITE_WHO`, `ROLE_NOT_FOR_BUSINESSES`, `CANNOT_INVITE_YOURSELF`, `ALREADY_INVITED`,
`TOO_MANY_INVITES`, `TOO_MANY_PHONE_INVITES`, `PHONE_INVALID`.

---

## 2. The team
**Purpose**: The owner first, then everyone invited, active or locked, oldest first.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/businesses/{businessId}/members`

**Access Level**: 🔒 Protected (business owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Team", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "memberId": "a1…", "accountId": "304e…", "userName": "joshua", "displayName": "Joshua Sakweli", "avatarUrl": null,
      "role": "OWNER", "status": "ACTIVE", "onDuty": false },
    { "memberId": "d4a1…", "accountId": "3213…", "userName": "mama_yoyo", "displayName": "Mama Yoyo", "avatarUrl": "https://…",
      "role": "RIDER", "status": "ACTIVE", "acceptedAt": "2026-11-16T11:00:00", "onDuty": true }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| role | `OWNER`, `DISPATCHER`, `RIDER` |
| status | `INVITED`, `ACTIVE`, `LOCKED` |
| onDuty | Riders: on duty now (informs the owner, never blocks a job) |
| inviteChannel, invitedPhone, invitedAt, inviteExpiresAt | Invites (a phone invite shows only the typed number) |

---

## 3. Withdraw an invite
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/withdraw`

**Access Level**: 🔒 Protected (business owner only)

**Success Response**: `message` "Invite withdrawn", `data` = the member. **Errors**: `INVITE_NOT_OPEN`.

---

## 4. Change someone's role
**Purpose**: Rider ↔ dispatcher.

**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/role`

**Access Level**: 🔒 Protected (business owner only)

**Request JSON Sample**:
```json
{ "role": "DISPATCHER" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| role | string | Yes | New role | enum: `RIDER`, `DISPATCHER` |

**Success Response**: `message` "Role changed", `data` = the member. **Errors**: `OWNER_ROLE_FIXED`, `ROLE_NOT_FOR_BUSINESSES`, `NOT_ON_TEAM`.

---

## 5. Lock someone
**Purpose**: Pause a member. A dispatcher is signed out of every office computer at once.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/lock`

**Access Level**: 🔒 Protected (business owner only)

**Success Response**: `message` "Member locked", `data` = the member. **Errors**: `MEMBER_STATE`, `OWNER_CANNOT_BE_REMOVED`.

---

## 6. Unlock someone
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/unlock`

**Access Level**: 🔒 Protected (business owner only)

**Success Response**: `message` "Member unlocked", `data` = the member. **Errors**: `MEMBER_STATE`.

---

## 7. Remove someone
**Purpose**: End a membership at once. History stays.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/remove`

**Access Level**: 🔒 Protected (business owner only)

**Query Parameters**:
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| confirmHolding | boolean | No | Remove a rider who is holding a parcel anyway | false |

```
 Remove Mama Yoyo
     │
     ├── she holds no parcel ─────────► removed (TEAM_REMOVED to her)
     └── she holds parcel NX-SQAW-ZL ─► 409 RIDER_HOLDS_PARCEL
                                          owner confirms → …/remove?confirmHolding=true
                                          → removed; the job shows assignee.removedWhileHolding = true
                                            ("Parcel with Mama Yoyo") until someone else takes it over
```

**Success Response**: `message` "Member removed", `data` = the member.

**Errors**: `OWNER_CANNOT_BE_REMOVED`, `RIDER_HOLDS_PARCEL`, `NOT_ON_TEAM`.

---

# Part 3 — Owner: riders and jobs

## 8. Who can carry it
**Purpose**: The list to pick a rider from, already sorted: on duty first, then phones that can ring, then fewest jobs
carried.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/businesses/{businessId}/riders`

**Access Level**: 🔒 Protected (owner; dispatchers on the office PC)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Riders", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "memberId": "d4a1…", "accountId": "3213…", "name": "Mama Yoyo", "avatarUrl": "https://…", "onDuty": true,
      "dutyChangedAt": "2026-11-17T08:01:00", "carrying": 1, "phoneCanRing": true }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| memberId | Send this to 9 |
| onDuty, dutyChangedAt | Duty status and since when |
| carrying | Jobs given to them and not finished |
| phoneCanRing | They have a shipper-app phone that can ring; `false` → warn "Her phone won't ring" |

---

## 9. Give a job to a rider
**Purpose**: Assign an accepted job. Giving it to someone else takes it from the first rider at once.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/shipping/jobs/{jobId}/assign`

**Access Level**: 🔒 Protected (owner; dispatchers on the office PC)

**Request JSON Sample**:
```json
{ "memberId": "d4a1…", "ring": "RING" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| memberId | UUID | Yes | From 8 | an active rider of this business |
| ring | string | No | `RING` or `QUIET`. Leave out for an on-duty rider (it rings) | required for an off-duty rider |

**Success Response**: `message` "Job assigned", `data` = the job (`GET /shipping/jobs/{id}` shape) with `assignee` set.
Giving it to the same rider again changes nothing.

**Errors**: `RIDER_OFF_DUTY` (`details.offDutySince`: ask "Send quietly / Ring anyway", then send `ring`),
`RIDER_NOT_AVAILABLE` (not an active rider), `JOB_NOT_ASSIGNABLE` (not accepted yet, or finished), `ASSIGN_RACE`
(someone else assigned it a moment ago: reload).

---

## 10. Take a job back
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/shipping/jobs/{jobId}/unassign`

**Access Level**: 🔒 Protected (owner; dispatchers on the office PC)

**Success Response**: `message` "Job taken back", `data` = the job with `assignee` `null`. The rider gets
`JOB_UNASSIGNED` (silent).

---

# Part 4 — Owner: office computers

Same flow as shop computers (README). Business permissions: `GET_OFFERS`, `ASSIGN_RIDERS`, `RECEIVE_CALLS`.

```
 OFFICE PC (terminal app)              SERVER                              OWNER (shipper app)
 POST /team/terminal-link/start ─────► code K7Q-4MX (30 s)
 shows code + QR                                                           scans / types it
                                       ◄────────────────────────────────── GET  /team/terminal-codes/K7Q-4MX      (11)
                                       ◄────────────────────────────────── POST /team/businesses/{id}/terminals/link (12)
 POST /team/terminal-link/poll ──────► approved + terminal key
 Peter (dispatcher) adds himself with his own NexGate app (scans "Add me"), then signs in with his PIN on the PC.
```

## 11. What is this code?
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal-codes/{userCode}`

**Access Level**: 🔒 Protected (any signed-in person)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Code", "action_time": "2026-11-17T10:30:45",
  "data": { "purpose": "LINK_TERMINAL", "platform": "WINDOWS", "placeKind": null, "placeId": null, "placeName": null,
            "terminalLabel": null, "expiresIn": 21 }
}
```

`purpose` `LINK_TERMINAL` → "Link this Windows computer to EMS Courier?" → 12.

---

## 12. Link the computer to the business
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/terminals/link`

**Access Level**: 🔒 Protected (business owner only, own phone)

**Request JSON Sample**:
```json
{ "userCode": "K7Q-4MX", "label": "Office PC", "permissions": ["GET_OFFERS", "ASSIGN_RIDERS", "RECEIVE_CALLS"] }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| userCode | string | Yes | The code on the computer | max 12 |
| label | string | Yes | Name shown everywhere | 1–40 |
| permissions | array | No | Left out = all three | enum: `GET_OFFERS`, `ASSIGN_RIDERS`, `RECEIVE_CALLS` |

**Success Response**: `message` "Approved. The computer finishes linking in a few seconds", `data` `null`.

**Errors**: `NOT_THE_OWNER`, `CODE_USED`, `TOO_MANY_TERMINALS` (20), `PERMISSION_NOT_HERE` (a shop permission).

> Office computers linked **before 2026-11-17** don't have `RECEIVE_CALLS`: they don't ring for calls until the owner
> ticks it (14).

---

## 13. List office computers
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/businesses/{businessId}/terminals`

**Access Level**: 🔒 Protected (business owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Terminals", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "terminalId": "71e0…", "label": "Office PC", "platform": "WINDOWS", "job": "DISPATCH",
      "permissions": ["GET_OFFERS", "ASSIGN_RIDERS", "RECEIVE_CALLS"], "linkedAt": "2026-11-16T09:00:00",
      "lastSeenAt": "2026-11-17T10:30:20", "appVersion": "0.1.0", "online": true,
      "people": [ { "enrolmentId": "e7…", "memberId": "p1…", "userName": "peter_m", "displayName": "Peter M",
                    "avatarUrl": null, "signedIn": true, "pinLockedUntil": null } ] }
  ]
}
```

---

## 14. Change an office computer
**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span> `{base_url}/team/businesses/{businessId}/terminals/{terminalId}`

**Access Level**: 🔒 Protected (business owner only)

**Request JSON Sample**:
```json
{ "permissions": ["GET_OFFERS", "ASSIGN_RIDERS", "RECEIVE_CALLS"] }
```

Only the fields sent change (`label` 1–40, `permissions` replaces the set). **Success Response**: `message` "Terminal
updated", `data` = the computer.

---

## 15. Remove an office computer
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/terminals/{terminalId}/remove`

**Access Level**: 🔒 Protected (business owner only)

**Success Response**: `message` "Terminal removed", `data` `null`. It stops at once; everyone on it is signed out.

---

## 16. Reset a person's PIN on an office computer
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/businesses/{businessId}/terminals/{terminalId}/people/{enrolmentId}/reset-pin`

**Access Level**: 🔒 Protected (business owner only)

**Success Response**: `message` "PIN reset. They add themselves to that computer again". They get `TERMINAL_PIN_RESET`.

---

# Part 5 — Owner: ring settings

## 17. Ring on my phone (status)
**Purpose**: Whether offers ring the owner's phone once the business has an office computer.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/businesses/{businessId}/office`

**Access Level**: 🔒 Protected (business owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Office", "action_time": "2026-11-17T10:30:45",
  "data": { "hasOffice": true, "ringMode": "WHEN_NOBODY_AT_OFFICE", "somebodyAtOffice": true, "phoneRingsNow": false, "nobodyRings": false }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| hasOffice | Show the setting **only** when `true` (no office: the phone rings as before) |
| ringMode | `ALWAYS`, `WHEN_NOBODY_AT_OFFICE` (default), `NEVER` |
| somebodyAtOffice | The owner or a dispatcher is signed in on an office PC that is open now and ticked Get offers |
| phoneRingsNow | Whether an offer now would ring this phone |
| nobodyRings | `NEVER` and nobody at the office: warn "Offers won't ring anywhere and your business may get paused" |

---

## 18. Change Ring on my phone
**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/shipping/businesses/{businessId}/office/ring-mode`

**Access Level**: 🔒 Protected (business owner only, own phone)

**Request JSON Sample**:
```json
{ "mode": "WHEN_NOBODY_AT_OFFICE" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| mode | string | Yes | Ring mode | enum: `ALWAYS`, `WHEN_NOBODY_AT_OFFICE`, `NEVER` |

The same mode decides whether a **call to the business** rings the owner's phone (with "somebody" meaning someone free
at an office PC ticked Receive calls).

**Success Response**: `message` "Saved", `data` as in 17.

---

## 19. Calls setting (status)
**Purpose**: "Ring the business when a rider doesn't answer".

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/businesses/{businessId}/office/work-calls`

**Access Level**: 🔒 Protected (business owner only)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Work calls", "action_time": "2026-11-17T10:30:45",
  "data": { "ringBusinessWhenRiderMisses": false }
}
```

---

## 20. Change the calls setting
**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/shipping/businesses/{businessId}/office/work-calls`

**Access Level**: 🔒 Protected (business owner only)

**Request JSON Sample**:
```json
{ "ringBusinessWhenRiderMisses": true }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| ringBusinessWhenRiderMisses | boolean | Yes | On: a rider rings alone for 20 s, then the office PCs and the owner's phones ring too, until 45 s. Off (default): only the rider |

**Success Response**: `message` "Saved", `data` as in 19.

---

# Part 6 — Activity and reports

## 21. Who did what
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/businesses/{businessId}/activity`

**Access Level**: 🔒 Protected (owner: everyone; a member: own rows only)

**Query Parameters**: `memberId`, `action`, `page` (from 1), `size` (max 50) — as in the NexGate app doc §12.

Business actions: team actions, plus `DUTY_ON`, `DUTY_OFF`, `JOB_ASSIGNED`, `JOB_UNASSIGNED`, `JOB_HEADING_TO_SHOP`,
`PARCEL_PICKED_UP`, `PARCEL_HANDED_OVER`, `PARCEL_AT_STATION`, `PARCEL_DELIVERED`, `PARCEL_REFUSED`, `OFFER_ACCEPTED`,
`OFFER_REJECTED`, `TERMINAL_*`, `SIGNED_IN`, `PIN_*`, `CALL_MADE`, `CALL_ANSWERED`.

**A member's day**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/businesses/{businessId}/members/{memberId}/day?date=2026-11-17` —
`{ memberId, accountId, displayName, day, counts: [ { action, count } ] }`.

---

## 22. Deliveries report (owner)
**Purpose**: Deliveries per rider over a period. **No money**: earnings stay on the Earnings pages.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/businesses/{businessId}/report`

**Access Level**: 🔒 Protected (business owner only)

**Query Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| from | string | Yes | `YYYY-MM-DD` | |
| to | string | Yes | `YYYY-MM-DD`, inclusive | at most 366 days after `from` |
| memberId | UUID | No | One rider ("Who" filter) | |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Deliveries", "action_time": "2026-11-17T18:00:00",
  "data": {
    "from": "2026-11-01", "to": "2026-11-17", "delivered": 42, "onTime": 39, "withPromise": 40, "takenBack": 2, "carrying": 3,
    "parts": [ { "id": "d4a1…", "name": "Mama Yoyo", "delivered": 30, "onTime": 28, "withPromise": 29 } ],
    "items": [ { "jobId": "0003…", "parcelNumber": "NX-SQAW-ZL", "businessId": "2a19…", "businessName": "EMS Courier",
                 "riderName": "Mama Yoyo", "deliveredAt": "2026-11-17T12:40:00", "onTime": true } ]
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| delivered | Jobs delivered in the period |
| onTime / withPromise | Delivered inside the promised window / jobs that had a promised window |
| takenBack | Jobs taken back from a rider or moved to another |
| carrying | Jobs being carried now |
| parts | One row per rider (`id` = memberId) |
| items | The deliveries, newest first, at most 100 |

---

## 23. My deliveries report (rider)
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/riders/me/report?from=2026-11-01&to=2026-11-17&businessId=`

**Access Level**: 🔒 Protected (the rider)

Same shape as 22; `parts` = one row per business that gave me jobs (`id` = businessId). `businessId` filters to one.

---

# Part 7 — Rider: my teams, duty, my jobs

## 24. My teams and invites
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/me`

**Access Level**: 🔒 Protected (any signed-in person)

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "My teams", "action_time": "2026-11-17T10:30:45",
  "data": {
    "memberships": [ { "memberId": "d4a1…", "placeKind": "BUSINESS", "placeId": "2a19…", "placeName": "EMS Courier",
                       "role": "RIDER", "shopRoleName": null, "status": "ACTIVE", "onDuty": true } ],
    "invites": [ { "memberId": "f9…", "placeKind": "BUSINESS", "placeId": "c4bc…", "placeName": "Kibuti Logistics",
                   "role": "RIDER", "shopRoleName": null, "invitedByName": "Asha M", "expiresAt": "2026-11-17T16:30:45" } ]
  }
}
```

Show "I work for" from `memberships` (with the duty switch) and the Invitations badge from `invites`.

---

## 25. Accept an invite
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/invites/{memberId}/accept`

**Success Response**: `message` "You joined the team", `data` = the membership. **Errors**: `INVITE_NOT_OPEN`,
`INVITE_EXPIRED`, `ALREADY_ON_TEAM`.

## 26. Decline an invite
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/invites/{memberId}/decline` — `message` "Invite declined", `data` `null`.

## 27. Leave
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/memberships/{memberId}/leave` — `message` "You left the team".

**Errors**: `PARCEL_IN_HAND` (hand the parcel over first), `OWNER_CANNOT_LEAVE`.

---

## 28. On / off duty
**Purpose**: Tell the owner whether I'm working. It never blocks a job; an off-duty rider can still be given one quietly.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/memberships/{memberId}/duty?onDuty=true`

**Access Level**: 🔒 Protected (the rider)

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| onDuty | boolean | Yes | `true` on duty, `false` off |

**Success Response**: `message` "You are on duty" / "You are off duty", `data` = the membership with the new `onDuty`.

**Errors**: `RIDERS_ONLY` (only riders go on and off duty).

---

## 29. Jobs given to me
**Purpose**: The rider's Work tab: jobs from every business that gave me one.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/jobs/assigned`

**Access Level**: 🔒 Protected (the rider)

**Query Parameters**:
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| status | string | No | `ACTIVE` (not finished) or `DONE` | ACTIVE |
| page | integer | No | From 1 | 1 |
| size | integer | No | Max 50 | 20 |

**Success Response**: `message` "Jobs assigned to me", `data` = a page of jobs in the usual job shape, **money fields
`null`**. `GET /shipping/jobs/{id}` also works for a job given to me. The usual job steps (`heading`, `check-parcel`,
`deliver`, `hand-over-next`, `arrived`, `refuse-parcel`, codes) work for the rider holding the job.

---

## 30. My numbers
**Purpose**: The rider's Home: delivered today, this week, carrying now.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shipping/riders/me/stats`

**Success Response JSON Sample**:
```json
{ "success": true, "httpStatus": "OK", "message": "My deliveries", "action_time": "2026-11-17T18:00:00",
  "data": { "deliveredToday": 4, "deliveredThisWeek": 19, "carrying": 1 } }
```

---

## 31. Test ring my phone
**Purpose**: "Is this phone ready" for a rider: ring this phone once.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/shipping/phones/{deviceId}/test-ring`

**Access Level**: 🔒 Protected (the phone's own person)

**Path Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| deviceId | string | Yes | This phone's device id (as registered) |

**Success Response**: `message` "Test ring sent", `data` `null`.

---

# Part 8 — Calls about a parcel

Voice only (LiveKit, microphone). The shipper app identifies the parcel by **`jobId`**.

## 32. Call the buyer or the shop
**Purpose**: From the job page: the rider (as herself) or the owner (as the business) calls the buyer or the shop.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls`

**Access Level**: 🔒 Protected (the rider holding the job; the business owner)

**Request JSON Sample**:
```json
{ "jobId": "00033c94-e8c2-471d-924c-27178fa7985f", "to": "BUYER" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| jobId | UUID | Yes | The job | accepted by the business, order still open |
| to | string | Yes | `BUYER` or `SHOP` | `DELIVERY` → `NOT_FOR_SHIPPERS` |
| businessId | UUID | No | Call as the business (needed on the office PC; on the owner's phone the server already calls as the business) | |

Who you call as:
```
 caller is the business owner ───────► SHIPPING_BUSINESS  ("EMS Courier")
 caller is the rider holding the job ─► RIDER             ("Mama Yoyo · rider for EMS Courier")
 anyone else ─────────────────────────► 409 NOT_ON_THIS_ORDER / NOT_YOUR_JOB
```

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Calling", "action_time": "2026-11-17T10:30:45",
  "data": {
    "call": { "callId": "6fb0…", "roomName": "call_6fb0…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" },
    "calling": { "role": "BUYER", "name": "Amina", "photo": "https://…", "parcelNumber": "NX-SQAW-ZL", "jobId": "0003…" },
    "allLinesBusy": false
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| call.token, call.url | Join now and wait (microphone only) |
| calling | Who is rung. **Never `orderNumber` / `orderId`** in this app |
| allLinesBusy | Calling the shop and every shop computer is on another call: "Everyone at the shop is on another call. Please wait, or call back later." |

**Errors**: `CALLS_CLOSED`, `NO_SHIPPER_YET`, `NOT_YOUR_JOB`, `NOT_ON_THIS_ORDER`, `NOT_FOR_SHIPPERS`, `BUSY`,
`SAME_PERSON` (e.g. the owner is also the buyer), `OWN_SHOP`.

**Normal phone call (backup):** while the job still shows phone numbers (`details`), the app may also offer the
phone's own dialer.

---

## 33. Answer a call
**Purpose**: Answer a ringing work call: as myself (`answerAs: ME`, a rider) or as the business (`answerAs: BUSINESS`).

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/join`

**Access Level**: 🔒 Protected

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| businessId | UUID | When the ring said `answerAs: BUSINESS` | Answer for the business; first to answer wins |

**Success Response JSON Sample**:
```json
{ "success": true, "httpStatus": "OK", "message": "Joined", "action_time": "2026-11-17T10:30:50",
  "data": { "callId": "6fb0…", "roomName": "call_6fb0…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" } }
```

**Errors**: `ANSWERED_ELSEWHERE` ("Answered by Peter M"), `CALL_ENDED`, `NOT_ON_THIS_CALL`, `NOT_YOUR_BUSINESS`.

---

## 34. Hang up, decline or cancel
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/end` (`?businessId=` when on the call as the business)

**Success Response**: `message` "Call ended", `data` = the call row (as in 36).

## 35. One call
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/{callId}` (`?businessId=` as in 33) — one row as in 36.

---

## 36. Calls list
**Purpose**: More → Calls. The rider's own calls (`rider=true`), or the business's (`businessId`), newest first.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls`

**Access Level**: 🔒 Protected

**Query Parameters**:
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| rider | boolean | No | `true`: calls on jobs given to me | false |
| businessId | UUID | No | The business's calls (owner) | |
| limit | integer | No | Max 50 | 30 |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Calls", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "callId": "6fb0…", "outgoing": false, "state": "ENDED", "outcome": "MISSED", "missed": true,
      "at": "2026-11-17T10:12:00+03:00", "durationSeconds": null,
      "other": { "role": "BUYER", "name": "Amina", "photo": "https://…", "parcelNumber": "NX-SQAW-ZL", "jobId": "0003…" },
      "callBack": "BUYER" }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| missed | Incoming and not answered, or it found me busy: show red |
| other.jobId | Send with `to` = `callBack` to 32 to call back |
| callBack | `BUYER` or `SHOP`; **absent** once the order's calls are closed or I'm no longer on the job |

---

## 37. Calls waiting for the business
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/waiting?businessId={businessId}`

**Access Level**: 🔒 Protected (owner; dispatchers on the office PC)

**Success Response**: calls still ringing for the business, oldest first:
`[ { callId, work: true, since, waitedSeconds, caller: { role, name, photo, parcelNumber, jobId } } ]`.

---

# Part 9 — Additions to existing responses

| Response | Added | Meaning |
|---|---|---|
| Job (`GET /shipping/jobs/{id}`, lists) | `assignee` `{ memberId, accountId, name, avatarUrl, since, removedWhileHolding }` | Who carries it. `null` = nobody. `removedWhileHolding` = the rider left or was removed while holding the parcel: show "Parcel with Mama Yoyo" |
| Job, for a rider | `cost`, `commission`, `payout`, `payoutStatus` = `null` | A rider never sees money. A dispatcher on the office PC does see job prices |
| Office computers | permission `RECEIVE_CALLS` | Business terminals can now take calls |

---

# Part 10 — Pushes and notifications

| Type | Contract | To | Behaviour |
|---|---|---|---|
| `JOB_ASSIGNED` | `JOB_ASSIGNED` | rider | rings, button **View** (lives 15 min) |
| `JOB_ASSIGNED_QUIET` | `SYSTEM` | rider | normal notice |
| `JOB_UNASSIGNED` | `JOB_UNASSIGNED` | rider | silent: stop the ring, drop the job |
| `JOB_CANCELLED` | `SYSTEM` | business + rider | the job was cancelled |
| `WORK_CALL_INCOMING` | `CALL_INCOMING` | rider (`answerAs: ME`, with `token`) · owner (`answerAs: BUSINESS`, `businessId`, no token) | ring full-screen like a phone call |
| `WORK_CALL_ENDED` | `CALL_ENDED` | same | stop ringing; `ANSWERED_ELSEWHERE` + `answeredBy`: someone else took it (ignore if it's you) |
| `WORK_CALL_MISSED` | `SYSTEM` | rider · owner | "Missed call from Amina · parcel NX-SQAW-ZL" |
| `MEMBER_NEW_PHONE` | bell | owner | a rider signed in on a phone they hadn't used, while they had another |
| `TEAM_INVITE`, `TEAM_REMOVED` | `SYSTEM` | the person | invites and removal |
| `TEAM_INVITE_ANSWERED`, `TEAM_MEMBER_LEFT` | `SYSTEM` | owner | answers and leavers |
| `TERMINAL_PIN_ALERT` | `SYSTEM` | owner | 5 wrong PINs on an office PC (locked 15 min) or 10 (removed) |

Ring data for calls (all strings): `callId`, `kind`, `roomName`, `url`, `ringSeconds`, `answerAs`, `work`,
`callerRole`, `callerName`, `callerAvatar`, `businessName`, `businessLogo`, `parcelNumber`, `jobId`, and `token` when
`answerAs` is `ME`. Full contract: `docs/notifications/push_contracts_api_doc.md` §4.2 and §4.8.

# Terminal App APIs

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated**: 2026-11-17  
**Version**: v1.0

**Base URL**: `https://api.nexgate.co/api/v1`

**Short Description**: Everything the terminal app needs: the shared computer (Windows/Mac desktop, or a shop tablet)
that sits at a shop counter or a shipping office. It links once to one shop or delivery business, shows the faces of
the people who work there, signs a person in with their own PIN, and then reaches **only** the screens that computer
is allowed: orders, products, chat and calls for a shop; offers, jobs, riders and calls for an office. Read
[`README.md`](README.md) first for roles, rights and terminal permissions.

**Hints**:
- **Two secrets live on the computer:** the **terminal key** (forever, until the owner removes the computer) and a
  person's **member session** (10 minutes, refreshed). Keep the key in the OS credential vault (Windows Credential
  Manager, macOS Keychain), never in a file.
- Every call sends `X-Terminal-Key`. A signed-in person's calls also send `Authorization: Bearer <member token>`.
- **The PIN never leaves the computer.** Send a `pinProof` derived from it (Part 1.4).
- Anything not listed in this document answers **403**. Don't call personal endpoints (profile, wallet, feed, personal
  chats); they are refused.
- Keep the live stream (Part 4) open **all the time the app runs**, also when nobody is signed in: alerts and calls
  arrive there. On Windows the app should live in the tray; warn before quitting ("Orders and calls won't reach this
  computer").
- When the team feature is off, every call answers **404** / **401**.

---

## Contents

- Part 1 — How it works (flows)
- Part 2 — Linking (1–2)
- Part 3 — On the computer: faces, adding people, signing in (3–12)
- Part 4 — The live stream (13)
- Part 5 — Shop counter: what a signed-in person may call
- Part 6 — Office (dispatch): what a signed-in person may call
- Part 7 — Calls on a terminal (14–19)
- Part 8 — Refusals and what to do

---

# Part 1 — How it works

## 1.1 The life of a terminal

```
  ┌───────────────┐   owner approves    ┌──────────────┐  someone taps a face  ┌───────────────┐
  │  NOT LINKED   │ ───────────────────►│   LOCKED     │ ────── + PIN ────────►│  SIGNED IN    │
  │ shows a code  │  (terminal key      │ faces screen │                       │ Jane's screens│
  │ every 30 s    │   saved once)       │ alerts ring  │◄─── Lock / 2–3 min ───│ (her rights ∩ │
  └───────────────┘                     │ calls ring   │      idle / 12 h      │  this PC)     │
          ▲                             └──────────────┘                       └───────────────┘
          │  TERMINAL_REMOVED (owner removed it, or 401 on the key)  → wipe everything, back to "not linked"
          └────────────────────────────────────────────────────────────────────────────────────────────
```

## 1.2 Linking (once)

```
 TERMINAL APP                                   SERVER                                OWNER'S PHONE
 POST /team/terminal-link/start ──────────────► { deviceCode, userCode: K7Q-4MX,
   { platform, appVersion }                       expiresIn: 30, interval: 2 }
 show K7Q-4MX big + as a QR
 every 2 s: POST /team/terminal-link/poll ────► authorization_pending
 every 30 s: start again (new code)                                                   scans, approves, ticks what
                                                ◄──────────────────────────────────── the PC may do
 POST /team/terminal-link/poll ───────────────► approved + terminalKey + settings
 save terminalKey in the vault (shown once)
 open the live stream, show the faces screen
```

## 1.3 Adding a person to this computer (once per person)

```
 TERMINAL APP                                   SERVER                                JANE'S PHONE (NexGate app)
 "Add me" → POST /team/terminal/enrol/start ──► { deviceCode, userCode: P2D-8WK }
 show the QR
 poll POST /team/terminal/enrol/poll ─────────► authorization_pending                 scans, "Add yourself to
                                                ◄──────────────────────────────────── Counter PC?" → add-me
 poll ────────────────────────────────────────► approved + person (Jane, photo)
 "Hi Jane, choose a PIN" (twice)
 POST /team/terminal/enrol/finish ────────────► Jane is on this computer
   { deviceCode, pinProof }                       + a member session (she's signed in)
```

Who can add themselves: an **active** member of this place. Shop: owner and staff. Office: owner and dispatchers.
Riders never.

## 1.4 Signing in with face + PIN, and the PIN proof

```
 faces screen → tap Jane → PIN pad → pinProof → POST /team/terminal/sessions { enrolmentId, pinProof }
                                                   ├─ right  → session (10 min token + refresh token)
                                                   ├─ wrong  → WRONG_PIN, details.triesLeft
                                                   ├─ 5th    → PIN_LOCKED 15 min (owner alerted)
                                                   └─ 10th   → PIN_TOO_MANY: Jane must add herself again
```

**pinProof**: derived from the PIN on the computer, at least 32 characters, the same PIN always giving the same proof
for that person on that computer. Recommended: PBKDF2-SHA256 of the PIN with a random per-person salt that the app
creates at "Add me" and keeps in the vault, 100 000 rounds, base64. The server keeps only a keyed hash of the proof
and counts every guess, so a stolen computer can't be used to guess PINs offline.

## 1.5 A session, minute by minute

```
 10:00  sign in ────────► accessToken (expires 10:10), refreshToken R1, sessionEnds 22:00
 10:09  refresh with R1 ─► new accessToken (10:19), R2   (R1 is now dead)
 10:12  Jane taps Lock / 2–3 min idle ─► POST /team/terminal/sessions/lock → faces screen
 any    the owner removes or locks Jane, resets her PIN, or removes the PC ─► the next call answers 401
 22:00  sessionEnds ─► sign in again
 R1 used again after R2 exists ─► SIGN_IN_AGAIN (the session is ended: someone copied it)
```

## 1.6 Every request is checked

```
 request ─► has X-Terminal-Key? ──no──► normal person rules (not this app)
               │ yes
               ▼
            key valid and computer not removed? ──no──► 401
               │
               ├── no Bearer token ──► path in "terminal alone" list (Part 3)? ──no──► 403
               │
               └── member token ──► same computer? session open? person still active here? ──no──► 401
                                       │ yes
                                       ▼
                                    path in this computer's allow-list (Part 5 / 6)? ──no──► 403
                                    person has the right it needs (their rights ∩ this PC)? ──no──► 403
                                    ?shopId / ?businessId = this computer's place (where required)? ──no──► 403
                                       │ yes
                                       ▼
                                    the endpoint runs, as this place only
```

---

# Part 2 — Linking

## 1. Start linking
**Purpose**: A new computer asks for a short code to show.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal-link/start`

**Access Level**: 🌐 Public (rate limited: 10 per minute per network address)

**Authentication**: None

**Request JSON Sample**:
```json
{ "platform": "WINDOWS", "appVersion": "0.1.0" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| platform | string | Yes | The computer's system | enum: `WINDOWS`, `MAC`, `LINUX`, `ANDROID`, `IOS`, `WEB` |
| appVersion | string | No | Terminal app version | max 30 |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Show this code", "action_time": "2026-11-17T09:00:00",
  "data": { "deviceCode": "kX9f…(secret)", "userCode": "K7Q-4MX", "expiresIn": 30, "interval": 2 }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| deviceCode | Secret; keep it in memory to poll. Never show it |
| userCode | Show big and as a QR (encode just the code) |
| expiresIn | Seconds; ask for a new code when it runs out |
| interval | Poll every this many seconds |

**Errors**: `PLATFORM` (unknown platform), `SLOW_DOWN` (too many starts).

---

## 2. Poll for approval
**Purpose**: Ask whether the owner approved the code.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal-link/poll`

**Access Level**: 🌐 Public

**Request JSON Sample**:
```json
{ "deviceCode": "kX9f…" }
```

**Success Response JSON Sample** (approved):
```json
{
  "success": true, "httpStatus": "OK", "message": "Link status", "action_time": "2026-11-17T09:00:14",
  "data": {
    "status": "approved",
    "terminalKey": "9b1c…e4.Qm9vb…",
    "terminal": { "terminalId": "9b1c…e4", "label": "Counter PC", "placeKind": "SHOP", "placeId": "cfb6…",
                  "placeName": "My Shop With Banner", "job": "SHOP_COUNTER",
                  "permissions": ["HANDLE_ORDERS", "ORDER_ALERTS", "CUSTOMER_CHAT", "RECEIVE_CALLS"] }
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| status | `authorization_pending` (keep polling), `slow_down` (wait longer), `expired_token` (start again), `approved` |
| terminalKey | **Shown once.** Save in the vault; send as `X-Terminal-Key` from now on. Lost → link again |
| terminal.job | `SHOP_COUNTER` (Part 5) or `DISPATCH` (Part 6) |
| terminal.permissions | What the owner allowed (README) |

---

# Part 3 — On the computer

Request headers for this part:

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| X-Terminal-Key | string | Yes | The terminal key |
| Authorization | string | Only where marked "member" | `Bearer <member accessToken>` |

## 3. Who's working? (faces)
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal/faces`

**Access Level**: 🔒 Terminal key

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Who's working?", "action_time": "2026-11-17T09:01:00",
  "data": [
    { "enrolmentId": "e1…", "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
      "avatarUrl": "https://…", "signedIn": false, "pinLockedUntil": null }
  ]
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| enrolmentId | Send with the PIN proof (7) |
| signedIn | Signed in here now |
| pinLockedUntil | After 5 wrong PINs: grey the face until then |

Re-read on `TERMINAL_FACES_CHANGED` (13).

---

## 4. "Add me": start
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/enrol/start`

**Access Level**: 🔒 Terminal key (10 per minute)

**Success Response**: `message` "Scan this with your phone", `data` = `{ deviceCode, userCode, expiresIn, interval }` as in 1.

---

## 5. "Add me": poll
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/enrol/poll`

**Access Level**: 🔒 Terminal key

**Request JSON Sample**: `{ "deviceCode": "…" }`

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Add me status", "action_time": "2026-11-17T09:02:10",
  "data": { "status": "approved",
            "person": { "enrolmentId": null, "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
                        "avatarUrl": "https://…", "signedIn": false, "pinLockedUntil": null } }
}
```

`status` as in 2. On `approved` greet "Hi Jane" and ask for a new PIN twice.

---

## 6. "Add me": finish
**Purpose**: Save the person on this computer with their PIN proof, and sign them in.

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/enrol/finish`

**Access Level**: 🔒 Terminal key

**Request JSON Sample**:
```json
{ "deviceCode": "kX9f…", "pinProof": "q8Zk3m…(base64, ≥ 32 chars)" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| deviceCode | string | Yes | From 4 | max 100 |
| pinProof | string | Yes | See 1.4 | 32–200 characters |

**Success Response**: `message` "You are on this computer", `data` = a session (as in 7).

**Errors**: `NOT_ACTIVE_HERE` (not an active member any more), `ROLE_NOT_FOR_TERMINAL`, `CODE_USED`.

---

## 7. Sign in (face + PIN)
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/sessions`

**Access Level**: 🔒 Terminal key

**Request JSON Sample**:
```json
{ "enrolmentId": "e1…", "pinProof": "q8Zk3m…" }
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| enrolmentId | UUID | Yes | The tapped face | |
| pinProof | string | Yes | See 1.4 | 32–200 characters |

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Signed in", "action_time": "2026-11-17T10:00:00",
  "data": {
    "accessToken": "eyJ…", "expiresIn": 600, "refreshToken": "e1….Zm9v…", "sessionEnds": "2026-11-17T22:00:00",
    "me": {
      "person": { "enrolmentId": "e1…", "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
                  "avatarUrl": "https://…", "signedIn": true, "pinLockedUntil": null },
      "role": "STAFF", "shopRoleName": "Order staff",
      "terminal": { "terminalId": "9b1c…", "label": "Counter PC", "placeKind": "SHOP", "placeId": "cfb6…",
                    "placeName": "My Shop With Banner", "job": "SHOP_COUNTER", "permissions": ["HANDLE_ORDERS", "ORDER_ALERTS"] },
      "shopRights": ["SEE_ORDERS", "HANDLE_ORDERS"], "businessRights": []
    }
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| accessToken | Member token: `Authorization: Bearer …` **with** `X-Terminal-Key` |
| expiresIn | Seconds (600). Refresh before (9) |
| refreshToken | One use only |
| sessionEnds | After this (12 hours), sign in again |
| me.shopRights / me.businessRights | **What this person may do on this computer**: hide every screen and button not covered. The server refuses them anyway |

**Errors**: `WRONG_PIN` (`details.triesLeft`), `PIN_LOCKED` (`details.until`), `PIN_TOO_MANY`, `NOT_ACTIVE_HERE`.

One session per person per computer: signing in again ends the previous one.

---

## 8. Lock
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/sessions/lock`

**Access Level**: 🔒 Member (key + member token)

**Success Response**: `message` "Locked", `data` `null`. Drop the tokens; back to the faces screen. Do this on the Lock
button and after 2–3 minutes without use.

---

## 9. Refresh the session
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/sessions/refresh`

**Access Level**: 🔒 Terminal key

**Request JSON Sample**: `{ "refreshToken": "e1….Zm9v…" }` (max 200)

**Success Response**: `message` "Session refreshed", `data` = a new session (as in 7); the old refresh token is dead.

**Errors**: `SIGN_IN_AGAIN` (an old refresh token was used, or the 12 hours are over): back to faces.

---

## 10. Me on this computer
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal/me`

**Access Level**: 🔒 Member

**Success Response**: `message` "You on this terminal", `data` = `me` as in 7. Re-read on `TERMINAL_SETTINGS_CHANGED`.

---

## 11. This computer's settings
**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal/settings`

**Access Level**: 🔒 Terminal key (also with a member token)

**Success Response**: `message` "This terminal", `data` = `terminal` as in 2. Show them read-only: "Set by the owner".

---

## 12. Heartbeat
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/team/terminal/heartbeat`

**Access Level**: 🔒 Terminal key (also with a member token)

**Request JSON Sample**: `{ "appVersion": "0.1.0" }` (optional body)

**Success Response**: `message` "Seen". Every few minutes; the live stream (13) also counts as seen.

---

# Part 4 — The live stream

## 13. Open the live stream
**Purpose**: Everything that must reach the computer at once: settings changes, order alerts, offers, chat, calls.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/team/terminal/stream` (server-sent events, `text/event-stream`)

**Access Level**: 🔒 Terminal key only. **Don't send the member token on the stream** (it would be refused); keep the
stream open while people sign in and out.

Keep it open while the app runs; reconnect with backoff (1 s, 2 s, 5 s, 10 s, then every 30 s). A comment `: ping`
comes every 20 seconds; no ping for 60 s → reconnect. **While the stream is connected the computer counts as "open"**
(it can be "somebody at the shop / office"); a closed stream counts as nobody.

### Events for every terminal

| Event | Data | Do |
|---|---|---|
| `READY` | `{}` | connected |
| `TERMINAL_SETTINGS_CHANGED` | `{ terminalId }` | re-read 11 and 10 (rights may have changed) |
| `TERMINAL_FACES_CHANGED` | `{}` | re-read 3; if the signed-in person is gone, back to faces |
| `TERMINAL_REMOVED` | `{}` | wipe the key and all local data; back to "not linked" |

### Shop counter events

| Event | Sent to computers ticked | Data | Do |
|---|---|---|---|
| `SHOP_NEW_ORDER` | Get order alerts | `orderId`, `orderNumber`, `items`, `total` | pop up with sound, **also when locked** |
| `ORDER_ACCEPT_REMINDER` | Get order alerts | `orderId`, `orderNumber`, `acceptBy` | pop up |
| `ORDER_CANCELLED`, `ORDER_DELIVERED` | Get order alerts | `orderId`, `orderNumber` | notice |
| `RIDER_COMING` | Get order alerts | `orderId`, `orderNumber`, `shipperName`, `check` | "EMS Courier is coming: check …" |
| `PARCEL_REFUSED` | Get order alerts | `orderId`, `orderNumber`, `shipperName` | notice |
| `ORDER_CHANGED` | all | `orderId`, `status` | re-read the order list |
| `message.created`, `message.updated`, `unread.changed`, `conversation.created`, `conversation.updated` | Customer chat | same as the app's chat events | update the inbox |
| `shop.typing` | Customer chat | `conversationId`, `shopId`, `accountId`, `name`, `untilMs` | "Jane is replying…" until `untilMs` |
| `call.incoming` | Receive calls | see Part 7 (**no token**) | ring, also when locked |
| `call.updated`, `call.ended` | Receive calls | `callId`, `outcome`, `answeredBy` | stop ringing / update |
| `SHOP_CALL_ANSWERED` | all | `callId`, `name`, `accountId` | "Answered by Jane": stop ringing |

### Office events

| Event | Sent to computers ticked | Data | Do |
|---|---|---|---|
| `JOB_OFFER`, `JOB_OFFER_REMINDER` | Get offers | `offerId`, `jobId`, `businessId`, `businessName`, from/to area and landmarks, `answerBy`, `expiresAtMs`, `serverNowMs`, `valueBand`, `roadKm`, `cost` | ring, also when locked (show faces of people who may accept) |
| `JOB_OFFER_CLOSED` | Get offers | `offerId`, `jobId`, `status` | stop ringing |
| `SHIPPER_CHANGED` | all | `businessId` | re-read lists |
| `call.incoming` | Receive calls | see Part 7 (**no token**) | ring, also when locked |
| `call.updated`, `call.ended` | all | `callId`, `outcome`, `answeredBy`, `work` | stop ringing / update |

---

# Part 5 — Shop counter: what a signed-in person may call

Every call below sends **both** headers. The request and response are **exactly the same as in the NexGate app** for the
owner; only the rules differ. "Needs" = the right the person must have **on this computer** (`me.shopRights`).
`?shopId=` marked ✅ = required, and must be this computer's shop.

### Orders

| Method | Path | Needs | `?shopId=` |
|---|---|---|---|
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/e-commerce/orders/shop/{shopId}/orders` (+ `/paged`, `/status/{status}`, `/status/{status}/paged`) | `SEE_ORDERS` | in the path |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/e-commerce/orders/{orderId}`, `/e-commerce/orders/number/{orderNumber}` | `SEE_ORDERS` | — |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/shipping/orders/{orderId}/accept`, `/ready`, `/hand-over`, `/hand-over-rider`, `/collect` | `HANDLE_ORDERS` | — |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/team/shops/{shopId}/orders/tags`, `/team/shops/{shopId}/orders/{orderId}/steps` | `SEE_ORDERS` | in the path |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/team/shops/{shopId}/orders/{orderId}/take`, `/release` | `HANDLE_ORDERS` | in the path |

- Accepting signs the order **as the shop**; who pressed it is in the steps.
- **Never:** cancelling, pickup time and pickup codes (the buyer's), refunds. A person's own purchases never open here.

### Products and stock

| Method | Path | Needs |
|---|---|---|
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/e-commerce/shops/{shopId}/products/my-shop-all` (+ `-paged`), `/{productId}/detailed` | `PRODUCTS` or `STOCK` |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/e-commerce/shops/{shopId}/products` | `PRODUCTS` |
| <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> | `/e-commerce/shops/{shopId}/products/{productId}` | `PRODUCTS` (details) and/or `STOCK` (quantities) |
| <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span> | `/e-commerce/shops/{shopId}/products/{productId}/publish` | `PRODUCTS` |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/files/request-upload`, `/files/thumbnail/{fileId}` | `PRODUCTS` (contexts `PRODUCT_IMAGE`, `PRODUCT_VIDEO`, `PRODUCT_PREVIEW_*`) or `CUSTOMER_CHAT` (`DM_IMAGE`, `DM_VIDEO`, `DM_DOCUMENT`) |

```
 Staff edits a product
   ├── name, photos, description, category, colours, limits ── needs PRODUCTS ── saved
   ├── stock, low-stock level, show stock ──────────────────── needs STOCK ───── saved
   └── price, compare price, group buying, instalments ─────── 409 PRICE_OWNER_ONLY (sending the current value is fine)
 Staff adds a product ─► saved as a DRAFT, whatever "action" said ─► the owner checks the price and publishes it
```

Other codes: `NO_PRODUCTS_RIGHT`, `NO_STOCK_RIGHT`, `OWNER_PUBLISHES`, `DIGITAL_OWNER_ONLY`. **Never:** delete/restore,
digital products.

### Chat (as the shop)

| Method | Path | Needs | `?shopId=` |
|---|---|---|---|
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/chat/conversations`, `/chat/conversations/archived/unread` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/chat/conversations/{conversationId}/messages` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> | `/chat/conversations/{conversationId}/messages/{messageId}` | `CUSTOMER_CHAT` (own messages only: `OWN_MESSAGES_ONLY`) | ✅ |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/chat/conversations/{conversationId}/read` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> | `/chat/conversations/{conversationId}/archive`, `/pin`, `/pinned-message` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> | `/chat/conversations/{conversationId}/pinned-message` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/chat/sync` | `CUSTOMER_CHAT` | ✅ |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/chat/offers` | `PRICE_OFFERS` | — |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/chat/offers/{offerId}` | `CUSTOMER_CHAT` | — |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/chat/offers/{offerId}/cancel` | `PRICE_OFFERS` | — |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/team/shops/{shopId}/chat/conversations/{conversationId}/senders` | `CUSTOMER_CHAT` | in the path |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/team/shops/{shopId}/chat/conversations/{conversationId}/typing` | `CUSTOMER_CHAT` | in the path |

- Without `?shopId=` the chat endpoints would mean the person's own chats, so the server answers **403**.
- **Never:** mute, delete a conversation, disappearing messages, secret or personal chats, `/chat/contexts/me`,
  `/events`.
- Name tags: show "— Jane" under the shop's messages using `senders`. Customers never see them.

### Calls

See Part 7. Allowed for `ANSWER_CALLS`: `POST /calls` (body `shopId`), `POST /calls/{callId}/join|end`,
`GET /calls/{callId}`, `GET /calls` (all with `?shopId=` ✅), `GET /team/shops/{shopId}/calls/missed`, and every
`/work-calls` path with `?shopId=` ✅ (start carries `shopId` in its body).

---

# Part 6 — Office (dispatch): what a signed-in person may call

Same rules as Part 5, with `me.businessRights`. `?businessId=` ✅ = required, and must be this computer's business.

| Method | Path | Needs | Notes |
|---|---|---|---|
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/shipping/businesses/{businessId}/offers`, `/upcoming`, `/jobs` | `VIEW_JOBS` | always on an office PC |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/shipping/jobs/{jobId}` | `VIEW_JOBS` | a dispatcher sees prices; never earnings |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/shipping/offers/{offerId}/accept`, `/reject`, `/received` | `ANSWER_OFFERS` | first tap wins (the owner's phone may also accept) |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/shipping/businesses/{businessId}/riders` | `ASSIGN_JOBS` | shipper app doc §8 |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/shipping/jobs/{jobId}/assign`, `/unassign` | `ASSIGN_JOBS` | shipper app doc §9–10 |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/work-calls` | `ANSWER_CALLS` | body `businessId` |
| <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> | `/work-calls/{callId}/join`, `/end` | `ANSWER_CALLS` | `?businessId=` ✅ |
| <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> | `/work-calls/{callId}`, `/work-calls`, `/work-calls/waiting` | `ANSWER_CALLS` | `?businessId=` ✅ |

**Never from an office PC:** earnings, reports, setup, pause, phones, team, reviews, documents, "my assigned jobs",
wallet. Who accepted or rejected each offer is in the activity log.

```
 Offer rings on the office PC (locked, faces shown)
   → Peter taps his face + PIN → offer list → Accept
   → POST /shipping/offers/{id}/accept  (first tap wins; the owner's phone gets the usual "already taken")
   → GET …/riders → Mama Yoyo (on duty, phone can ring) → POST /shipping/jobs/{jobId}/assign
```

---

# Part 7 — Calls on a terminal

A shop or office with computers works like a small call centre.

```
 Call to the shop / office
     │
     ▼
 every open computer ticked "Receive calls" gets call.incoming (no token)
     ├── locked: ring + show the faces of people who may answer
     ├── signed in, free: ring
     └── already on a call: don't ring loudly; add it to the waiting list (18)
     │
     ▼
 someone answers (14/15) ──► first wins ──► everyone else: SHOP_CALL_ANSWERED / call.updated → stop ringing
 nobody in 45 s ──► call.ended (MISSED) ──► missed list (shop chat calls: missed endpoint; parcel calls: 17)
 every computer busy ──► the owner's phone rings per her setting; the caller is told "everyone is on another call"
```

`call.incoming` data: `callId`, `kind` (`AUDIO`), `roomName`, `url`, `ringSeconds`, `callerJid`, `callerName`,
`callerAvatar`, `answerAs` (`SHOP` / `BUSINESS`), `shopId` or `businessId`, and for a call about a parcel: `work: "true"`,
`callerRole`, `businessName`, `businessLogo`, `parcelNumber`, plus `orderNumber` + `orderId` (shop) or `jobId` (office).
A shop chat call carries `conversationId` instead of `work`.

## 14. Answer a customer's call (shop chat call)
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/calls/{callId}/join?shopId={shopId}`

**Access Level**: 🔒 Member with `ANSWER_CALLS`

**Success Response JSON Sample**:
```json
{ "success": true, "httpStatus": "OK", "message": "Joined", "action_time": "2026-11-17T10:30:50",
  "data": { "callId": "k-90…", "roomName": "call_k-90…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" } }
```

**Errors**: `ANSWERED_ELSEWHERE` ("Answered by Jane"), `CALL_ENDED`.

## 15. Answer a call about a parcel
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/join?shopId={shopId}` (shop) or `?businessId={businessId}` (office)

**Access Level**: 🔒 Member with `ANSWER_CALLS`

**Success Response**: as in 14. Join the LiveKit room with `token` (microphone only).

**Errors**: `ANSWERED_ELSEWHERE`, `CALL_ENDED`, `NOT_ON_THIS_CALL`.

## 16. Call the delivery (shop) / the buyer or shop (office)
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls`

**Access Level**: 🔒 Member with `ANSWER_CALLS`

**Request JSON Sample** (shop computer):
```json
{ "orderId": "0f05…", "to": "DELIVERY", "shopId": "cfb6…" }
```

**Request JSON Sample** (office computer):
```json
{ "jobId": "0003…", "to": "BUYER", "businessId": "2a19…" }
```

**Success Response**: `{ call, calling, allLinesBusy }` as in the NexGate app doc §34.

**Errors**: `ACT_AS_PLACE` (no `shopId`/`businessId`: a computer always calls as its place), `CALLS_CLOSED`,
`NO_SHIPPER_YET`, `BUSY`, `NOT_YOUR_SHOP`, `NOT_YOUR_BUSINESS`.

## 17. Hang up / call list / one call
- <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/work-calls/{callId}/end?shopId=|businessId=`
- <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls?shopId=|businessId=&limit=30` — history rows (`other`, `missed`, `callBack`)
- <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/{callId}?shopId=|businessId=`
- Shop chat calls: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `/calls/{callId}/end?shopId=`, <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `/calls?shopId=`, <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `/team/shops/{shopId}/calls/missed`

## 18. The waiting queue
**Purpose**: Calls still ringing at this place, oldest first, so a free person can take the longest-waiting one.

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/work-calls/waiting?shopId={shopId}` (or `?businessId=`)

**Access Level**: 🔒 Member with `ANSWER_CALLS`

**Success Response JSON Sample**:
```json
{
  "success": true, "httpStatus": "OK", "message": "Waiting calls", "action_time": "2026-11-17T10:30:45",
  "data": [
    { "callId": "k-90…", "work": false, "conversationId": "c-12…", "since": "2026-11-17T10:30:10+03:00", "waitedSeconds": 35,
      "caller": { "role": "BUYER", "name": "Amina", "photo": "https://…" } },
    { "callId": "6fb1…", "work": true, "since": "2026-11-17T10:30:30+03:00", "waitedSeconds": 15,
      "caller": { "role": "RIDER", "name": "Mama Yoyo", "businessName": "EMS Courier", "orderNumber": "ORD-2026-23424",
                  "parcelNumber": "NX-SQAW-ZL", "orderId": "0f05…" } }
  ]
}
```

Answer `work: false` with 14 and `work: true` with 15. Re-read on every `call.*` event.

## 19. Call a customer back (shop)
**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/calls` with `{ "conversationId": "…", "kind": "AUDIO", "shopId": "…" }`

**Access Level**: 🔒 Member with `ANSWER_CALLS`

Only inside the customer's 24-hour window (the existing chat rule). A personal call (no `shopId`) is refused.

---

# Part 8 — Refusals and what to do

| Answer | Meaning | Do |
|---|---|---|
| `401` on any call with only the key | the computer was removed | wipe, back to "not linked" |
| `401` with a member token | the session ended (locked by the owner, removed, PIN reset, 12 h over) | back to faces |
| `403` | the path isn't allowed on this computer, or the person lacks the right, or `?shopId`/`?businessId` missing or wrong | hide that action; never retry |
| `409 WRONG_PIN` | `details.triesLeft` | "Wrong PIN, 3 tries left" |
| `409 PIN_LOCKED` | `details.until` | grey the face until then |
| `409 PIN_TOO_MANY` | 10 wrong | "Ask the owner, then add yourself again" |
| `409 SIGN_IN_AGAIN` | refresh token reused or session over | back to faces |
| `409 ANSWERED_ELSEWHERE` | someone else took the call | stop ringing, show who |
| `409 ORDER_TAKEN` | someone else is packing it | show who |
| `409 PRICE_OWNER_ONLY`, `OWNER_PUBLISHES` | prices and publishing staff products are the owner's | hide those fields / buttons |