# 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.