Terminal App APIs
Base URL: https://api.nexgate.co/api/v1
Short Description: Everything the terminal app needs: the shared computer (Windows/Mac desktop, or a shop tablet)
that sits at a shop counter or a shipping office. It links once to one shop or delivery business, shows the faces of
the people who work there, signs a person in with their own PIN, and then reaches only the screens that computer
is allowed: orders, products, chat and calls for a shop; offers, jobs, riders and calls for an office. Read
README.md first for roles, rights and terminal permissions.
Hints:
- Two secrets live on the computer: the terminal key (forever, until the owner removes the computer) and a person's member session (10 minutes, refreshed). Keep the key in the OS credential vault (Windows Credential Manager, macOS Keychain), never in a file.
- Every call sends
X-Terminal-Key. A signed-in person's calls also sendAuthorization: Bearer <member token>. - The PIN never leaves the computer. Send a
pinProofderived from it (Part 1.4). - Anything not listed in this document answers 403. Don't call personal endpoints (profile, wallet, feed, personal chats); they are refused.
- Keep the live stream (Part 4) open all the time the app runs, also when nobody is signed in: alerts and calls arrive there. On Windows the app should live in the tray; warn before quitting ("Orders and calls won't reach this computer").
- When the team feature is off, every call answers 404 / 401.
Contents
- Part 1 — How it works (flows)
- Part 2 — Linking (1–2)
- Part 3 — On the computer: faces, adding people, signing in (3–12)
- Part 4 — The live stream (13)
- Part 5 — Shop counter: what a signed-in person may call
- Part 6 — Office (dispatch): what a signed-in person may call
- Part 7 — Calls on a terminal (14–19)
- Part 8 — Refusals and what to do
Part 1 — How it works
1.1 The life of a terminal
┌───────────────┐ owner approves ┌──────────────┐ someone taps a face ┌───────────────┐
│ NOT LINKED │ ───────────────────►│ LOCKED │ ────── + PIN ────────►│ SIGNED IN │
│ shows a code │ (terminal key │ faces screen │ │ Jane's screens│
│ every 30 s │ saved once) │ alerts ring │◄─── Lock / 2–3 min ───│ (her rights ∩ │
└───────────────┘ │ calls ring │ idle / 12 h │ this PC) │
▲ └──────────────┘ └───────────────┘
│ TERMINAL_REMOVED (owner removed it, or 401 on the key) → wipe everything, back to "not linked"
└────────────────────────────────────────────────────────────────────────────────────────────
1.2 Linking (once)
TERMINAL APP SERVER OWNER'S PHONE
POST /team/terminal-link/start ──────────────► { deviceCode, userCode: K7Q-4MX,
{ platform, appVersion } expiresIn: 30, interval: 2 }
show K7Q-4MX big + as a QR
every 2 s: POST /team/terminal-link/poll ────► authorization_pending
every 30 s: start again (new code) scans, approves, ticks what
◄──────────────────────────────────── the PC may do
POST /team/terminal-link/poll ───────────────► approved + terminalKey + settings
save terminalKey in the vault (shown once)
open the live stream, show the faces screen
1.3 Adding a person to this computer (once per person)
TERMINAL APP SERVER JANE'S PHONE (NexGate app)
"Add me" → POST /team/terminal/enrol/start ──► { deviceCode, userCode: P2D-8WK }
show the QR
poll POST /team/terminal/enrol/poll ─────────► authorization_pending scans, "Add yourself to
◄──────────────────────────────────── Counter PC?" → add-me
poll ────────────────────────────────────────► approved + person (Jane, photo)
"Hi Jane, choose a PIN" (twice)
POST /team/terminal/enrol/finish ────────────► Jane is on this computer
{ deviceCode, pinProof } + a member session (she's signed in)
Who can add themselves: an active member of this place. Shop: owner and staff. Office: owner and dispatchers. Riders never.
1.4 Signing in with face + PIN, and the PIN proof
faces screen → tap Jane → PIN pad → pinProof → POST /team/terminal/sessions { enrolmentId, pinProof }
├─ right → session (10 min token + refresh token)
├─ wrong → WRONG_PIN, details.triesLeft
├─ 5th → PIN_LOCKED 15 min (owner alerted)
└─ 10th → PIN_TOO_MANY: Jane must add herself again
pinProof: derived from the PIN on the computer, at least 32 characters, the same PIN always giving the same proof for that person on that computer. Recommended: PBKDF2-SHA256 of the PIN with a random per-person salt that the app creates at "Add me" and keeps in the vault, 100 000 rounds, base64. The server keeps only a keyed hash of the proof and counts every guess, so a stolen computer can't be used to guess PINs offline.
1.5 A session, minute by minute
10:00 sign in ────────► accessToken (expires 10:10), refreshToken R1, sessionEnds 22:00
10:09 refresh with R1 ─► new accessToken (10:19), R2 (R1 is now dead)
10:12 Jane taps Lock / 2–3 min idle ─► POST /team/terminal/sessions/lock → faces screen
any the owner removes or locks Jane, resets her PIN, or removes the PC ─► the next call answers 401
22:00 sessionEnds ─► sign in again
R1 used again after R2 exists ─► SIGN_IN_AGAIN (the session is ended: someone copied it)
1.6 Every request is checked
request ─► has X-Terminal-Key? ──no──► normal person rules (not this app)
│ yes
▼
key valid and computer not removed? ──no──► 401
│
├── no Bearer token ──► path in "terminal alone" list (Part 3)? ──no──► 403
│
└── member token ──► same computer? session open? person still active here? ──no──► 401
│ yes
▼
path in this computer's allow-list (Part 5 / 6)? ──no──► 403
person has the right it needs (their rights ∩ this PC)? ──no──► 403
?shopId / ?businessId = this computer's place (where required)? ──no──► 403
│ yes
▼
the endpoint runs, as this place only
Part 2 — Linking
1. Start linking
Purpose: A new computer asks for a short code to show.
Endpoint: POST {base_url}/team/terminal-link/start
Access Level: 🌐 Public (rate limited: 10 per minute per network address)
Authentication: None
Request JSON Sample:
{ "platform": "WINDOWS", "appVersion": "0.1.0" }
Request Body Parameters:
| Parameter | Type | Required | Description | Validation |
|---|---|---|---|---|
| platform | string | Yes | The computer's system | enum: WINDOWS, MAC, LINUX, ANDROID, IOS, WEB |
| appVersion | string | No | Terminal app version | max 30 |
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Show this code", "action_time": "2026-11-17T09:00:00",
"data": { "deviceCode": "kX9f…(secret)", "userCode": "K7Q-4MX", "expiresIn": 30, "interval": 2 }
}
Success Response Fields:
| Field | Description |
|---|---|
| deviceCode | Secret; keep it in memory to poll. Never show it |
| userCode | Show big and as a QR (encode just the code) |
| expiresIn | Seconds; ask for a new code when it runs out |
| interval | Poll every this many seconds |
Errors: PLATFORM (unknown platform), SLOW_DOWN (too many starts).
2. Poll for approval
Purpose: Ask whether the owner approved the code.
Endpoint: POST {base_url}/team/terminal-link/poll
Access Level: 🌐 Public
Request JSON Sample:
{ "deviceCode": "kX9f…" }
Success Response JSON Sample (approved):
{
"success": true, "httpStatus": "OK", "message": "Link status", "action_time": "2026-11-17T09:00:14",
"data": {
"status": "approved",
"terminalKey": "9b1c…e4.Qm9vb…",
"terminal": { "terminalId": "9b1c…e4", "label": "Counter PC", "placeKind": "SHOP", "placeId": "cfb6…",
"placeName": "My Shop With Banner", "job": "SHOP_COUNTER",
"permissions": ["HANDLE_ORDERS", "ORDER_ALERTS", "CUSTOMER_CHAT", "RECEIVE_CALLS"] }
}
}
Success Response Fields:
| Field | Description |
|---|---|
| status | authorization_pending (keep polling), slow_down (wait longer), expired_token (start again), approved |
| terminalKey | Shown once. Save in the vault; send as X-Terminal-Key from now on. Lost → link again |
| terminal.job | SHOP_COUNTER (Part 5) or DISPATCH (Part 6) |
| terminal.permissions | What the owner allowed (README) |
Part 3 — On the computer
Request headers for this part:
| Header | Type | Required | Description |
|---|---|---|---|
| X-Terminal-Key | string | Yes | The terminal key |
| Authorization | string | Only where marked "member" | Bearer <member accessToken> |
3. Who's working? (faces)
Endpoint: GET {base_url}/team/terminal/faces
Access Level: 🔒 Terminal key
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Who's working?", "action_time": "2026-11-17T09:01:00",
"data": [
{ "enrolmentId": "e1…", "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
"avatarUrl": "https://…", "signedIn": false, "pinLockedUntil": null }
]
}
Success Response Fields:
| Field | Description |
|---|---|
| enrolmentId | Send with the PIN proof (7) |
| signedIn | Signed in here now |
| pinLockedUntil | After 5 wrong PINs: grey the face until then |
Re-read on TERMINAL_FACES_CHANGED (13).
4. "Add me": start
Endpoint: POST {base_url}/team/terminal/enrol/start
Access Level: 🔒 Terminal key (10 per minute)
Success Response: message "Scan this with your phone", data = { deviceCode, userCode, expiresIn, interval } as in 1.
5. "Add me": poll
Endpoint: POST {base_url}/team/terminal/enrol/poll
Access Level: 🔒 Terminal key
Request JSON Sample: { "deviceCode": "…" }
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Add me status", "action_time": "2026-11-17T09:02:10",
"data": { "status": "approved",
"person": { "enrolmentId": null, "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
"avatarUrl": "https://…", "signedIn": false, "pinLockedUntil": null } }
}
status as in 2. On approved greet "Hi Jane" and ask for a new PIN twice.
6. "Add me": finish
Purpose: Save the person on this computer with their PIN proof, and sign them in.
Endpoint: POST {base_url}/team/terminal/enrol/finish
Access Level: 🔒 Terminal key
Request JSON Sample:
{ "deviceCode": "kX9f…", "pinProof": "q8Zk3m…(base64, ≥ 32 chars)" }
Request Body Parameters:
| Parameter | Type | Required | Description | Validation |
|---|---|---|---|---|
| deviceCode | string | Yes | From 4 | max 100 |
| pinProof | string | Yes | See 1.4 | 32–200 characters |
Success Response: message "You are on this computer", data = a session (as in 7).
Errors: NOT_ACTIVE_HERE (not an active member any more), ROLE_NOT_FOR_TERMINAL, CODE_USED.
7. Sign in (face + PIN)
Endpoint: POST {base_url}/team/terminal/sessions
Access Level: 🔒 Terminal key
Request JSON Sample:
{ "enrolmentId": "e1…", "pinProof": "q8Zk3m…" }
Request Body Parameters:
| Parameter | Type | Required | Description | Validation |
|---|---|---|---|---|
| enrolmentId | UUID | Yes | The tapped face | |
| pinProof | string | Yes | See 1.4 | 32–200 characters |
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Signed in", "action_time": "2026-11-17T10:00:00",
"data": {
"accessToken": "eyJ…", "expiresIn": 600, "refreshToken": "e1….Zm9v…", "sessionEnds": "2026-11-17T22:00:00",
"me": {
"person": { "enrolmentId": "e1…", "memberId": "b2…", "userName": "jane_k", "displayName": "Jane Kimaro",
"avatarUrl": "https://…", "signedIn": true, "pinLockedUntil": null },
"role": "STAFF", "shopRoleName": "Order staff",
"terminal": { "terminalId": "9b1c…", "label": "Counter PC", "placeKind": "SHOP", "placeId": "cfb6…",
"placeName": "My Shop With Banner", "job": "SHOP_COUNTER", "permissions": ["HANDLE_ORDERS", "ORDER_ALERTS"] },
"shopRights": ["SEE_ORDERS", "HANDLE_ORDERS"], "businessRights": []
}
}
}
Success Response Fields:
| Field | Description |
|---|---|
| accessToken | Member token: Authorization: Bearer … with X-Terminal-Key |
| expiresIn | Seconds (600). Refresh before (9) |
| refreshToken | One use only |
| sessionEnds | After this (12 hours), sign in again |
| me.shopRights / me.businessRights | What this person may do on this computer: hide every screen and button not covered. The server refuses them anyway |
Errors: WRONG_PIN (details.triesLeft), PIN_LOCKED (details.until), PIN_TOO_MANY, NOT_ACTIVE_HERE.
One session per person per computer: signing in again ends the previous one.
8. Lock
Endpoint: POST {base_url}/team/terminal/sessions/lock
Access Level: 🔒 Member (key + member token)
Success Response: message "Locked", data null. Drop the tokens; back to the faces screen. Do this on the Lock
button and after 2–3 minutes without use.
9. Refresh the session
Endpoint: POST {base_url}/team/terminal/sessions/refresh
Access Level: 🔒 Terminal key
Request JSON Sample: { "refreshToken": "e1….Zm9v…" } (max 200)
Success Response: message "Session refreshed", data = a new session (as in 7); the old refresh token is dead.
Errors: SIGN_IN_AGAIN (an old refresh token was used, or the 12 hours are over): back to faces.
10. Me on this computer
Endpoint: GET {base_url}/team/terminal/me
Access Level: 🔒 Member
Success Response: message "You on this terminal", data = me as in 7. Re-read on TERMINAL_SETTINGS_CHANGED.
11. This computer's settings
Endpoint: GET {base_url}/team/terminal/settings
Access Level: 🔒 Terminal key (also with a member token)
Success Response: message "This terminal", data = terminal as in 2. Show them read-only: "Set by the owner".
12. Heartbeat
Endpoint: POST {base_url}/team/terminal/heartbeat
Access Level: 🔒 Terminal key (also with a member token)
Request JSON Sample: { "appVersion": "0.1.0" } (optional body)
Success Response: message "Seen". Every few minutes; the live stream (13) also counts as seen.
Part 4 — The live stream
13. Open the live stream
Purpose: Everything that must reach the computer at once: settings changes, order alerts, offers, chat, calls.
Endpoint: GET {base_url}/team/terminal/stream (server-sent events, text/event-stream)
Access Level: 🔒 Terminal key only. Don't send the member token on the stream (it would be refused); keep the stream open while people sign in and out.
Keep it open while the app runs; reconnect with backoff (1 s, 2 s, 5 s, 10 s, then every 30 s). A comment : ping
comes every 20 seconds; no ping for 60 s → reconnect. While the stream is connected the computer counts as "open"
(it can be "somebody at the shop / office"); a closed stream counts as nobody.
Events for every terminal
| Event | Data | Do |
|---|---|---|
READY |
{} |
connected |
TERMINAL_SETTINGS_CHANGED |
{ terminalId } |
re-read 11 and 10 (rights may have changed) |
TERMINAL_FACES_CHANGED |
{} |
re-read 3; if the signed-in person is gone, back to faces |
TERMINAL_REMOVED |
{} |
wipe the key and all local data; back to "not linked" |
Shop counter events
| Event | Sent to computers ticked | Data | Do |
|---|---|---|---|
SHOP_NEW_ORDER |
Get order alerts | orderId, orderNumber, items, total |
pop up with sound, also when locked |
ORDER_ACCEPT_REMINDER |
Get order alerts | orderId, orderNumber, acceptBy |
pop up |
ORDER_CANCELLED, ORDER_DELIVERED |
Get order alerts | orderId, orderNumber |
notice |
RIDER_COMING |
Get order alerts | orderId, orderNumber, shipperName, check |
"EMS Courier is coming: check …" |
PARCEL_REFUSED |
Get order alerts | orderId, orderNumber, shipperName |
notice |
ORDER_CHANGED |
all | orderId, status |
re-read the order list |
message.created, message.updated, unread.changed, conversation.created, conversation.updated |
Customer chat | same as the app's chat events | update the inbox |
shop.typing |
Customer chat | conversationId, shopId, accountId, name, untilMs |
"Jane is replying…" until untilMs |
call.incoming |
Receive calls | see Part 7 (no token) | ring, also when locked |
call.updated, call.ended |
Receive calls | callId, outcome, answeredBy |
stop ringing / update |
SHOP_CALL_ANSWERED |
all | callId, name, accountId |
"Answered by Jane": stop ringing |
Office events
| Event | Sent to computers ticked | Data | Do |
|---|---|---|---|
JOB_OFFER, JOB_OFFER_REMINDER |
Get offers | offerId, jobId, businessId, businessName, from/to area and landmarks, answerBy, expiresAtMs, serverNowMs, valueBand, roadKm, cost |
ring, also when locked (show faces of people who may accept) |
JOB_OFFER_CLOSED |
Get offers | offerId, jobId, status |
stop ringing |
SHIPPER_CHANGED |
all | businessId |
re-read lists |
call.incoming |
Receive calls | see Part 7 (no token) | ring, also when locked |
call.updated, call.ended |
all | callId, outcome, answeredBy, work |
stop ringing / update |
Part 5 — Shop counter: what a signed-in person may call
Every call below sends both headers. The request and response are exactly the same as in the NexGate app for the
owner; only the rules differ. "Needs" = the right the person must have on this computer (me.shopRights).
?shopId= marked ✅ = required, and must be this computer's shop.
Orders
| Method | Path | Needs | ?shopId= |
|---|---|---|---|
| GET | /e-commerce/orders/shop/{shopId}/orders (+ /paged, /status/{status}, /status/{status}/paged) |
SEE_ORDERS |
in the path |
| GET | /e-commerce/orders/{orderId}, /e-commerce/orders/number/{orderNumber} |
SEE_ORDERS |
— |
| POST | /shipping/orders/{orderId}/accept, /ready, /hand-over, /hand-over-rider, /collect |
HANDLE_ORDERS |
— |
| GET | /team/shops/{shopId}/orders/tags, /team/shops/{shopId}/orders/{orderId}/steps |
SEE_ORDERS |
in the path |
| POST | /team/shops/{shopId}/orders/{orderId}/take, /release |
HANDLE_ORDERS |
in the path |
- Accepting signs the order as the shop; who pressed it is in the steps.
- Never: cancelling, pickup time and pickup codes (the buyer's), refunds. A person's own purchases never open here.
Products and stock
| Method | Path | Needs |
|---|---|---|
| GET | /e-commerce/shops/{shopId}/products/my-shop-all (+ -paged), /{productId}/detailed |
PRODUCTS or STOCK |
| POST | /e-commerce/shops/{shopId}/products |
PRODUCTS |
| PUT | /e-commerce/shops/{shopId}/products/{productId} |
PRODUCTS (details) and/or STOCK (quantities) |
| PATCH | /e-commerce/shops/{shopId}/products/{productId}/publish |
PRODUCTS |
| POST | /files/request-upload, /files/thumbnail/{fileId} |
PRODUCTS (contexts PRODUCT_IMAGE, PRODUCT_VIDEO, PRODUCT_PREVIEW_*) or CUSTOMER_CHAT (DM_IMAGE, DM_VIDEO, DM_DOCUMENT) |
Staff edits a product
├── name, photos, description, category, colours, limits ── needs PRODUCTS ── saved
├── stock, low-stock level, show stock ──────────────────── needs STOCK ───── saved
└── price, compare price, group buying, instalments ─────── 409 PRICE_OWNER_ONLY (sending the current value is fine)
Staff adds a product ─► saved as a DRAFT, whatever "action" said ─► the owner checks the price and publishes it
Other codes: NO_PRODUCTS_RIGHT, NO_STOCK_RIGHT, OWNER_PUBLISHES, DIGITAL_OWNER_ONLY. Never: delete/restore,
digital products.
Chat (as the shop)
| Method | Path | Needs | ?shopId= |
|---|---|---|---|
| GET | /chat/conversations, /chat/conversations/archived/unread |
CUSTOMER_CHAT |
✅ |
| GET POST | /chat/conversations/{conversationId}/messages |
CUSTOMER_CHAT |
✅ |
| DELETE | /chat/conversations/{conversationId}/messages/{messageId} |
CUSTOMER_CHAT (own messages only: OWN_MESSAGES_ONLY) |
✅ |
| POST | /chat/conversations/{conversationId}/read |
CUSTOMER_CHAT |
✅ |
| PUT | /chat/conversations/{conversationId}/archive, /pin, /pinned-message |
CUSTOMER_CHAT |
✅ |
| DELETE | /chat/conversations/{conversationId}/pinned-message |
CUSTOMER_CHAT |
✅ |
| GET | /chat/sync |
CUSTOMER_CHAT |
✅ |
| POST | /chat/offers |
PRICE_OFFERS |
— |
| GET | /chat/offers/{offerId} |
CUSTOMER_CHAT |
— |
| POST | /chat/offers/{offerId}/cancel |
PRICE_OFFERS |
— |
| GET | /team/shops/{shopId}/chat/conversations/{conversationId}/senders |
CUSTOMER_CHAT |
in the path |
| POST | /team/shops/{shopId}/chat/conversations/{conversationId}/typing |
CUSTOMER_CHAT |
in the path |
- Without
?shopId=the chat endpoints would mean the person's own chats, so the server answers 403. - Never: mute, delete a conversation, disappearing messages, secret or personal chats,
/chat/contexts/me,/events. - Name tags: show "— Jane" under the shop's messages using
senders. Customers never see them.
Calls
See Part 7. Allowed for ANSWER_CALLS: POST /calls (body shopId), POST /calls/{callId}/join|end,
GET /calls/{callId}, GET /calls (all with ?shopId= ✅), GET /team/shops/{shopId}/calls/missed, and every
/work-calls path with ?shopId= ✅ (start carries shopId in its body).
Part 6 — Office (dispatch): what a signed-in person may call
Same rules as Part 5, with me.businessRights. ?businessId= ✅ = required, and must be this computer's business.
| Method | Path | Needs | Notes |
|---|---|---|---|
| GET | /shipping/businesses/{businessId}/offers, /upcoming, /jobs |
VIEW_JOBS |
always on an office PC |
| GET | /shipping/jobs/{jobId} |
VIEW_JOBS |
a dispatcher sees prices; never earnings |
| POST | /shipping/offers/{offerId}/accept, /reject, /received |
ANSWER_OFFERS |
first tap wins (the owner's phone may also accept) |
| GET | /shipping/businesses/{businessId}/riders |
ASSIGN_JOBS |
shipper app doc §8 |
| POST | /shipping/jobs/{jobId}/assign, /unassign |
ASSIGN_JOBS |
shipper app doc §9–10 |
| POST | /work-calls |
ANSWER_CALLS |
body businessId |
| POST | /work-calls/{callId}/join, /end |
ANSWER_CALLS |
?businessId= ✅ |
| GET | /work-calls/{callId}, /work-calls, /work-calls/waiting |
ANSWER_CALLS |
?businessId= ✅ |
Never from an office PC: earnings, reports, setup, pause, phones, team, reviews, documents, "my assigned jobs", wallet. Who accepted or rejected each offer is in the activity log.
Offer rings on the office PC (locked, faces shown)
→ Peter taps his face + PIN → offer list → Accept
→ POST /shipping/offers/{id}/accept (first tap wins; the owner's phone gets the usual "already taken")
→ GET …/riders → Mama Yoyo (on duty, phone can ring) → POST /shipping/jobs/{jobId}/assign
Part 7 — Calls on a terminal
A shop or office with computers works like a small call centre.
Call to the shop / office
│
▼
every open computer ticked "Receive calls" gets call.incoming (no token)
├── locked: ring + show the faces of people who may answer
├── signed in, free: ring
└── already on a call: don't ring loudly; add it to the waiting list (18)
│
▼
someone answers (14/15) ──► first wins ──► everyone else: SHOP_CALL_ANSWERED / call.updated → stop ringing
nobody in 45 s ──► call.ended (MISSED) ──► missed list (shop chat calls: missed endpoint; parcel calls: 17)
every computer busy ──► the owner's phone rings per her setting; the caller is told "everyone is on another call"
call.incoming data: callId, kind (AUDIO), roomName, url, ringSeconds, callerJid, callerName,
callerAvatar, answerAs (SHOP / BUSINESS), shopId or businessId, and for a call about a parcel: work: "true",
callerRole, businessName, businessLogo, parcelNumber, plus orderNumber + orderId (shop) or jobId (office).
A shop chat call carries conversationId instead of work.
14. Answer a customer's call (shop chat call)
Endpoint: POST {base_url}/calls/{callId}/join?shopId={shopId}
Access Level: 🔒 Member with ANSWER_CALLS
Success Response JSON Sample:
{ "success": true, "httpStatus": "OK", "message": "Joined", "action_time": "2026-11-17T10:30:50",
"data": { "callId": "k-90…", "roomName": "call_k-90…", "token": "eyJ…", "url": "wss://livekit…", "kind": "AUDIO", "state": "RINGING" } }
Errors: ANSWERED_ELSEWHERE ("Answered by Jane"), CALL_ENDED.
15. Answer a call about a parcel
Endpoint: POST {base_url}/work-calls/{callId}/join?shopId={shopId} (shop) or ?businessId={businessId} (office)
Access Level: 🔒 Member with ANSWER_CALLS
Success Response: as in 14. Join the LiveKit room with token (microphone only).
Errors: ANSWERED_ELSEWHERE, CALL_ENDED, NOT_ON_THIS_CALL.
16. Call the delivery (shop) / the buyer or shop (office)
Endpoint: POST {base_url}/work-calls
Access Level: 🔒 Member with ANSWER_CALLS
Request JSON Sample (shop computer):
{ "orderId": "0f05…", "to": "DELIVERY", "shopId": "cfb6…" }
Request JSON Sample (office computer):
{ "jobId": "0003…", "to": "BUYER", "businessId": "2a19…" }
Success Response: { call, calling, allLinesBusy } as in the NexGate app doc §34.
Errors: ACT_AS_PLACE (no shopId/businessId: a computer always calls as its place), CALLS_CLOSED,
NO_SHIPPER_YET, BUSY, NOT_YOUR_SHOP, NOT_YOUR_BUSINESS.
17. Hang up / call list / one call
- POST
{base_url}/work-calls/{callId}/end?shopId=|businessId= - GET
{base_url}/work-calls?shopId=|businessId=&limit=30— history rows (other,missed,callBack) - GET
{base_url}/work-calls/{callId}?shopId=|businessId= - Shop chat calls: POST
/calls/{callId}/end?shopId=, GET/calls?shopId=, GET/team/shops/{shopId}/calls/missed
18. The waiting queue
Purpose: Calls still ringing at this place, oldest first, so a free person can take the longest-waiting one.
Endpoint: GET {base_url}/work-calls/waiting?shopId={shopId} (or ?businessId=)
Access Level: 🔒 Member with ANSWER_CALLS
Success Response JSON Sample:
{
"success": true, "httpStatus": "OK", "message": "Waiting calls", "action_time": "2026-11-17T10:30:45",
"data": [
{ "callId": "k-90…", "work": false, "conversationId": "c-12…", "since": "2026-11-17T10:30:10+03:00", "waitedSeconds": 35,
"caller": { "role": "BUYER", "name": "Amina", "photo": "https://…" } },
{ "callId": "6fb1…", "work": true, "since": "2026-11-17T10:30:30+03:00", "waitedSeconds": 15,
"caller": { "role": "RIDER", "name": "Mama Yoyo", "businessName": "EMS Courier", "orderNumber": "ORD-2026-23424",
"parcelNumber": "NX-SQAW-ZL", "orderId": "0f05…" } }
]
}
Answer work: false with 14 and work: true with 15. Re-read on every call.* event.
19. Call a customer back (shop)
Endpoint: POST {base_url}/calls with { "conversationId": "…", "kind": "AUDIO", "shopId": "…" }
Access Level: 🔒 Member with ANSWER_CALLS
Only inside the customer's 24-hour window (the existing chat rule). A personal call (no shopId) is refused.
Part 8 — Refusals and what to do
| Answer | Meaning | Do |
|---|---|---|
401 on any call with only the key |
the computer was removed | wipe, back to "not linked" |
401 with a member token |
the session ended (locked by the owner, removed, PIN reset, 12 h over) | back to faces |
403 |
the path isn't allowed on this computer, or the person lacks the right, or ?shopId/?businessId missing or wrong |
hide that action; never retry |
409 WRONG_PIN |
details.triesLeft |
"Wrong PIN, 3 tries left" |
409 PIN_LOCKED |
details.until |
grey the face until then |
409 PIN_TOO_MANY |
10 wrong | "Ask the owner, then add yourself again" |
409 SIGN_IN_AGAIN |
refresh token reused or session over | back to faces |
409 ANSWERED_ELSEWHERE |
someone else took the call | stop ringing, show who |
409 ORDER_TAKEN |
someone else is packing it | show who |
409 PRICE_OWNER_ONLY, OWNER_PUBLISHES |
prices and publishing staff products are the owner's | hide those fields / buttons |
No comments to display
No comments to display