Skip to main content

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:

  • 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 send Authorization: Bearer <member token>.
  • The PIN never leaves the computer. Send a pinProof derived 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