Endpoints

NexGate App — Team APIs

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2026-11-17
Version: v1.0

Base URL: https://api.nexgate.co/api/v1

Short Description: Everything the NexGate app (Android, iOS, web) needs for teams: a shop owner builds her team, roles and shop computers and takes calls; anyone answers invites and adds themselves to a shop computer; a buyer sees who is bringing the parcel and can call the delivery. Read README.md first for roles, rights and terminals.

Hints:


Contents


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

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


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.

Tags clear by themselves when the order is ready, handed over or collected, and when the person leaves the team.


22. Release an order

Purpose: Drop your own tag (the owner: anyone's).

Endpoint: 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

Purpose: Name tags under the shop's messages ("— Jane"), shop side only. Customers never receive this.

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

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2026-11-17
Version: v1.0

Base URL: https://api.nexgate.co/api/v1

Short Description: Everything the shipper app needs for teams: a business owner builds the team, gives jobs to riders, links office computers, sets how calls ring and reads reports; a rider sees only the jobs given to them, goes on and off duty, and calls the buyer or the shop about a parcel. Read README.md first for roles, rights and terminals. The shipper app's offer and job calls are in docs/shipping/shipper_app_api_doc.md.

Hints:


Contents


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"

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 }
}

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

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2026-11-17
Version: v1.0

Base URL: https://api.nexgate.co/api/v1

Short Description: Everything the terminal app needs: the shared computer (Windows/Mac desktop, or a shop tablet) that sits at a shop counter or a shipping office. It links once to one shop or delivery business, shows the faces of the people who work there, signs a person in with their own PIN, and then reaches only the screens that computer is allowed: orders, products, chat and calls for a shop; offers, jobs, riders and calls for an office. Read README.md first for roles, rights and terminal permissions.

Hints:


Contents


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

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

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

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