Team Mng Service
Team Mng Into
Base URL: https://api.nexgate.co/api/v1 (production) — https://dev.api.nexgate.co/api/v1 (staging) — http://localhost:8765/api/v1 (local)
Short Description: Shops and delivery businesses can have a team. The owner invites people, gives them a role, links shared computers (terminals) and decides what each computer may do. Riders work from their own phone in the shipper app; shop staff and dispatchers work only on terminals. This page explains the ideas once and tells each app team which document is theirs.
Hints:
- Read only your app's document. Each one lists every call that app makes, written for that app.
- When the team feature is switched off (production for now), every team endpoint answers 404.
- A person is identified only by
accountId. Never send or store a username to point at a person. - Coded refusals are HTTP 409 with
data.code: switch on the code, never on the message. - Times without a zone are East Africa Time (
2026-11-17T10:30:45). Times with a zone are ISO 8601.
Which document is mine?
| I build… | My document | Who uses those screens |
|---|---|---|
| NexGate app (Android, iOS, web) | nexgate_app_team_api.md |
shop owners (team, roles, shop computers, calls), anyone invited to a team, buyers (who is bringing my parcel, calling the delivery) |
| Shipper app (Android) | shipper_app_team_api.md |
delivery business owners (team, riders, office computers, calls), riders (my jobs, duty, calls) |
| Terminal app (Windows / Mac desktop, shop tablet) | terminal_app_api.md |
the shop counter computer and the shipping office computer: shop staff, dispatchers, and owners when they sit there |
- Pushes:
docs/notifications/push_contracts_api_doc.md(all apps). - Product rules:
docs/team/SHOP_TEAM.md,docs/team/SHIPPER_TEAM.md,docs/team/WORK_CALLS.md. - What changed for existing screens:
docs/changelog/frontend_changelog_2026-11-17.md.
The picture
┌───────────────────────────── SHOP: My Shop With Banner ─────────────────────────────┐
│ OWNER (Joshua) STAFF (Jane: "Order staff") STAFF (Rose: "Customer care") │
│ NexGate app, own phone only on shop computers only on shop computers │
│ │ │ │ │
│ │ links + sets rights ▼ ▼ │
│ └──────────────► [ Counter PC ] ◄──────────── [ Back office tablet ] │
└──────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────── DELIVERY BUSINESS: EMS Courier ─────────────────────────┐
│ OWNER (Joshua) DISPATCHER (Peter) RIDER (Mama Yoyo) │
│ shipper app, own phone only on the office computer shipper app, own phone │
│ │ │ ▲ │
│ │ links + sets rights ▼ │ jobs given to her│
│ └──────────────► [ Office PC ] ──── assigns jobs ────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
Key ideas
Places and roles
A place is a shop or a delivery business. In paths it appears as {kind}/{placeId}:
{kind} |
{placeId} |
Roles a person can have there |
|---|---|---|
shops |
the shop id | OWNER, STAFF (with a shop role, see below) |
businesses |
the delivery business id | OWNER, DISPATCHER, RIDER |
- The owner is the person who created the place. They always hold every right and can never be removed, locked, given another role, or leave.
- Business roles are fixed. A dispatcher accepts offers and assigns riders on the office computer. A rider carries the jobs given to them, from their own phone, and never sees money.
- Shop roles are built by each shop from the rights NexGate defines. Three ready-made roles (Order staff, Customer care, Shop manager) appear on first use and can be edited or deleted.
Shop rights
| Right | Allows |
|---|---|
SEE_ORDERS |
view the shop's orders |
HANDLE_ORDERS |
accept, mark Ready, hand over with the shipper's code, collect |
CUSTOMER_CHAT |
read and reply to customers as the shop |
PRICE_OFFERS |
send and cancel a special-price offer in chat |
ANSWER_CALLS |
answer and make calls as the shop |
PRODUCTS |
add products; edit names, photos, descriptions (never prices) |
STOCK |
change quantities, low-stock level, out of stock |
Never a right (owner only): catalogue prices and selling terms, money, cancelling orders, shop settings, team, roles, terminals.
Business rights (fixed by role)
| Right | Owner | Dispatcher | Rider |
|---|---|---|---|
VIEW_JOBS |
✅ | ✅ | only jobs given to them |
ANSWER_OFFERS |
✅ | ✅ | ❌ |
ASSIGN_JOBS |
✅ | ✅ | ❌ |
ANSWER_CALLS |
✅ | ✅ | only calls about their own jobs |
VIEW_EARNINGS |
✅ | ❌ | ❌ |
Terminals (shared computers)
A terminal is a computer or tablet linked to one place. The owner links it from her own phone and ticks what it may do (its permissions). People tap their face on it and type their own PIN.
What a person may do ON a terminal = their rights ∩ the terminal's permissions
Jane ("Order staff": SEE_ORDERS, HANDLE_ORDERS) on Counter PC (HANDLE_ORDERS, RECEIVE_CALLS)
→ SEE_ORDERS, HANDLE_ORDERS (no ANSWER_CALLS: Jane's role doesn't have it)
| Terminal permission | Kind | Gives (if the person also has it) |
|---|---|---|
ORDER_ALERTS |
shop | SEE_ORDERS + new-order pop-ups |
HANDLE_ORDERS |
shop | SEE_ORDERS, HANDLE_ORDERS |
CUSTOMER_CHAT |
shop | CUSTOMER_CHAT, PRICE_OFFERS |
RECEIVE_CALLS |
shop and business | ANSWER_CALLS + incoming call rings |
PRODUCTS_STOCK |
shop | PRODUCTS, STOCK |
GET_OFFERS |
business | ANSWER_OFFERS + offer rings |
ASSIGN_RIDERS |
business | ASSIGN_JOBS |
The three kinds of caller
Every request is one of these. The server checks which on every call.
┌─────────────────────────┬───────────────────────────────────────────┬──────────────────────────────────────────┐
│ Caller │ Sends │ Reaches │
├─────────────────────────┼───────────────────────────────────────────┼──────────────────────────────────────────┤
│ A person, own phone │ Authorization: Bearer <person token> │ everything, as today │
│ The terminal alone │ X-Terminal-Key: <terminal key> │ only the terminal's own calls │
│ │ │ (faces, sign in, settings, live stream) │
│ A person on a terminal │ Authorization: Bearer <member token> │ only that terminal's allow-list, │
│ (member session) │ + X-Terminal-Key: <terminal key> │ only for that place, only with the right │
└─────────────────────────┴───────────────────────────────────────────┴──────────────────────────────────────────┘
Anything not on a terminal's allow-list answers 403 before any feature code runs. A member token without its terminal's key answers 401.
Activity
Every team action is recorded with who did it and on which terminal. The owner sees everyone; a member sees only their own. Kept one year; nobody can edit or delete a row, not even the owner.
Standard Response Format
Success Response Structure
{
"success": true,
"httpStatus": "OK",
"message": "Invite sent",
"action_time": "2026-11-17T10:30:45",
"data": { }
}
Coded refusal (HTTP 409)
{
"success": false,
"httpStatus": "CONFLICT",
"message": "This person is already invited or on the team",
"action_time": "2026-11-17T10:30:45",
"data": { "code": "ALREADY_INVITED", "reason": "This person is already invited or on the team" }
}
Some refusals carry data.details (for example WRONG_PIN → details.triesLeft).
Standard Response Fields
| Field | Type | Description |
|---|---|---|
success |
boolean | true for success, false for errors |
httpStatus |
string | HTTP status name (OK, CONFLICT, NOT_FOUND, …) |
message |
string | Human-readable result; safe to show |
action_time |
string | When the response was made |
data |
object/string | The payload, or the error details |
Standard Error Types
400 BAD_REQUEST: invalid request data401 UNAUTHORIZED: missing, invalid or expired token; a member token without its terminal key; a session that ended403 FORBIDDEN: a terminal calling something not on its allow-list, or for another place404 NOT_FOUND: the thing doesn't exist, isn't yours, or the team feature is off409 CONFLICT: a coded refusal (data.code), listed per endpoint422 UNPROCESSABLE_ENTITY: validation failed (datahas one message per field)429 TOO_MANY_REQUESTS: rate limit
HTTP Method Badge Standards
- GET - GET - read
- POST - POST - create / act
- PUT - PUT - replace
- PATCH - PATCH - change some fields
- DELETE - DELETE - remove
All refusal codes
| Code | Meaning | Where |
|---|---|---|
NOT_THE_OWNER |
only the owner does this | team, roles, terminals, settings |
INVITE_WHO |
send exactly one of accountId / phone |
invite |
ROLE_NOT_FOR_BUSINESSES, ROLE_NOT_FOR_SHOPS, SHOP_ROLE_REQUIRED |
wrong kind of role for this place | invite, change role |
CANNOT_INVITE_YOURSELF |
the owner invited their own account or number | invite |
ALREADY_INVITED |
already invited or on the team | invite |
TOO_MANY_INVITES, TOO_MANY_PHONE_INVITES |
20 invites per place per hour, 5 of them by phone | invite |
PHONE_INVALID |
the number can't be read | invite |
INVITE_NOT_OPEN, INVITE_EXPIRED |
withdrawn / answered, or older than 6 hours | accept, decline, withdraw |
ALREADY_ON_TEAM |
accepting a phone invite while already on that team | accept |
OWNER_ROLE_FIXED, OWNER_CANNOT_BE_REMOVED, OWNER_CANNOT_LEAVE |
the owner's own row | team |
NOT_ON_TEAM, MEMBER_STATE |
not on the team (any more); wrong state (e.g. unlocking someone not locked) | team |
ROLE_NAME_TAKEN, ROLE_EMPTY, ROLE_IN_USE |
shop roles | roles |
MEMBER_REQUIRED, OWN_ACTIVITY_ONLY |
activity | activity |
RIDER_NOT_AVAILABLE, RIDER_OFF_DUTY, JOB_NOT_ASSIGNABLE, ASSIGN_RACE |
giving a job to a rider | riders |
RIDER_HOLDS_PARCEL, PARCEL_IN_HAND, RIDERS_ONLY |
a rider holding a parcel; rider-only calls | riders |
PLATFORM, SLOW_DOWN, CODE_USED, TOO_MANY_TERMINALS, PERMISSION_NOT_HERE |
linking a terminal | terminals |
ROLE_NOT_FOR_TERMINAL, NOT_ACTIVE_HERE |
adding yourself to / signing in on a terminal | terminals |
WRONG_PIN, PIN_LOCKED, PIN_TOO_MANY, SIGN_IN_AGAIN |
PIN and session | terminals |
ORDER_TAKEN, ORDER_FINISHED |
packing tags | shop orders |
NO_ORDER, NO_SHIPPER_YET, CALLS_CLOSED, NOT_ON_THIS_ORDER, NOT_YOUR_JOB, NOT_YOUR_ORDER, USE_SHOP_CALLS, NOT_FOR_SHIPPERS, SAME_PERSON, OWN_BUSINESS, OWN_SHOP, BUSY, ACT_AS_PLACE, NOT_YOUR_SHOP, NOT_YOUR_BUSINESS, NOT_ON_THIS_CALL, ANSWERED_ELSEWHERE, NO_PLACE |
calls about a parcel | work calls |
Endpoints
NexGate App — Team APIs
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 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}=shopsand{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: POST {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:
{ "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:
{
"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.
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: GET {base_url}/team/shops/{shopId}/members
Access Level: 🔒 Protected (shop owner only)
Authentication: Bearer token
Success Response JSON Sample:
{
"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: POST {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: PUT {base_url}/team/shops/{shopId}/members/{memberId}/role
Access Level: 🔒 Protected (shop owner only)
Request JSON Sample:
{ "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: POST {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: POST {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: POST {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: GET {base_url}/team/shops/{shopId}/roles
Access Level: 🔒 Protected (shop owner only)
Success Response JSON Sample:
{
"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: POST {base_url}/team/shops/{shopId}/roles
Access Level: 🔒 Protected (shop owner only)
Request JSON Sample:
{ "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: PUT {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: DELETE {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: GET {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:
{
"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: GET {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:
{
"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: GET {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):
{
"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: POST {base_url}/team/shops/{shopId}/terminals/link
Access Level: 🔒 Protected (shop owner only, from her own phone)
Request JSON Sample:
{ "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: GET {base_url}/team/shops/{shopId}/terminals
Access Level: 🔒 Protected (shop owner only)
Success Response JSON Sample:
{
"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: PATCH {base_url}/team/shops/{shopId}/terminals/{terminalId}
Access Level: 🔒 Protected (shop owner only)
Request JSON Sample:
{ "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: POST {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: POST {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: GET {base_url}/team/shops/{shopId}/orders/tags
Access Level: 🔒 Protected (owner, or SEE_ORDERS)
Success Response JSON Sample:
{
"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: POST {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.
22. Release an order
Purpose: Drop your own tag (the owner: anyone's).
Endpoint: POST {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: GET {base_url}/team/shops/{shopId}/orders/{orderId}/steps
Access Level: 🔒 Protected (owner, or SEE_ORDERS)
Success Response JSON Sample:
{
"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
Endpoint: GET {base_url}/team/shops/{shopId}/chat/conversations/{conversationId}/senders
Access Level: 🔒 Protected (owner, or CUSTOMER_CHAT)
Success Response JSON Sample:
{
"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: POST {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: GET {base_url}/team/shops/{shopId}/calls
Access Level: 🔒 Protected (shop owner only)
Success Response JSON Sample:
{
"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: PUT {base_url}/team/shops/{shopId}/calls/ring-mode
Access Level: 🔒 Protected (shop owner only)
Request JSON Sample:
{ "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: GET {base_url}/team/shops/{shopId}/calls/missed
Access Level: 🔒 Protected (owner, or ANSWER_CALLS)
Success Response JSON Sample:
{
"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: GET {base_url}/team/me
Access Level: 🔒 Protected (any signed-in person)
Success Response JSON Sample:
{
"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: POST {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: POST {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: POST {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: POST {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: POST {base_url}/work-calls
Access Level: 🔒 Protected (the order's buyer; or the shop with shopId: owner or ANSWER_CALLS)
Request JSON Sample (buyer):
{ "orderId": "0f059667-6e07-4230-bc6b-a94185cfce0c", "to": "DELIVERY" }
Request JSON Sample (shop owner, as the shop):
{ "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:
{
"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: POST {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:
{
"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: POST {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: GET {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: GET {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:
{
"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: GET {base_url}/work-calls/waiting?shopId={shopId}
Access Level: 🔒 Protected (owner, or ANSWER_CALLS)
Success Response JSON Sample:
{
"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 |
"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
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 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}=businessesand{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, nobusinessId). Rider rings reach it; the business's offer rings never do. - Shippers never get an order number or order id. Calls and jobs carry
jobIdandparcelNumber. - 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: POST {base_url}/team/businesses/{businessId}/invites
Access Level: 🔒 Protected (business owner only)
Authentication: Bearer token
Request JSON Sample:
{ "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:
{
"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: GET {base_url}/team/businesses/{businessId}/members
Access Level: 🔒 Protected (business owner only)
Success Response JSON Sample:
{
"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: POST {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: PUT {base_url}/team/businesses/{businessId}/members/{memberId}/role
Access Level: 🔒 Protected (business owner only)
Request JSON Sample:
{ "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: POST {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: POST {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: POST {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: GET {base_url}/shipping/businesses/{businessId}/riders
Access Level: 🔒 Protected (owner; dispatchers on the office PC)
Success Response JSON Sample:
{
"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: POST {base_url}/shipping/jobs/{jobId}/assign
Access Level: 🔒 Protected (owner; dispatchers on the office PC)
Request JSON Sample:
{ "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: POST {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: GET {base_url}/team/terminal-codes/{userCode}
Access Level: 🔒 Protected (any signed-in person)
Success Response JSON Sample:
{
"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: POST {base_url}/team/businesses/{businessId}/terminals/link
Access Level: 🔒 Protected (business owner only, own phone)
Request JSON Sample:
{ "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: GET {base_url}/team/businesses/{businessId}/terminals
Access Level: 🔒 Protected (business owner only)
Success Response JSON Sample:
{
"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: PATCH {base_url}/team/businesses/{businessId}/terminals/{terminalId}
Access Level: 🔒 Protected (business owner only)
Request JSON Sample:
{ "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: POST {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: POST {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: GET {base_url}/shipping/businesses/{businessId}/office
Access Level: 🔒 Protected (business owner only)
Success Response JSON Sample:
{
"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: PUT {base_url}/shipping/businesses/{businessId}/office/ring-mode
Access Level: 🔒 Protected (business owner only, own phone)
Request JSON Sample:
{ "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: GET {base_url}/shipping/businesses/{businessId}/office/work-calls
Access Level: 🔒 Protected (business owner only)
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Work calls", "action_time": "2026-11-17T10:30:45",
"data": { "ringBusinessWhenRiderMisses": false }
}
20. Change the calls setting
Endpoint: PUT {base_url}/shipping/businesses/{businessId}/office/work-calls
Access Level: 🔒 Protected (business owner only)
Request JSON Sample:
{ "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: GET {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: GET {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: GET {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:
{
"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: GET {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: GET {base_url}/team/me
Access Level: 🔒 Protected (any signed-in person)
Success Response JSON Sample:
{
"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: POST {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: POST {base_url}/team/invites/{memberId}/decline — message "Invite declined", data null.
27. Leave
Endpoint: POST {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: POST {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: GET {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: GET {base_url}/shipping/riders/me/stats
Success Response JSON Sample:
{ "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: POST {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: POST {base_url}/work-calls
Access Level: 🔒 Protected (the rider holding the job; the business owner)
Request JSON Sample:
{ "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:
{
"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: POST {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:
{ "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: POST {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: GET {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: GET {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:
{
"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: GET {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
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 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 sendAuthorization: Bearer <member token>. - The PIN never leaves the computer. Send a
pinProofderived 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: POST {base_url}/team/terminal-link/start
Access Level: 🌐 Public (rate limited: 10 per minute per network address)
Authentication: None
Request JSON Sample:
{ "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:
{
"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: POST {base_url}/team/terminal-link/poll
Access Level: 🌐 Public
Request JSON Sample:
{ "deviceCode": "kX9f…" }
Success Response JSON Sample (approved):
{
"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: GET {base_url}/team/terminal/faces
Access Level: 🔒 Terminal key
Success Response JSON Sample:
{
"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: POST {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: POST {base_url}/team/terminal/enrol/poll
Access Level: 🔒 Terminal key
Request JSON Sample: { "deviceCode": "…" }
Success Response JSON Sample:
{
"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: POST {base_url}/team/terminal/enrol/finish
Access Level: 🔒 Terminal key
Request JSON Sample:
{ "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: POST {base_url}/team/terminal/sessions
Access Level: 🔒 Terminal key
Request JSON Sample:
{ "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:
{
"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: POST {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: POST {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: GET {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: GET {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: POST {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: GET {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= |
|---|---|---|---|
| GET | /e-commerce/orders/shop/{shopId}/orders (+ /paged, /status/{status}, /status/{status}/paged) |
SEE_ORDERS |
in the path |
| GET | /e-commerce/orders/{orderId}, /e-commerce/orders/number/{orderNumber} |
SEE_ORDERS |
— |
| POST | /shipping/orders/{orderId}/accept, /ready, /hand-over, /hand-over-rider, /collect |
HANDLE_ORDERS |
— |
| GET | /team/shops/{shopId}/orders/tags, /team/shops/{shopId}/orders/{orderId}/steps |
SEE_ORDERS |
in the path |
| POST | /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 |
|---|---|---|
| GET | /e-commerce/shops/{shopId}/products/my-shop-all (+ -paged), /{productId}/detailed |
PRODUCTS or STOCK |
| POST | /e-commerce/shops/{shopId}/products |
PRODUCTS |
| PUT | /e-commerce/shops/{shopId}/products/{productId} |
PRODUCTS (details) and/or STOCK (quantities) |
| PATCH | /e-commerce/shops/{shopId}/products/{productId}/publish |
PRODUCTS |
| POST | /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= |
|---|---|---|---|
| GET | /chat/conversations, /chat/conversations/archived/unread |
CUSTOMER_CHAT |
✅ |
| GET POST | /chat/conversations/{conversationId}/messages |
CUSTOMER_CHAT |
✅ |
| DELETE | /chat/conversations/{conversationId}/messages/{messageId} |
CUSTOMER_CHAT (own messages only: OWN_MESSAGES_ONLY) |
✅ |
| POST | /chat/conversations/{conversationId}/read |
CUSTOMER_CHAT |
✅ |
| PUT | /chat/conversations/{conversationId}/archive, /pin, /pinned-message |
CUSTOMER_CHAT |
✅ |
| DELETE | /chat/conversations/{conversationId}/pinned-message |
CUSTOMER_CHAT |
✅ |
| GET | /chat/sync |
CUSTOMER_CHAT |
✅ |
| POST | /chat/offers |
PRICE_OFFERS |
— |
| GET | /chat/offers/{offerId} |
CUSTOMER_CHAT |
— |
| POST | /chat/offers/{offerId}/cancel |
PRICE_OFFERS |
— |
| GET | /team/shops/{shopId}/chat/conversations/{conversationId}/senders |
CUSTOMER_CHAT |
in the path |
| POST | /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 |
|---|---|---|---|
| GET | /shipping/businesses/{businessId}/offers, /upcoming, /jobs |
VIEW_JOBS |
always on an office PC |
| GET | /shipping/jobs/{jobId} |
VIEW_JOBS |
a dispatcher sees prices; never earnings |
| POST | /shipping/offers/{offerId}/accept, /reject, /received |
ANSWER_OFFERS |
first tap wins (the owner's phone may also accept) |
| GET | /shipping/businesses/{businessId}/riders |
ASSIGN_JOBS |
shipper app doc §8 |
| POST | /shipping/jobs/{jobId}/assign, /unassign |
ASSIGN_JOBS |
shipper app doc §9–10 |
| POST | /work-calls |
ANSWER_CALLS |
body businessId |
| POST | /work-calls/{callId}/join, /end |
ANSWER_CALLS |
?businessId= ✅ |
| GET | /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: POST {base_url}/calls/{callId}/join?shopId={shopId}
Access Level: 🔒 Member with ANSWER_CALLS
Success Response JSON Sample:
{ "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: POST {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: POST {base_url}/work-calls
Access Level: 🔒 Member with ANSWER_CALLS
Request JSON Sample (shop computer):
{ "orderId": "0f05…", "to": "DELIVERY", "shopId": "cfb6…" }
Request JSON Sample (office computer):
{ "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
- POST
{base_url}/work-calls/{callId}/end?shopId=|businessId= - GET
{base_url}/work-calls?shopId=|businessId=&limit=30— history rows (other,missed,callBack) - GET
{base_url}/work-calls/{callId}?shopId=|businessId= - Shop chat calls: POST
/calls/{callId}/end?shopId=, GET/calls?shopId=, GET/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: GET {base_url}/work-calls/waiting?shopId={shopId} (or ?businessId=)
Access Level: 🔒 Member with ANSWER_CALLS
Success Response JSON Sample:
{
"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: POST {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 |