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 ──► Mama Yoyo's shipper app (no rider on it → EMS Courier: office + owner)
Shop ── Call delivery ──► same
Mama Yoyo / EMS ── Call buyer ──► Amina's NexGate app
Mama Yoyo / EMS ── 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 whoever has the parcel now: the rider on the job, else the delivery business.
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": "RIDER", "name": "Mama Yoyo", "photo": "https://…", "businessName": "EMS Courier",
"businessLogo": "https://…", "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 ("Calling Mama Yoyo · rider for EMS Courier") |
| calling.role | RIDER or SHIPPING_BUSINESS |
| 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 rider 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": "RIDER", "name": "Mama Yoyo", "photo": "https://…", "businessName": "EMS Courier",
"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", "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…" } }
]
}
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, photo } |
The rider the business gave that leg to. 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, businessName, businessLogo, 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", "photo": "https://…" } }
]
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) |