Shipper App — Team APIs
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}=businessesand{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, nobusinessId). Rider rings reach it; the business's offer rings never do. - Shippers never get an order number or order id. Calls and jobs carry
jobIdandparcelNumber. - 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 }
}
purpose LINK_TERMINAL → "Link this Windows computer to EMS Courier?" → 12.
12. Link the computer to the business
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.
No comments to display
No comments to display