Skip to main content

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:

  • Every call uses the person's normal login: Authorization: Bearer <access token>.
  • Team paths use {kind} = businesses and {placeId} = the delivery business id.
  • A rider never sees money. Everything a rider receives has cost, commission, payout, payoutStatus = null.
  • A rider's phone is the rider's own, not the business's: it is linked to the shipper app without a business (app = SHIPPERS, no businessId). Rider rings reach it; the business's offer rings never do.
  • Shippers never get an order number or order id. Calls and jobs carry jobId and parcelNumber.
  • When the team feature is off, team endpoints answer 404: hide Team, Riders, Office, Reports.

Contents

  • Part 1 — How it works (flows)
  • Part 2 — Owner: the team (1–7)
  • Part 3 — Owner: riders and jobs (8–10)
  • Part 4 — Owner: office computers (11–16)
  • Part 5 — Owner: ring settings (17–20)
  • Part 6 — Activity and reports (21–23)
  • Part 7 — Rider: my teams, duty, my jobs (24–31)
  • Part 8 — Calls about a parcel (32–37)
  • Part 9 — Additions to existing responses
  • Part 10 — Pushes and notifications

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"
  • One call at a time per person: a rider already on a call → the caller hears BUSY, the rider gets a missed-call notice.
  • Nobody's own phone rings for their own call. If nobody else could answer, the call is refused (SAME_PERSON, OWN_BUSINESS, OWN_SHOP).

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.