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 |