Skip to main content

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:

  • Every call here uses the person's normal login: Authorization: Bearer <access token>.
  • Shop-owner screens use {kind} = shops and {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).


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