{ "openapi": "3.0.0", "info": { "title": "Kapitano — Captain App API", "description": "The Kapitano Logistic **captain app API** (`/api/driver/*`) used by the mobile app:\nself-registration, OTP sign in, profile, presence (availability + location),\ndocuments and push-device registration.\n\n**Required headers.** Every `api/*` route passes `CheckApiHeaderMiddleware` first:\n\n- `Accept: application/json` — anything else answers `401`.\n- `Accept-Language: en` (or `ar`) — missing answers `401`; accepted values are the\n `app.supported_locales` list, anything else falls back to the fallback locale.\n\n**Authentication.** Every captain endpoint takes the `driverAuth` bearer token\nissued by `POST /api/driver/auth/verify` (a Laravel Sanctum token).\n\n**Response envelope.** Every endpoint answers the same shape:\n`{ \"Model\", \"Status\", \"Message\", \"MessageDebug\", \"Total\", \"Page\", \"Records\" }`.\nOn paginated lists `Total` is the number of pages, `Page` the current one and\n`Records` the total record count.\n\n---\n\n## The delivery flow\n\nAn assignment is an **offer**, not an instruction. The captain answers it, and only then\ndoes the delivery begin.\n\n```\n (dispatch assigns)\n |\n v\npending ---------> assigned ------- accept ------> accepted\n ^ | |\n | | |\n +---- decline -------+---------- decline -----------+\n | |\n +---- offer expires -+ |\n picked-up\n |\n v\n on-the-way\n |\n +------------+------------+\n v v\n delivered delivery-failed\n```\n\n| Step | Call |\n|---|---|\n| Take the offer | `POST /api/driver/orders/{uuid}/accept` |\n| Turn it down | `POST /api/driver/orders/{uuid}/decline` |\n| Collect **one supplier** | `PATCH /api/driver/orders/{uuid}/pickups/{pickup}/collected` |\n| Collect everything at once | `PATCH /api/driver/orders/{uuid}/picked-up` |\n| Set off | `PATCH /api/driver/orders/{uuid}/on-the-way` |\n| Complete it | `POST /api/driver/orders/{uuid}/delivered` *(photo)* or `PATCH` *(note only)* |\n| Give up on it | `PATCH /api/driver/orders/{uuid}/failed` |\n\nThe two collection routes answer the same question at different grain — see\n**Collecting from several suppliers** below for which to build on.\n\n### The app MUST call `accept`\n\n**`assigned → picked_up` is not a legal transition.** A captain cannot collect a parcel for\nan order they have not accepted, and `picked-up` answers **422** if they try. An app build\nthat skips the accept step cannot complete a single delivery.\n\nRead `next_statuses` rather than hard-coding the sequence: an offered order answers\n`[\"accepted\"]`, and that is the only forward button to draw.\n\n### …except when the order arrives already accepted\n\nOperations may **direct** an employee captain rather than offer to them: the order is\nassigned and accepted in one move, so it reaches the app as `accepted` with\n`offer_expires_at: null` and nothing to answer.\n\nThis is why the sequence must not be hard-coded. An app that draws an *Accept* button\nwhenever an order is new will show a dead button on every directed order, and one that\ndemands `accept` before enabling the pickup will strand the captain entirely.\n`next_statuses` already answers `[\"picked_up\"]` on these — draw that.\n\nIt never happens to a freelance captain: their arrangement is that they may refuse, so\nthe endpoint that directs a captain answers 422 for them.\n\n### The countdown\n\nAn offered order carries `offer_expires_at`. If the captain has not answered by then, the\noffer is taken back, the order returns to `pending` for somebody else, and the captain's\ncapacity is freed. The window is 60 seconds by default.\n\nTiming out is recorded exactly as a decline, flagged as having expired rather than been\nrefused — refusing is a choice, never answering may be a flat battery.\n\n### Declining\n\nAllowed from `assigned` **and** from `accepted`, so a captain whose car will not start after\naccepting has a way out that is not a failed delivery. A `reason` may be sent and is\noptional.\n\nThe order returns to the pool, and **this captain is excluded from that order's next\nsuggestion list** — the ranking that put them first would otherwise hand it straight back.\nThe exclusion is per order; it never follows the captain to anything else.\n\nAfter the pickup there is no way back: use `failed`, which requires a reason.\n\n### What a captain may never do\n\n**Cancel.** Ending an order is the store's or the back office's decision. A captain can\nalways get out of an order — by declining before the pickup, or by failing it after — but\nthe order goes back to the pool rather than dying in their hands.\n\nA cancellation reaches the captain as a push (`type: order_cancelled`) whenever one of\ntheir orders is ended under them, with the reason attached. It is the only status change\nthat is pushed, because it is the only one the captain did not cause.\n\n---\n\n## Collecting from several suppliers\n\nAn order may gather its goods from up to three shops. `pickups[]` lists them in visiting\norder, each carrying the `uuid` the per-stop route is addressed to.\n\n```\npickups[0] confirmed -> order stays `accepted`, stop leaves the route plan\npickups[1] confirmed -> order stays `accepted`\npickups[2] confirmed -> nothing outstanding, so the order becomes `picked_up`\n```\n\nThe last stop rolls everything up: the order's `items_collected` and `amount_paid` become\nthe sums of the stops, `items_mismatch` is set if any stop was short *or* the totals do not\nagree, and the status moves on its own. There is no separate call to finish.\n\n**Build on the per-stop route, not on `picked-up`.** Every order has at least one stop —\nwhere a store sent none, one is made from the pickup address — so looping `pickups[]`\nworks for a single-supplier order exactly as it does for three, and the app needs one code\npath rather than two. `PATCH /picked-up` stays exactly as it was for older builds: it means\n\"collect everything still outstanding and go\".\n\nThree behaviours worth knowing before writing the screen:\n\n- **Confirming the same stop twice answers 422.** After a timed-out request, re-read the\n order and check `pickups[].collected` before retrying, or the captain sees an error for\n work that landed.\n- **`amount_paid: 0` is a real answer**, not a missing one. It records the stop and writes\n no ledger entry — plenty of suppliers are settled by the office, and a captain with\n nothing to pay should not have to leave the field blank to get past the screen.\n- **`pickups[].items` is empty unless the store said which supplier each line comes from**,\n which is still the common case. Fall back to the order's own `items` when it is, rather\n than showing a captain an empty counter.\n\n---\n\n## Wrapped orders: one parcel, two journeys\n\nSome orders pass through a wrapping shop on their way to the customer. Those are **two\norders**, not one order with an extra stop, because a different captain drives each half\nand the first is released the moment they drop the goods off.\n\n```\ncollection leg ORD-000482-C suppliers -> wrapping shop captain A\ndelivery leg ORD-000482 wrapping shop -> customer captain B\n```\n\nEach half reaches a captain as an ordinary order with the ordinary lifecycle — accept,\ncollect, on the way, delivered. **Nothing new to implement in the flow.** What the app must\nread is `leg`:\n\n| `leg` | What it is |\n|---|---|\n| `null` | An ordinary order, straight to the customer. **Nearly all of them.** |\n| `delivery` | The customer half of a wrapped order. Behaves like an ordinary one. |\n| `collection` | The internal half: buy from the suppliers, drop at the wrapping shop. |\n\n**A collection leg has no customer and takes no money.** Its `customer_name` holds the\n*wrapping shop's* name and its `amount_to_collect` is null — so an app that does not read\n`leg` will show the shop as though it were a person waiting at home, and may offer a\n\"collect cash\" screen for money nobody owes.\n\nDo not try to infer this from anything else. `amount_to_collect` is null on a genuinely\nprepaid customer delivery too, and `customer_phone` can be empty on either. `leg` is the\nonly field that answers it.\n\n**There is no \"awaiting wrapping\" status.** The delivery leg simply stays `pending` and\ncannot be assigned until its collection leg reports `delivered`; the block is worked out at\nthe moment of assignment rather than stored. The captain-facing status list is unchanged,\nand a captain never sees a blocked delivery leg — it has not been given to anyone.\n\n---\n\n## Money: paying, collecting, handing over\n\nA captain often pays the supplier out of their own pocket, and the captain who delivers and\ntakes the cash is often somebody else. Every one of those movements is recorded, and the\ncompany sits in the middle: captains never owe each other.\n\n| When | Send | Recorded as |\n|---|---|---|\n| Paying at the supplier | `amount_paid` on `PATCH …/picked-up` | the company owes this captain |\n| Taking cash from the customer | `amount_collected` on `…/delivered` | this captain owes the company |\n| At the cash desk | *(back office)* | clears the balance |\n\n**Pre-fill, don't ask blind.** The order carries `expected_goods_cost` (the sum of its lines)\nand `amount_to_collect`. Show them and let the captain confirm or correct: they are\nreimbursed for what they **actually** paid, and a difference is recorded as a variance rather\nthan refused. Both fields are optional; `0` or leaving one out records nothing.\n\n### Handing an order to another captain\n\n```\ncaptain A (carrying) captain B (receiving)\nPOST /orders/{uuid}/handover ────────► GET /handovers (their inbox)\n { to_captain_uuid } POST …/handover/accept ← order becomes B's\nDELETE /orders/{uuid}/handover POST …/handover/decline ← order stays with A\n (withdraw, before B answers)\n```\n\n- Only from `picked_up` or `on_the_way` — before that, a captain who cannot take the order\n **declines** it instead. The status never changes during a handover.\n- B must accept. Nothing moves until then, and B is refused with **409** if they have no room.\n- **The money does not move with the parcel.** A captain who paid the supplier stays owed\n that amount whoever delivers; the one who collects owes what they collected.\n\n### A captain's own balance\n\n`GET /api/driver/ledger` — the same figures the cash desk sees, per currency, with every\nmovement behind them. Positive means the company owes the captain.", "version": "1.0.0" }, "servers": [ { "url": "https://captain.kapitano.shop", "description": "Production API" }, { "url": "http://127.0.0.1:8000", "description": "Local — php artisan serve" }, { "url": "http://localhost/kapitano_logistic", "description": "Local — XAMPP (htdocs)" } ], "paths": { "/api/driver/auth/register": { "post": { "tags": [ "Captain App — Authentication" ], "summary": "Submit a captain application", "description": "Self-registration from the captain app. The account stays `pending` until the back\noffice decides. Multipart: the JSON fields plus the license photo, the profile photo\nand — for personal vehicles — the vehicle images. A phone/email/national-id already\nregistered answers 422.\n\nSend `fcm_token` if the app has one: it is the only opportunity to register the handset\nbefore the review, and the decision push is sent in the language of this request's\n`Accept-Language`.", "operationId": "driverRegister", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "name": { "type": "string", "example": "Abdulaziz Al Ajlan", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500000008" }, "email": { "type": "string", "format": "email", "example": "aziz.free@example.com", "nullable": true }, "national_id": { "type": "string", "example": "1000000008", "maxLength": 50 }, "date_of_birth": { "description": "Must be before today.", "type": "string", "format": "date", "example": "1991-11-28" }, "employment_type": { "type": "string", "example": "freelance", "enum": [ "employee", "freelance" ] }, "driving_license_number": { "type": "string", "example": "DL-10008", "maxLength": 50 }, "driving_license_expires_at": { "description": "Must be after today.", "type": "string", "format": "date", "example": "2029-09-12" }, "driving_license": { "description": "jpg/jpeg/png/pdf, max 5120KB", "type": "string", "format": "binary" }, "profile_photo": { "description": "jpg/jpeg/png, max 5120KB", "type": "string", "format": "binary" }, "fcm_token": { "description": "Optional, and strongly recommended: the handset's push token. A pending applicant cannot sign in, so this is the only chance to register the device before the review — send it and the approval, rejection or documents-required decision is pushed to this phone. One token belongs to one captain: a token another account registered moves to this one.", "type": "string", "example": "dQXWaxgOS-iU6USjwwObiV:APA91bE...", "nullable": true, "maxLength": 512 }, "device_id": { "description": "Optional handset identifier stored next to the token.", "type": "string", "example": "a1b2c3d4e5f6", "nullable": true, "maxLength": 255 }, "vehicle": { "description": "Vehicle block; when ownership_type is personal, its fields are required.", "properties": { "ownership_type": { "type": "string", "example": "personal", "enum": [ "company_owned", "personal" ] }, "plate_number": { "type": "string", "example": "AZZ-8008", "maxLength": 20 }, "brand": { "type": "string", "example": "GMC", "maxLength": 100 }, "model": { "type": "string", "example": "Terrain", "maxLength": 100 }, "manufacture_year": { "type": "integer", "example": 2021, "maximum": 2027, "minimum": 1950 }, "color": { "type": "string", "example": "red", "maxLength": 50 }, "vehicle_image": { "type": "string", "format": "binary" }, "mechanics_image": { "type": "string", "format": "binary" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Application submitted, status pending.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Driver" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Registered successfully" } }, "type": "object" } } } }, "401": { "description": "Required headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Validation failed (e.g. duplicate phone/email/national id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } }, "429": { "description": "Too many requests (api throttle).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/driver/auth/login": { "post": { "tags": [ "Captain App — Authentication" ], "summary": "Request an OTP code", "description": "Sends a numeric code (default length 6, expires after 15 minutes) to the phone.\n\nWho may sign in:\n- `approved` — the working captain.\n- `documents_required` — management sent the application back; the captain signs in\n only to re-upload the documents (`POST /api/driver/documents`). They cannot go online\n or be given orders until approved (`can_receive_orders` is `false`).\n\nAnything else answers 404 (not registered), 423 (`pending`, still under review) or 403\n(rejected or disabled), with the reason in `MessageDebug.reason`.\nThrottle `otp`: 4 requests per minute per phone **and** per IP.", "operationId": "driverLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500000008" } }, "type": "object" }, "example": { "phone": "+966500000008" } } } }, "responses": { "200": { "description": "Code sent.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "null" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "We have sent your verification code!" } }, "type": "object" } } } }, "401": { "description": "Required headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Phone not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "423": { "description": "Application still under review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorLocked" } } } }, "403": { "description": "Rejected or disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "429": { "description": "OTP throttle (4/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/driver/auth/resend": { "post": { "tags": [ "Captain App — Authentication" ], "summary": "Resend the OTP code", "description": "Replaces the previous code for the phone and sends it again. Same account checks and throttle as login.", "operationId": "driverResendOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500000008" } }, "type": "object" }, "example": { "phone": "+966500000008" } } } }, "responses": { "200": { "description": "New code sent." }, "401": { "description": "Required headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Phone not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "423": { "description": "Application still under review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorLocked" } } } }, "403": { "description": "Rejected or disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "429": { "description": "OTP throttle (4/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/driver/auth/verify": { "post": { "tags": [ "Captain App — Authentication" ], "summary": "Verify the OTP and receive a bearer token", "description": "Exchanges a valid code for a Sanctum token plus the driver record. A mismatched,\nexpired or exhausted code answers 422 on the `code` field. Codes are single use,\nstored hashed, expire after 15 minutes and are invalidated after the configured\nwrong-try limit (default 5).", "operationId": "driverVerifyOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500000008" }, "code": { "description": "Numeric code of the configured OTP length (6).", "type": "string", "pattern": "^[0-9]{6}$", "example": "257843" }, "device_name": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" }, "example": { "phone": "+966500000008", "code": "257843" } } } }, "responses": { "200": { "description": "Token issued.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/DriverAuthResult" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Verification code verified!" } }, "type": "object" } } } }, "401": { "description": "Required headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "Phone not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "423": { "description": "Application still under review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorLocked" } } } }, "403": { "description": "Rejected or disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Code wrong, expired or exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } }, "429": { "description": "OTP throttle (4/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/driver/auth/logout": { "post": { "tags": [ "Captain App — Authentication" ], "summary": "Sign out", "description": "Revokes every Sanctum token the signed in captain holds.", "operationId": "driverLogout", "responses": { "200": { "description": "Signed out.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "null" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Logged out successfully" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/ledger/hand-in": { "get": { "tags": [ "Captain App — Ledger" ], "summary": "The declaration still waiting, and the ones before it", "description": "`Pending` is the declaration the desk has not answered yet, or null. `Model` is the captain's\nown history of hand-ins, newest first — including the ones the desk turned away and why.", "operationId": "driverReadCashHandIns", "parameters": [ { "name": "rows", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 10 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 } } ], "responses": { "200": { "description": "The pending declaration and the history.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CashHandIn" } }, "Pending": { "oneOf": [ { "$ref": "#/components/schemas/CashHandIn" } ], "nullable": true }, "Status": { "type": "boolean", "example": true }, "Records": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] }, "post": { "tags": [ "Captain App — Ledger" ], "summary": "Declare that you are bringing the cash in", "description": "**This clears nothing by itself.** It puts the captain on the desk's queue with the amount\nthey are bringing; their balance falls to zero when somebody counts the notes and confirms.\nA button that could zero a balance would have the books saying the company held cash nobody\nhad received.\n\nWith no `amount` the captain is declaring **everything they owe** in that currency, which is\nwhat \"settle up\" means on their screen. An explicit amount is allowed for a part payment, but\nnever more than they owe — cash they are not holding is not theirs to hand over.\n\nPressing twice does not create a second row: the declaration already waiting comes back, so\nthe desk never sees one captain twice for the same money.\n\n`422` when the captain is owed money or is square — there is nothing to hand in.", "operationId": "driverDeclareCashHandIn", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "amount": { "description": "Leave it out to hand in everything owed.", "type": "number", "format": "float", "example": 380, "nullable": true }, "currency": { "type": "string", "example": "SYP", "nullable": true }, "note": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "The declaration. The balance is unchanged.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CashHandIn" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Nothing to hand in, or more than the captain owes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/ledger/hand-in/{uuid}": { "delete": { "tags": [ "Captain App — Ledger" ], "summary": "Call the declaration off", "description": "Before the desk has answered it, and the captain's own only. A confirmed hand-in is money that\nhas changed hands and nothing on a phone may undo that.\n\nSomebody else's declaration answers `404`, not `403`: a captain must not learn that another\ncaptain's hand-in exists.", "operationId": "driverCancelCashHandIn", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Called off. The balance is unchanged.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CashHandIn" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "No such declaration of theirs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "The desk has already answered it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/device-token": { "post": { "tags": [ "Captain App — Device Token" ], "summary": "Register the push device token", "description": "Registers (or updates) the FCM token for the signed in captain so order notifications can reach them.", "operationId": "driverRegisterDeviceToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "fcm_token": { "type": "string", "example": "fcm-token-...", "maxLength": 512 }, "device_id": { "type": "string", "example": "device-uuid-...", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Token registered.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "fcm_token": { "type": "string" } }, "type": "object" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] }, "delete": { "tags": [ "Captain App — Device Token" ], "summary": "Forget a push device token", "description": "Removes the token by fcm_token and/or device_id. Typically called on logout. Either fcm_token or device_id must be present.", "operationId": "driverUnregisterDeviceToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "fcm_token": { "type": "string", "nullable": true, "maxLength": 512 }, "device_id": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Token forgotten.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "null" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Device token removed" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/documents": { "post": { "tags": [ "Captain App — Documents" ], "summary": "Re-upload documents after management asked for them", "description": "When management reviews a captain's application and needs a clearer or missing document,\nit sends the application back instead of rejecting it. This endpoint is how the captain\nanswers from the app.\n\n**The journey**\n\n1. Management sends the application back\n (`PATCH /api/dashboard/drivers/{uuid}/request-documents` with a `review_note`). The\n status becomes `documents_required` and the captain is pushed a notification with\n `data.type = driver_application_reviewed` and `data.status = documents_required`.\n2. The captain signs in as usual — `POST /api/driver/auth/login`, then\n `POST /api/driver/auth/verify`. A `documents_required` account **may** sign in for\n exactly this purpose; a `pending` one still answers 423.\n3. The app shows the captain `review_note` (from the verify response or\n `GET /api/driver/profile`): it says what management needs.\n4. The captain uploads the replacement here.\n5. Management is notified in the back office inbox, reviews the file again, and approves,\n rejects, or asks for documents once more.\n\n**What the upload does**\n\n- Send `multipart/form-data` with one or both files. Only the files sent are replaced:\n a captain asked only for the license can leave the photo alone.\n- Each file **replaces** the previous version — it is not added next to it.\n- The status **stays** `documents_required` until management decides. Uploading again\n before then is allowed and replaces the files again.\n- A sent-back captain is signed in but **not working**: `can_receive_orders` is `false`,\n going online answers 403, and no order can be assigned to them until they are approved.\n\n**Headers**: `Accept: application/json` and `Accept-Language` (`en` or `ar`) are required\non every request; `Message` and the `*_label` fields follow the language.\n\n| Status | When |\n|---|---|\n| 200 | Files replaced; answers the captain's full profile. |\n| 401 | Token missing or revoked, or a required header missing. |\n| 422 | No file, a file of the wrong type or over 5 MB, or the account is not in `documents_required`. |\n| 429 | Too many requests (API throttle). |", "operationId": "driverDocumentsResubmit", "parameters": [ { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" } }, { "name": "Accept-Language", "in": "header", "required": true, "schema": { "type": "string", "example": "en", "enum": [ "en", "ar" ] } } ], "requestBody": { "description": "At least one of the two files. Send only what management asked for.", "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "driving_license": { "description": "The driving license. jpg, jpeg, png or pdf; at most 5120 KB. Required when `profile_photo` is not sent.", "type": "string", "format": "binary" }, "profile_photo": { "description": "The captain's photo. An image: jpg, jpeg or png; at most 5120 KB. Required when `driving_license` is not sent.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Documents replaced. The status stays `documents_required` until management decides.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Driver" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Your documents have been updated and are back under review." }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "examples": { "both documents replaced": { "summary": "Both files sent: both links point at the new uploads.", "value": { "Model": { "uuid": "01m2r22qwbs3te5cbf3vy7ehb3", "name": "Sami Salem", "phone": "+966500020001", "email": "sami@example.com", "national_id": "9876543210", "date_of_birth": "1993-03-12", "employment_type": "freelance", "employment_type_label": "Freelance captain", "status": "documents_required", "status_label": "Documents required", "review_note": "Please send a clearer photo of the driving license.", "reviewed_at": "2026-09-17 19:09:38", "can_receive_orders": false, "driving_license_number": "DL-54321", "driving_license_expires_at": "2030-01-01", "is_active": true, "documents": { "driving_license": "https://captain.kapitano.shop/storage/images/17-09-2026/19/44/new-license.png", "profile_photo": "https://captain.kapitano.shop/storage/images/17-09-2026/19/45/new-photo.png" }, "vehicle": { "uuid": "01a0b021-5fbb-7347-a6ce-77bb821239f2", "ownership_type": "personal", "ownership_type_label": "Personal vehicle owned by the applicant", "vehicle_type": null, "vehicle_type_label": null, "plate_number": "XYZ-7788", "brand": "Hyundai", "model": "Staria", "manufacture_year": 2021, "color": "black", "registration_number": null, "registration_expires_at": null, "registration_status": "missing", "registration_status_label": "Not recorded", "insurance_policy_number": null, "insurance_expires_at": null, "insurance_status": "missing", "insurance_status_label": "Not recorded", "images": { "vehicle_image": "https://captain.kapitano.shop/storage/images/17-09-2026/19/39/car.png", "mechanics_image": "https://captain.kapitano.shop/storage/images/17-09-2026/19/40/mechanic.png" }, "is_active": true, "created_at": "2026-09-17 19:09:32", "updated_at": "2026-09-17 19:09:32" }, "created_at": "2026-09-17 19:09:32" }, "Status": true, "Message": "Your documents have been updated and are back under review.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } }, "only the driving license replaced": { "summary": "Only driving_license sent: the profile photo keeps its earlier file.", "value": { "Model": { "uuid": "01m2r22qwbs3te5cbf3vy7ehb3", "name": "Sami Salem", "phone": "+966500020001", "email": "sami@example.com", "national_id": "9876543210", "date_of_birth": "1993-03-12", "employment_type": "freelance", "employment_type_label": "Freelance captain", "status": "documents_required", "status_label": "Documents required", "review_note": "Please send a clearer photo of the driving license.", "reviewed_at": "2026-09-17 19:09:38", "can_receive_orders": false, "driving_license_number": "DL-54321", "driving_license_expires_at": "2030-01-01", "is_active": true, "documents": { "driving_license": "https://captain.kapitano.shop/storage/images/17-09-2026/19/44/new-license.png", "profile_photo": "https://captain.kapitano.shop/storage/images/17-09-2026/19/42/photo.png" }, "vehicle": { "uuid": "01a0b021-5fbb-7347-a6ce-77bb821239f2", "ownership_type": "personal", "ownership_type_label": "Personal vehicle owned by the applicant", "vehicle_type": null, "vehicle_type_label": null, "plate_number": "XYZ-7788", "brand": "Hyundai", "model": "Staria", "manufacture_year": 2021, "color": "black", "registration_number": null, "registration_expires_at": null, "registration_status": "missing", "registration_status_label": "Not recorded", "insurance_policy_number": null, "insurance_expires_at": null, "insurance_status": "missing", "insurance_status_label": "Not recorded", "images": { "vehicle_image": "https://captain.kapitano.shop/storage/images/17-09-2026/19/39/car.png", "mechanics_image": "https://captain.kapitano.shop/storage/images/17-09-2026/19/40/mechanic.png" }, "is_active": true, "created_at": "2026-09-17 19:09:32", "updated_at": "2026-09-17 19:09:32" }, "created_at": "2026-09-17 19:09:32" }, "Status": true, "Message": "Your documents have been updated and are back under review.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } }, "Arabic": { "summary": "Accept-Language: ar — the message and labels come back in Arabic.", "value": { "Model": { "uuid": "01m2r22qwbs3te5cbf3vy7ehb3", "status": "documents_required", "status_label": "المستندات مطلوبة", "can_receive_orders": false, "review_note": "Please send a clearer photo of the driving license." }, "Status": true, "Message": "تم تحديث مستنداتك وهي الآن قيد المراجعة.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } } } }, "401": { "description": "Token missing or revoked, or a required header missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" }, "examples": { "no token": { "summary": "Authorization header missing or the token was revoked (e.g. after logout).", "value": { "Model": null, "Status": false, "Message": "These credentials do not match our records.", "MessageDebug": { "Unauthorized": [ "Unauthorized !" ] }, "Total": 0, "Page": 0, "Records": 0 } }, "no Accept-Language": { "summary": "The language header is required on every API request.", "value": { "Model": null, "Status": false, "Message": null, "MessageDebug": { "Language not definite": [ "Put the language code in the request header in Accept-Language" ] }, "Total": 0, "Page": 0, "Records": 0 } } } } } }, "422": { "description": "A file is missing, of the wrong type or too large — or documents were not requested on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "no file sent": { "summary": "Neither file was sent. Field errors are under MessageDebug.validation.", "value": { "Model": null, "Status": false, "Message": "Check the data", "MessageDebug": { "validation": { "driving_license": [ "The Driving license photo field is required when Profile photo is not present." ], "profile_photo": [ "The Profile photo field is required when Driving license photo is not present." ] } }, "Total": 0, "Page": 0, "Records": 0 } }, "wrong file type": { "summary": "profile_photo must be a jpg, jpeg or png image.", "value": { "Model": null, "Status": false, "Message": "Check the data", "MessageDebug": { "validation": { "profile_photo": [ "The Profile photo field must be an image.", "The Profile photo field must be a file of type: jpg, jpeg, png." ] } }, "Total": 0, "Page": 0, "Records": 0 } }, "documents not requested": { "summary": "The account is not in documents_required — e.g. already approved, or never sent back. No field errors: MessageDebug is null.", "value": { "Model": null, "Status": false, "Message": "Documents were not requested for this account.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } } } }, "429": { "description": "Too many requests (API throttle).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/handovers": { "get": { "tags": [ "Captain App — Handover" ], "summary": "Orders other captains are handing to me", "description": "The receiving captain's inbox. An order being handed over is not theirs until they accept\nit, so it appears in none of their other lists — this is the only place to find it.\n\nEach order carries a `handover` block naming the captain offering it. Oldest request\nfirst.", "operationId": "driverHandoverInbox", "responses": { "200": { "description": "The orders waiting for this captain.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainOrder" } }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/handover": { "post": { "tags": [ "Captain App — Handover" ], "summary": "Offer my order to another captain", "description": "**Nothing moves yet.** The order stays with the captain carrying it until the other captain\naccepts, and no capacity is reserved for them — they may take minutes to arrive.\n\n- Only the captain carrying the order may offer it (403 otherwise).\n- Only from `picked_up` or `on_the_way` (422). Before the pickup, decline instead.\n- Not to yourself, and not to a captain who is off duty or on a break (422).\n\n`to_captain_uuid` is the other captain's **ULID**.\n\n**The money stays put.** Whatever this captain paid the supplier, they stay owed it after\nthe handover.", "operationId": "driverHandoverRequest", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "to_captain_uuid" ], "properties": { "to_captain_uuid": { "description": "ULID of the receiving captain.", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" } }, "type": "object" } } } }, "responses": { "200": { "description": "Offered. `Model.handover.to_captain` names the receiver.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainOrderEnvelope" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "This captain is not carrying the order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order or captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Not in a car yet, handing to yourself, the other captain is off duty, or `to_captain_uuid` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] }, "delete": { "tags": [ "Captain App — Handover" ], "summary": "Withdraw my offer before it is answered", "operationId": "driverHandoverWithdraw", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Withdrawn; `handover` is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainOrderEnvelope" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "This captain is not carrying the order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "There is no handover to withdraw.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/handover/accept": { "post": { "tags": [ "Captain App — Handover" ], "summary": "Take the order being handed to me", "description": "**The only step where anything moves.** The order becomes this captain's, their capacity\nis taken with the same atomic check dispatch uses, and the handing-over captain's is\nreleased — in that order, so the parcel never belongs to nobody. Both captains' routes are\nrecomputed, and the timeline gains a row naming who took it.\n\nThe order's status does not change.\n\n**409** when this captain has no room left — worth hearing while still standing next to\nthe other captain.", "operationId": "driverHandoverAccept", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Taken. The order is now this captain's; `handover` is null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainOrderEnvelope" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not being handed to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "409": { "description": "This captain has no room for another order. Nothing moved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "The order is no longer in a car.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/handover/decline": { "post": { "tags": [ "Captain App — Handover" ], "summary": "Refuse the order being handed to me", "description": "The order stays with the captain carrying it, and the request is cleared.", "operationId": "driverHandoverDecline", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptainOrderEnvelope" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not being handed to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/ledger": { "get": { "tags": [ "Captain App — Ledger" ], "summary": "My balance and every movement behind it", "description": "The same figures the cash desk sees about this captain, so a captain can check the number\nthey are about to be settled against.\n\n`Balances` is per currency — never summed across them. **Positive means the company owes\nthe captain**; negative means the captain owes the company.\n\n`Model` is the statement, newest first: every supplier payment, every cash collection,\nevery movement at the desk, and every correction — nothing is ever edited or deleted.", "operationId": "driverLedger", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 10 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "example": "SYP" } ], "responses": { "200": { "description": "The statement, a page at a time.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainLedgerEntry" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Pages.", "type": "integer", "example": 1 }, "Page": { "type": "integer", "example": 1 }, "Records": { "type": "integer", "example": 2 }, "Balances": { "description": "currency => balance", "type": "object", "example": { "SYP": 300 } }, "Totals": { "description": "currency => what that balance is made of. The balance alone cannot say whether a captain is owed money or is holding cash somebody is waiting for, and those ask opposite actions of them.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CaptainBalanceBreakdown" } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "`rows` or `page` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders": { "get": { "tags": [ "Captain App — Orders" ], "summary": "My orders", "description": "The orders handed to the signed in captain, newest first, optionally narrowed to one\nstatus.\n\n**The envelope's names are not what they look like.** `Model` is the array of orders,\n`Page` is the current page — and `Total` is the number of **pages** while `Records` is\nthe number of **rows**. Paging on `Total` walks the list one page per order; the count\nto show the captain is `Records`.\n\n`rows` and `page` are optional. Left out, the answer is the first page of 15 rather\nthan a 422.\n\n**Every order in the list carries `leg`.** `null` is an ordinary delivery and is nearly\nall of them; `collection` is the internal half of a wrapped order, with a wrapping shop\nin `customer_name` and no money to collect. See the flow guide on this page.\n\n`pickups[]` comes back with each order, so a multi-supplier order can be drawn from the\nlist without a second call.", "operationId": "driverOrderIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 10 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "status", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "assigned", "picked_up", "on_the_way", "delivered", "delivery_failed" ] } } ], "responses": { "200": { "description": "A page of orders.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainOrder" } }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": null, "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 1 }, "Page": { "type": "integer", "example": 1 }, "Records": { "type": "integer", "example": 1 } }, "type": "object" }, "example": { "Model": [ { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "on_the_way", "status_label": "On the way", "next_statuses": [ "delivered", "delivery_failed" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivered", "label": "Delivered", "state": "next", "state_label": "Next", "at": null } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": null, "failed_at": null, "failed_reason": null } ], "Status": true, "Message": null, "MessageDebug": null, "Total": 1, "Page": 1, "Records": 1 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Missing/invalid page, rows or status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}": { "get": { "tags": [ "Captain App — Orders" ], "summary": "One of my orders, in full", "description": "One order in full: the customer and how to reach them, every stop it is collected from,\nthe lines to ask for at each, the money in both directions, and the delivery progress.\n\nThis is what the new-order push (`data.order_uuid`) opens, and what every state-changing\ncall answers with — so the app rarely needs to re-read it after acting.\n\n**What to drive the screen from:**\n\n- `next_statuses` — the forward moves allowed right now. Draw buttons from this, never\n from `status`, because a directed order arrives already accepted.\n- `steps` — the whole sequence with each step marked done, next, upcoming or failed.\n- `pickups[]` — the stops, each with the `uuid` its confirmation is addressed to, and\n `pickups_pending` for how many are left.\n- `leg` — `collection` means there is no customer and no cash on this order, whatever\n `customer_name` appears to say.\n- `expected_goods_cost` against `amount_paid`, and `amount_to_collect` against\n `amount_collected` — what the order should cost and what it actually did.\n\nAnother captain's order answers **403**, not 404: the order exists, it is simply not\ntheirs to read.", "operationId": "driverOrderShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "responses": { "200": { "description": "The order, ready for the delivery screen.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": null, "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "on_the_way", "status_label": "On the way", "next_statuses": [ "delivered", "delivery_failed" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivered", "label": "Delivered", "state": "next", "state_label": "Next", "at": null } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": null, "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/accept": { "post": { "tags": [ "Captain App — Orders" ], "summary": "I will take it", "description": "**Assigned → Accepted.** The first call of every delivery.\n\nAn assignment is an offer. Until it is accepted the order is still counted against this\ncaptain, but `offer_expires_at` is running: when it passes, the offer is taken back and\nthe order goes to somebody else.\n\nAccepting stops that clock (`offer_expires_at` comes back `null`), stamps `accepted_at`,\nand opens the pickup. **It cannot fail for want of capacity** — the slot was reserved when\ndispatch assigned the order, so accepting only records the answer.\n\nAnswers **422** if the order is no longer on offer: the countdown ran out and it was\nhanded to another captain while this screen was open.", "operationId": "driverOrderAccept", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "responses": { "200": { "description": "The offer is taken; the pickup is now the next step.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "You have accepted the order.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "accepted", "status_label": "Accepted", "next_statuses": [ "picked_up" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "next", "state_label": "Next", "at": null }, { "status": "on_the_way", "label": "On the way", "state": "upcoming", "state_label": "Upcoming", "at": null }, { "status": "delivered", "label": "Delivered", "state": "upcoming", "state_label": "Upcoming", "at": null } ], "items_collected": null, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": null, "on_the_way_at": null, "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "You have accepted the order.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "No longer on offer — the countdown ran out, or it was already answered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/decline": { "post": { "tags": [ "Captain App — Orders" ], "summary": "I cannot take it", "description": "**Assigned → Pending**, or **Accepted → Pending**. The order goes back to the pool.\n\nAllowed right up to the pickup, not just while the offer is fresh — a captain whose car\nwill not start after accepting needs a way out that is not a failed delivery. Once the\nparcel is in the car this answers **422**; use `failed` instead, which requires a reason.\n\nThe captain's capacity is released, and **this captain is left out of that order's next\nsuggestion list**. The ranking that put them first would otherwise hand the same order\nstraight back to the same phone. The exclusion is about this order only and never follows\nthe captain to another one.\n\n`reason` is optional. Nothing is gained by forcing a captain to type a character to get\npast a dialog, and who declined what is recorded either way.", "operationId": "driverOrderDecline", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "example": "Too far from me right now.", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Handed back. The order is pending again and belongs to nobody.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "You have declined the order. It has gone back for reassignment.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "pending", "status_label": "Pending", "next_statuses": [], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "upcoming", "state_label": "Upcoming", "at": null }, { "status": "on_the_way", "label": "On the way", "state": "upcoming", "state_label": "Upcoming", "at": null }, { "status": "delivered", "label": "Delivered", "state": "upcoming", "state_label": "Upcoming", "at": null } ], "items_collected": null, "items_mismatch": false, "accepted_at": null, "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": null, "on_the_way_at": null, "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "You have declined the order. It has gone back for reassignment.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Too late — the parcel has been collected. Use failed instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/picked-up": { "patch": { "tags": [ "Captain App — Orders" ], "summary": "I have the package", "description": "**Accepted → Picked up.** The order must have been accepted first — `assigned → picked_up`\nis not a legal move and answers **422**.\n\n**Money:** when the captain paid the supplier, send `amount_paid`. The company then owes\nthis captain that amount, whoever ends up delivering the order — the balance follows who\nspent the money, not who carries the parcel. A figure different from\n`expected_goods_cost` is recorded as a variance, not refused.\n\nOne tap: send an empty body. Optionally confirm how many items\nwere collected with `items_collected`; it is compared with `items_expected` (the sum of\nthe product quantities). A different count still picks the order up, sets\n`items_mismatch = true` for the operations team, and answers with a message saying so.", "operationId": "driverOrderPickedUp", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "items_collected": { "type": "integer", "example": 3, "nullable": true, "maximum": 9999, "minimum": 1 }, "amount_paid": { "description": "What the captain paid the supplier out of their own pocket. Pre-fill with `expected_goods_cost` and let the captain correct it. Recorded as money the company owes this captain; 0 or omitted records nothing.", "type": "number", "format": "float", "example": 300, "nullable": true, "maximum": 999999.98999999999068677425384521484375, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Step taken.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order has been picked up.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "examples": { "one-tap pickup": { "summary": "Empty body — the pickup goes through and nothing is flagged.", "value": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "picked_up", "status_label": "Picked up", "next_statuses": [ "on_the_way" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "next", "state_label": "Next", "at": null }, { "status": "delivered", "label": "Delivered", "state": "upcoming", "state_label": "Upcoming", "at": null } ], "items_collected": null, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": null, "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order has been picked up.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } }, "expected count confirmed": { "summary": "items_collected matches items_expected: not flagged.", "value": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "picked_up", "status_label": "Picked up", "next_statuses": [ "on_the_way" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "next", "state_label": "Next", "at": null }, { "status": "delivered", "label": "Delivered", "state": "upcoming", "state_label": "Upcoming", "at": null } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": null, "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order has been picked up.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } }, "item count mismatch": { "summary": "items_collected differs from items_expected: still picked up, but flagged for the operations team.", "value": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "picked_up", "status_label": "Picked up", "next_statuses": [ "on_the_way" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "next", "state_label": "Next", "at": null }, { "status": "delivered", "label": "Delivered", "state": "upcoming", "state_label": "Upcoming", "at": null } ], "items_collected": 2, "items_mismatch": true, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": null, "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order has been picked up. The number of items collected does not match the order, so it has been flagged for the operations team.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Not allowed from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/pickups/{pickup}/collected": { "patch": { "tags": [ "Captain App — Orders" ], "summary": "I have collected this store", "description": "**One store of an order that is collected from several.** An order may gather its goods\nfrom up to three suppliers; `pickups[]` on the order lists them in visiting order, each\nwith the `uuid` this route is addressed to.\n\n**The order does not move until the last store is confirmed.** Collect one of three and\nthe order stays `accepted`, with that store stamped and gone from the route plan; collect\nthe last and the order becomes `picked_up`, its `items_collected` and `amount_paid` the\nsums of the stores.\n\n**Money is recorded against the shop it was paid at**, so a disputed payment names a\ncounter rather than an order.\n\n`items_collected` is compared with that store's own `items_expected` — the quantities of\nthe lines assigned to it. A different count still collects the store and flags it. A\nstore that owns no lines expects nothing and is never flagged.\n\n`PATCH /picked-up` is unchanged and still collects everything outstanding in one tap,\nfor an app that does not work store by store.", "operationId": "driverOrderPickupCollected", "parameters": [ { "name": "uuid", "in": "path", "description": "The order.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" }, { "name": "pickup", "in": "path", "description": "The store, from `pickups[].uuid` on the order.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e999" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "items_collected": { "description": "How many pieces came off this counter. Omit for a one-tap confirmation.", "type": "integer", "example": 3, "nullable": true, "maximum": 9999, "minimum": 1 }, "amount_paid": { "description": "What the captain paid at this supplier. Recorded as money the company owes them, against this store. 0 or omitted records nothing.", "type": "number", "format": "float", "example": 120, "nullable": true, "maximum": 999999.98999999999068677425384521484375, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Store collected. The order is returned so the app can see what is left.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Store collected.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such order, or that store does not belong to this order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "This store has already been collected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/on-the-way": { "patch": { "tags": [ "Captain App — Orders" ], "summary": "I am driving to the customer", "description": "Picked up → On the way. The on-the-way step is marked done and the delivery becomes the next step.", "operationId": "driverOrderOnTheWay", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "responses": { "200": { "description": "Step taken.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order is on the way.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "on_the_way", "status_label": "On the way", "next_statuses": [ "delivered", "delivery_failed" ], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivered", "label": "Delivered", "state": "next", "state_label": "Next", "at": null } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": null, "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order is on the way.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Not allowed from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/delivered": { "post": { "tags": [ "Captain App — Orders" ], "summary": "Delivered (with the proof photo)", "description": "**On the way → Delivered.** The call the delivery screen makes.\n\n**Use POST whenever a photo is being sent.** PHP parses a multipart body only on a POST,\nso `proof` cannot arrive any other way. The same path also answers `PATCH` for a delivery\nclosed with nothing but a note — see the PATCH operation below.\n\n`proof` is the proof-of-delivery photo: `jpg`, `jpeg`, `png` or `webp`, up to **5 MB**.\nIts URL comes back on the order as `proof_of_delivery`, and the dashboard shows the same\nfile.\n\nThe photo is **optional in the API**, so an older app build can still close a delivery,\nbut it is the only record that says the parcel arrived and the one piece of evidence\nbehind a disputed delivery. **The app should always send one.**\n\nThe upload is filed **before** the status moves: if the photo cannot be stored, the order\nstays on the way and answers 422 rather than being recorded as delivered with its proof\nquietly dropped. Retrying replaces the photo, it does not pile them up.\n\nThe optional `note` lands on the order timeline.\n\n**Money:** on a cash order send `amount_collected` — what the customer actually handed\nover. It is recorded as money this captain owes the company and cleared at the cash desk.\nA customer who paid short is recorded as a variance, not a refused delivery.\n\n**A refunded order cannot be delivered** (422): the store has already paid the customer\nback, and delivering would take a second payment for the same goods.", "operationId": "driverOrderDeliveredWithProof", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "proof": { "description": "The proof-of-delivery photo. jpg, jpeg, png or webp, max 5 MB.", "type": "string", "format": "binary", "nullable": true }, "amount_collected": { "description": "Cash taken from the customer. Pre-fill with `amount_to_collect`. Recorded as money this captain owes the company. Leave out on a prepaid delivery.", "type": "number", "format": "float", "example": 380, "nullable": true, "maximum": 999999.98999999999068677425384521484375, "minimum": 0 }, "note": { "type": "string", "example": "Handed to reception.", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Step taken.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order has been delivered.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "delivered", "status_label": "Delivered", "next_statuses": [], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivered", "label": "Delivered", "state": "done", "state_label": "Done", "at": "2026-09-13 12:30:00" } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": "https://api.kapitano.shop/storage/42/doorstep.jpg", "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": "2026-09-13 12:30:00", "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order has been delivered.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Not allowed from the current status, or the photo was rejected or could not be stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] }, "patch": { "tags": [ "Captain App — Orders" ], "summary": "Delivered (note only, no photo)", "description": "**On the way → Delivered**, with no proof photo.\n\nThe same handler as the POST above. It is kept so an app build that predates the camera\nstep keeps working against the same route; **a build that can take a photo should POST**.\n\nA delivery closed this way comes back with `proof_of_delivery: null`, and there is nothing\nto show if it is later disputed.", "operationId": "driverOrderDelivered", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "note": { "type": "string", "example": "Handed to reception.", "nullable": true, "maxLength": 1000 }, "amount_collected": { "description": "Cash taken from the customer. Recorded as money this captain owes the company.", "type": "number", "format": "float", "example": 380, "nullable": true, "maximum": 999999.98999999999068677425384521484375, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Delivered, with no proof on file.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order has been delivered.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "delivered", "status_label": "Delivered", "next_statuses": [], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivered", "label": "Delivered", "state": "done", "state_label": "Done", "at": "2026-09-13 12:30:00" } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": "2026-09-13 12:30:00", "failed_at": null, "failed_reason": null }, "Status": true, "Message": "The order has been delivered.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Not allowed from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/orders/{uuid}/failed": { "patch": { "tags": [ "Captain App — Orders" ], "summary": "Delivery failed", "description": "On the way → Delivery failed. A reason is required and lands on the order timeline.", "operationId": "driverOrderFailed", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Customer not reachable.", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Step taken.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The delivery could not be completed.", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "type": "integer", "example": 0 } }, "type": "object" }, "example": { "Model": { "uuid": "01a089d1-9dc5-7207-b8ec-928fa322e342", "order_number": "ORD-100002", "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "customer_note": "Call on arrival.", "pickup_address": "Store 12, Granada Mall, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_address": "Olaya Street, Riyadh", "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "items": [ { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db5", "name": "Perfume", "quantity": 2, "unit_price": 60, "note": null }, { "uuid": "01a08600-878b-726b-8df7-0c1bc4374db6", "name": "Gift wrap", "quantity": 1, "unit_price": 5, "note": null } ], "items_expected": 3, "payment_method": "cash_on_delivery", "payment_method_label": "Cash on delivery", "amount_to_collect": 92.5, "currency": "SYP", "created_at": "2026-09-13 09:30:00", "status": "delivery_failed", "status_label": "Delivery failed", "next_statuses": [], "steps": [ { "status": "picked_up", "label": "Picked up", "state": "done", "state_label": "Done", "at": "2026-09-13 09:45:00" }, { "status": "on_the_way", "label": "On the way", "state": "done", "state_label": "Done", "at": "2026-09-13 09:55:00" }, { "status": "delivery_failed", "label": "Delivery failed", "state": "failed", "state_label": "Failed", "at": "2026-09-13 11:00:00" } ], "items_collected": 3, "items_mismatch": false, "accepted_at": "2026-09-13 09:39:12", "offer_expires_at": null, "proof_of_delivery": null, "picked_up_at": "2026-09-13 09:45:00", "on_the_way_at": "2026-09-13 09:55:00", "delivered_at": null, "failed_at": "2026-09-13 11:00:00", "failed_reason": "Customer not reachable." }, "Status": true, "Message": "The delivery could not be completed.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The order is not assigned to this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Missing reason, or not allowed from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/availability": { "get": { "tags": [ "Captain App — Presence" ], "summary": "What the captain availability is right now", "description": "On duty, on a break, and when that last changed. The app asks on launch: without it a\nrestart can only guess, or write a value nobody asked for — which is how a captain ends up\nonline with their phone in a drawer.\n\nA captain who has never gone online answers `is_online: false`, `on_break: false` and a null\n`last_seen_at`, with a **200**. Reading the answer never creates the row.\n\nUnlike setting it, this does not require an approved captain: one still under review may open\nthe app, and \"you are offline\" is the truth, while a 403 would read as a fault in the app.", "operationId": "driverReadAvailability", "responses": { "200": { "description": "The current availability.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/DriverAvailability" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] }, "post": { "tags": [ "Captain App — Presence" ], "summary": "Turn availability on or off, take or end a break", "description": "`is_online` is required. `on_break` is optional: an online captain on a break is not\noffered new orders; a request without it leaves the break as it was. Going offline ends\nthe break and takes the captain off the live dispatch map.\n\nOnly an **approved** captain may go online. Any other signed-in captain answers 403 —\nincluding one in `documents_required`, who may sign in to re-upload documents but must\nnot be offered orders.", "operationId": "driverSetAvailability", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "is_online" ], "properties": { "is_online": { "type": "boolean", "example": true }, "on_break": { "type": "boolean", "example": false } }, "type": "object" }, "example": { "is_online": true, "on_break": false } } } }, "responses": { "200": { "description": "Availability updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/DriverAvailability" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "The captain is not approved — e.g. sent back for documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" }, "example": { "Model": null, "Status": false, "Message": "Only an approved captain may go online.", "MessageDebug": null, "Total": 0, "Page": 0, "Records": 0 } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/location": { "post": { "tags": [ "Captain App — Presence" ], "summary": "Report the newest GPS position (adaptive ping)", "description": "Stores the captain's newest position in the database and on the live dispatch map\n(Redis), then answers with `next_ping_seconds`: the app should send its next ping after\nthat many seconds — short while the captain moves, long while they stand still.\n\n- `speed_mps` is what the phone's GPS reports; when it is missing, the speed is worked out\n from the previous point.\n- **The server stamps every position** with the moment the request arrives. Do not send\n `captured_at`; if it is sent it is ignored. (Honouring the phone's clock let a time\n without a timezone, or a stale example date, make every ping look old and be dropped.)\n- A buffered ping sent after reconnecting is therefore stamped when it arrives. Send\n buffered pings oldest first, so the last one — the newest — is what stays stored.\n- `accepted: false` means the ping was not written because the stored point is newer. With\n server stamping this only happens if the server's clock steps backwards.", "operationId": "driverReportLocation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "lat", "lng" ], "properties": { "lat": { "type": "number", "format": "float", "example": 24.7135999999999995679900166578590869903564453125, "maximum": 90, "minimum": -90 }, "lng": { "type": "number", "format": "float", "example": 46.67530000000000001136868377216160297393798828125, "maximum": 180, "minimum": -180 }, "accuracy": { "type": "number", "format": "float", "example": 6.5, "nullable": true, "maximum": 10000, "minimum": 0 }, "speed_mps": { "description": "Metres per second.", "type": "number", "format": "float", "example": 11.199999999999999289457264239899814128875732421875, "nullable": true, "maximum": 100, "minimum": 0 }, "heading": { "description": "Degrees clockwise from north.", "type": "integer", "example": 270, "nullable": true, "maximum": 359, "minimum": 0 } }, "type": "object" } } } }, "responses": { "200": { "description": "Ping handled.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "lat": { "type": "number", "format": "float", "example": 24.7135999999999995679900166578590869903564453125 }, "lng": { "type": "number", "format": "float", "example": 46.67530000000000001136868377216160297393798828125 }, "accuracy": { "type": "number", "format": "float", "example": 6.5, "nullable": true }, "captured_at": { "description": "When the server received the stored point, in the application time zone.", "type": "string", "format": "date-time", "example": "2026-09-14 10:19:59" }, "speed_mps": { "type": "number", "format": "float", "example": 11.199999999999999289457264239899814128875732421875, "nullable": true }, "heading": { "type": "integer", "example": 270, "nullable": true }, "accepted": { "description": "False when the ping was older than the stored point and was not written.", "type": "boolean", "example": true }, "next_ping_seconds": { "type": "integer", "example": 8 } }, "type": "object" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/profile": { "get": { "tags": [ "Captain App — Profile" ], "summary": "Signed in captain's own record", "operationId": "driverProfileShow", "responses": { "200": { "description": "The captain record, documents and vehicle included.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Driver" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] }, "post": { "tags": [ "Captain App — Profile" ], "summary": "Update the signed in captain's record", "description": "Replaces the optional fields sent. The email must stay unique (other captains excluded).", "operationId": "driverProfileUpdate", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "aziz.free@example.com", "nullable": true, "maxLength": 255 }, "driving_license_number": { "type": "string", "example": "DL-10008", "maxLength": 50 }, "driving_license_expires_at": { "description": "Must be after today.", "type": "string", "format": "date", "example": "2029-09-12" }, "driving_license": { "description": "jpg/jpeg/png/pdf, max 5120KB", "type": "string", "format": "binary" }, "profile_photo": { "description": "jpg/jpeg/png, max 5120KB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Record updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Driver" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/route-plan": { "get": { "tags": [ "Captain App — Route" ], "summary": "The route this captain is driving", "description": "The stops the captain still has to make — every store not yet collected and every customer\nnot yet delivered — in the order the system wants them driven, with the line to draw and\nthe arrival time for each one.\n\n**Call this when the app opens, when it returns from the background, and whenever a push\nsays the version moved.** The push carries a version, not a route: a route with a polyline\ncan exceed what a push message may hold, and a message too large is rejected outright,\nwhich would leave the captain with nothing. One way to read a route is also one way for it\nto be wrong.\n\n**Render only the highest `version` you have seen.** Routes are recomputed whenever an\norder joins or a stop is completed, and a websocket frame or a push can arrive after a\nnewer one. A client that repainted on arrival order would show a route that has already\nbeen replaced. Compare, keep the highest, ignore the rest.\n\n**`degraded: true` means the map service could not answer.** The stops and their order are\nstill correct — that is arithmetic, not cartography — but the times are estimated from\nstraight-line distance and `polyline` is null. Draw the stop list; do not draw a route\nline that does not exist.\n\n`Model` is `null` when the captain is carrying nothing. That is an answer, not an error.", "operationId": "captainRoutePlan", "responses": { "200": { "description": "The route, or null when there is nothing to drive.", "content": { "application/json": { "schema": { "properties": { "Model": { "oneOf": [ { "$ref": "#/components/schemas/RoutePlan" } ], "nullable": true }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "driverAuth": [] } ] } }, "/api/driver/vehicle": { "get": { "tags": [ "Captain App — Vehicle" ], "summary": "Signed in captain's own vehicle", "description": "The vehicle the captain drives, with photos and the registration / insurance status. A captain with no vehicle on record answers 404.", "operationId": "driverVehicleShow", "responses": { "200": { "description": "The vehicle.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Vehicle" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "No vehicle on record for this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "driverAuth": [] } ] }, "post": { "tags": [ "Captain App — Vehicle" ], "summary": "Update the captain's own car", "description": "Multipart. Only a captain driving their **own** car (`ownership_type = personal`) may\nchange it; a company car answers 403 — the back office manages it. Only the fields sent\nchange, saved immediately. The plate must stay unique (the captain's own plate may be\nre-sent). Registration / insurance fields may be sent empty to clear them.\n`ownership_type` is never changed by the captain and is ignored if sent.", "operationId": "driverVehicleUpdate", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "vehicle_type": { "type": "string", "example": "car", "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "plate_number": { "type": "string", "example": "AZZ-8008", "maxLength": 20 }, "brand": { "type": "string", "example": "GMC", "maxLength": 100 }, "model": { "type": "string", "example": "Terrain", "maxLength": 100 }, "manufacture_year": { "type": "integer", "example": 2021, "maximum": 2027, "minimum": 1950 }, "color": { "type": "string", "example": "red", "maxLength": 50 }, "registration_number": { "type": "string", "example": "REG-8008", "nullable": true, "maxLength": 50 }, "registration_expires_at": { "type": "string", "format": "date", "example": "2027-09-30", "nullable": true }, "insurance_policy_number": { "type": "string", "example": "INS-8008", "nullable": true, "maxLength": 50 }, "insurance_expires_at": { "type": "string", "format": "date", "example": "2027-02-28", "nullable": true }, "vehicle_image": { "description": "jpg/jpeg/png, max 5 MB.", "type": "string", "format": "binary" }, "mechanics_image": { "description": "jpg/jpeg/png, max 5 MB.", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Vehicle updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Vehicle" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "A company vehicle — only the back office may change it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No vehicle on record for this captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Validation failed (e.g. plate number already on record).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "driverAuth": [] } ] } } }, "components": { "schemas": { "ErrorValidation": { "description": "422 — validation failed; the offending fields sit under MessageDebug.validation.", "example": { "Model": null, "Status": false, "Message": "Validation Error", "MessageDebug": { "validation": { "phone": [ "The phone field is required." ] } }, "Total": 0, "Page": 0, "Records": 0 }, "allOf": [ { "properties": { "Status": { "description": "422 — validation failed. The offending fields sit under `MessageDebug.validation`.", "type": "boolean", "example": false }, "Message": { "type": "string", "example": "Validation Error" }, "MessageDebug": { "properties": { "validation": { "type": "object", "example": { "phone": [ "The phone field is required." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" } }, "type": "object" } ] }, "ErrorUnauthorized": { "description": "401 — missing/invalid token, or a required header was not sent.", "properties": { "Status": { "description": "401 — no usable token, or the required headers are missing.", "type": "boolean", "example": false }, "Message": { "description": "Already translated and safe to show. On this status it rarely helps the user, though — a missing header and a dead token read the same to them, so prefer sending them back to sign in.", "type": "string", "example": "Unauthorized", "nullable": true }, "MessageDebug": { "description": "Diagnostic detail (unauthorized / accept_header / language) — this is what tells the two apart while developing. Never shown to a user." } }, "type": "object", "example": { "Model": null, "Status": false, "Message": "Unauthorized", "MessageDebug": { "Unauthorized": [ "Unauthorized !" ] }, "Total": 0, "Page": 0, "Records": 0 } }, "ErrorForbidden": { "description": "403 — the account is disabled/rejected, or the admin lacks the required permission.", "properties": { "Status": { "description": "403 — the account is turned away for good, or the token lacks the permission.", "type": "boolean", "example": false }, "Message": { "description": "Why it was refused, already translated. Worth showing: a suspended captain needs to know that is what happened rather than that something broke.", "type": "string", "example": null, "nullable": true }, "MessageDebug": { "description": "Diagnostic detail (reason / permission message). Never shown to a user." } }, "type": "object", "example": { "Model": null, "Status": false, "Message": null, "MessageDebug": "You do not have permission to access this link.", "Total": 0, "Page": 0, "Records": 0 } }, "ErrorNotFound": { "description": "404 — the requested record was not found.", "properties": { "Status": { "description": "404 — the record (or account) does not exist.", "type": "boolean", "example": false }, "Message": { "description": "Already translated and safe to show.", "type": "string", "example": "The item not found" }, "MessageDebug": { "description": "The machine-readable key behind the message. Never shown to a user.", "type": "object", "example": { "item_not_found": [] } } }, "type": "object", "example": { "Model": null, "Status": false, "Message": "The item not found", "MessageDebug": { "item_not_found": [] }, "Total": 0, "Page": 0, "Records": 0 } }, "ErrorConflict": { "description": "409 — the requested change conflicts with the current state (e.g. re-deciding an application).", "properties": { "Status": { "description": "409 — the state machine refuses a repeated decision.", "type": "boolean", "example": false }, "Message": { "description": "Already translated and safe to show. A conflict usually means the screen is out of date, so re-reading the record is the right next move.", "type": "string", "example": "The item already exists." }, "MessageDebug": { "description": "The machine-readable key behind the message. Never shown to a user.", "type": "object", "example": { "item_already_exists": [] } } }, "type": "object", "example": { "Model": null, "Status": false, "Message": "The item already exists.", "MessageDebug": { "item_already_exists": [] }, "Total": 0, "Page": 0, "Records": 0 } }, "ErrorLocked": { "description": "423 — the application is still under review.", "properties": { "Status": { "description": "423 — an account still under review cannot move forward.", "type": "boolean", "example": false }, "Message": { "description": "Already translated and safe to show — this is the waiting-room screen a new applicant sees when they try to sign in.", "type": "string", "example": "Your application is under review." }, "MessageDebug": { "description": "The machine-readable reason. Never shown to a user.", "type": "object", "example": { "reason": "pending" } } }, "type": "object", "example": { "Model": null, "Status": false, "Message": "Your application is under review.", "MessageDebug": { "reason": "pending" }, "Total": 0, "Page": 0, "Records": 0 } }, "ErrorTooManyRequests": { "description": "429 — too many requests; slow down and retry shortly.", "properties": { "Status": { "description": "429 — the request was throttled.", "type": "boolean", "example": false }, "Message": { "description": "Already translated and safe to show. Back off rather than retrying straight away — the OTP endpoints allow four attempts a minute.", "type": "string", "example": "Too many requests, please slow down and try again shortly" }, "MessageDebug": { "description": "The machine-readable key behind the message. Never shown to a user.", "type": "object", "example": { "too_many_requests": [] } } }, "type": "object", "example": { "Model": null, "Status": false, "Message": "Too many requests, please slow down and try again shortly", "MessageDebug": { "too_many_requests": [] }, "Total": 0, "Page": 0, "Records": 0 } }, "CaptainLedgerEntry": { "description": "One movement of money between a captain and the company. Written once and never edited — a\ncorrection is a new `adjustment` line.\n\n**`amount` is signed: positive means the company owes the captain.** A supplier payment and\ncash handed in are positive; cash collected from a customer and cash paid out by the desk are\nnegative. `balance_after` is the captain's running balance in this currency once the line\nlanded.", "properties": { "uuid": { "description": "One line of a captain's statement.", "type": "string", "format": "uuid", "example": "01a0c6d2-4f1e-7c3a-9b2d-5e8f1a2b3c4d" }, "type": { "description": "What kind of movement this is. `supplier_payment` and `delivery_earning` raise the balance (the company owes the captain more), `cash_collected` and `cash_handed_in` and `cash_paid_out` lower it, and `adjustment` is a correction that may go either way.", "type": "string", "example": "supplier_payment", "enum": [ "supplier_payment", "cash_collected", "delivery_earning", "cash_paid_out", "cash_handed_in", "adjustment" ] }, "type_label": { "description": "The movement type translated for the screen.", "type": "string", "example": "Paid supplier" }, "amount": { "description": "Signed. Positive = the company owes the captain.", "type": "number", "format": "float", "example": 300 }, "balance_after": { "description": "The running balance in this currency once this line landed — so a statement reconciles down the page without the reader adding anything up.", "type": "number", "format": "float", "example": 300 }, "currency": { "description": "Always `SYP`. Balances are grouped by it, which is why every line still carries it.", "type": "string", "example": "SYP" }, "expected_amount": { "description": "What the system expected: the goods cost for a supplier payment, `amount_to_collect` for a collection. Null for a desk movement.", "type": "number", "format": "float", "example": 300, "nullable": true }, "variance": { "description": "Actual minus expected. Null when nothing was expected.", "type": "number", "format": "float", "example": 0, "nullable": true }, "has_variance": { "description": "Whether the actual and the expected disagree — the flag to colour a row by, so a captain is not left comparing two numbers themselves.", "type": "boolean", "example": false }, "order": { "description": "Which order the movement belongs to. Null on a desk movement, which settles a balance rather than a delivery.", "properties": { "uuid": { "description": "Opens the order this movement came from.", "type": "string", "format": "uuid" }, "order_number": { "description": "The reference to show beside the amount, so a captain can match a line to a job.", "type": "string", "example": "ORD-100002" } }, "type": "object", "nullable": true }, "pickup": { "description": "Which counter the money changed hands at, on a payment made to one supplier of a multi-supplier order. This is what turns \"the order was 4,000 short\" into \"the second shop was\", and it is the difference between an office ringing the captain and an office ringing the right shop. Null on an order collected in one tap, and on every desk movement.", "properties": { "uuid": { "description": "The stop the payment was made at.", "type": "string", "format": "uuid" }, "store_name": { "description": "The counter to name when a payment is queried. Null when the store sent no name.", "type": "string", "example": "بيت العود", "nullable": true }, "address": { "description": "Where that counter is — enough for an office to ring the right shop.", "type": "string", "example": "شارع الثورة، دمشق" } }, "type": "object", "nullable": true }, "captain": { "description": "Whose line it is. Present on the money feed, where every row is a different person; absent from a statement that already names one captain beside the page.", "properties": { "uuid": { "description": "A ULID — whose line this is.", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "description": "The captain name, for a feed where every row is a different person.", "type": "string", "example": "Ahmed" } }, "type": "object", "nullable": true }, "recorded_by": { "description": "Who wrote the line: the captain on their phone, or the back office.", "properties": { "kind": { "description": "Which side entered it. A captain-entered figure is a claim from the road; a back-office one has already been through somebody at a desk.", "type": "string", "example": "captain", "enum": [ "captain", "back_office", "other" ] }, "name": { "description": "Who exactly. Null when the actor is no longer on record.", "type": "string", "example": "Ahmed", "nullable": true } }, "type": "object", "nullable": true }, "reference": { "description": "Voucher or receipt number from the desk.", "type": "string", "example": "VCH-2001", "nullable": true }, "note": { "description": "Whatever was written alongside the movement, by the captain or the desk.", "type": "string", "example": null, "nullable": true }, "created_at": { "description": "When the movement was recorded. A statement reads newest first.", "type": "string", "format": "date-time", "example": "2026-09-21 10:15:00" } }, "type": "object" }, "CaptainBalanceBreakdown": { "description": "What a balance is actually made of, keyed by currency. The balance on its own is one number standing in for four different things, and two of them ask opposite actions: money the company owes a captain is theirs to claim, cash they are holding belongs to somebody else. Reported as plain positive totals with names that say the direction, so nothing has to be inferred from a sign.", "properties": { "paid_to_suppliers": { "description": "What the captain paid out of pocket at suppliers.", "type": "number", "format": "float", "example": 140 }, "collected_from_customers": { "description": "What they took from customers on delivery.", "type": "number", "format": "float", "example": 200 }, "earned_from_deliveries": { "description": "What the deliveries themselves earned them — their own pay, not money passing through their hands.", "type": "number", "format": "float", "example": 0 }, "reimbursed_by_desk": { "description": "What the cashier has already paid back to them.", "type": "number", "format": "float", "example": 0 }, "handed_in_at_desk": { "description": "What they have already handed in.", "type": "number", "format": "float", "example": 0 }, "adjustments": { "description": "Signed, because a correction is the one entry whose meaning is \"this much, this way\" - flattening it to a magnitude would hide which way it went.", "type": "number", "format": "float", "example": 0 }, "balance": { "description": "The signed net, unchanged: positive still means the company owes the captain. Every movement is inside exactly one of the parts above, so none of this balance is unaccounted for — reading them back to it means applying the direction each name states, since the parts themselves are magnitudes.", "type": "number", "format": "float", "example": -60 } }, "type": "object" }, "CaptainOrderEnvelope": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "description": "Whether the call succeeded. Read this rather than guessing from whether `Model` is null — plenty of successful calls answer with null, such as a route plan for a captain carrying nothing.", "type": "boolean", "example": true }, "Message": { "description": "A sentence for the captain, already translated into the language `Accept-Language` asked for. Safe to show as-is.", "type": "string", "example": null, "nullable": true }, "MessageDebug": { "description": "Detail for developers, and null outside local development. Never show it to a captain.", "example": null, "nullable": true }, "Total": { "description": "**The number of pages, not the number of rows.** The name is the opposite of what it reads like, and `Records` is the row count — so paging on this field walks the list one page per row. Zero on a single-object response.", "type": "integer", "example": 0 }, "Page": { "description": "Which page this is, 1-based. Zero on a single-object response.", "type": "integer", "example": 0 }, "Records": { "description": "**The total number of rows across every page** — the count to show the captain. Zero on a single-object response.", "type": "integer", "example": 0 } }, "type": "object" }, "CashHandIn": { "description": "A captain saying they are bringing the company's cash in, and what the desk did about it.\n\n**`declared_amount` is a claim, not money.** While the status is `pending` nothing in the ledger\nhas moved and the captain still owes every riyal of it: a screen drawing the declared figure as\nsettled would be telling an operator the company holds cash that is still in somebody's pocket.\n\n`confirmed_amount` is the money — it exists once somebody has counted it — and it is allowed to\ndiffer from the declaration. `shortfall` is the gap, positive when the desk received **less** than\nwas promised, which is the number worth looking at.", "properties": { "uuid": { "description": "How the declaration is addressed — what a captain sends to call their own one off.", "type": "string", "format": "uuid" }, "status": { "description": "Where the declaration stands. **Only `confirmed` has moved any money**: `pending` is a claim waiting at the desk, `cancelled` is the captain calling it off, `declined` is the desk refusing it. A captain may cancel only while it is `pending`.", "type": "string", "example": "pending", "enum": [ "pending", "confirmed", "declined", "cancelled" ] }, "status_label": { "description": "The status translated for the screen.", "type": "string", "example": "Waiting for the desk" }, "currency": { "description": "Always `SYP`. A hand-in settles one currency, which is why it is named on the declaration.", "type": "string", "example": "SYP" }, "declared_amount": { "description": "What the captain says they are bringing. Moves nothing.", "type": "number", "format": "float", "example": 380 }, "confirmed_amount": { "description": "What the desk counted. Null until it is counted.", "type": "number", "format": "float", "example": null, "nullable": true }, "shortfall": { "description": "Declared minus confirmed. Positive means less arrived than was promised.", "type": "number", "format": "float", "example": null, "nullable": true }, "captain": { "description": "Who is bringing the cash. Present on the desk queue, where every row is a different person; absent from a captain reading their own hand-ins.", "properties": { "uuid": { "description": "A ULID — which captain is settling.", "type": "string" }, "name": { "description": "Their name, for the desk queue.", "type": "string" }, "phone": { "description": "So the desk can ring them about a declaration that never arrived.", "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "ledger_entry_uuid": { "description": "The movement the confirmation wrote — the claim and the money, linked.", "type": "string", "format": "uuid", "nullable": true }, "decided_by": { "description": "The name of whoever at the desk confirmed or declined it. Null while it waits.", "type": "string", "example": null, "nullable": true }, "decided_at": { "description": "When the desk decided. Null while it waits.", "type": "string", "format": "date-time", "nullable": true }, "captain_note": { "description": "What the captain wrote when declaring.", "type": "string", "nullable": true }, "desk_note": { "description": "What the desk wrote when deciding — usually why a count fell short, or why it was declined.", "type": "string", "nullable": true }, "created_at": { "description": "When the captain declared. How long a hand-in has been waiting is read from this.", "type": "string", "format": "date-time" } }, "type": "object" }, "City": { "description": "A city, or a district inside one, with the flat amount a captain earns for delivering there.\n\n**The tree is two deep.** A city holds districts; a district holds nothing. The depth is capped\nbecause what a captain is paid has to be explainable to that captain in one sentence.\n\n`delivery_earning` is always the figure **in force on this row**, whether it was typed here or\ncopied down from the city. `earning_source` is what says which, and it is the field an editing\nscreen turns on: a district marked `inherited` follows its city, and one marked `own` is a\ndecision somebody took that a later cascade must not silently destroy.\n\nThe geofence is a centre and a radius rather than a polygon: a hand-drawn boundary is a\nmaintenance job nobody does twice, and a radius is a figure an operations manager can correct\nfrom a map in seconds.", "properties": { "uuid": { "description": "How the area is addressed.", "type": "string", "format": "uuid" }, "name": { "description": "What the area is called — a city, or a district inside one.", "type": "string", "example": "Mezzeh" }, "is_district": { "description": "Whether this sits inside a city rather than being one. A district may set its own delivery rate or inherit its city's.", "type": "boolean", "example": true }, "parent_uuid": { "description": "The city this district belongs to. Null on a city.", "type": "string", "format": "uuid", "nullable": true }, "parent_name": { "description": "The parent city's name, so a district can be shown in full without a second lookup.", "type": "string", "example": "Damascus", "nullable": true }, "lat": { "description": "Centre of the area. A drop-off falls inside it when it lands within `radius_m` of this point.", "type": "number", "format": "float", "example": 33.50750000000000028421709430404007434844970703125 }, "lng": { "description": "Longitude of the area centre, paired with `lat`.", "type": "number", "format": "float", "example": 36.24000000000000198951966012828052043914794921875 }, "radius_m": { "description": "How far the area reaches from its centre, in metres.", "type": "integer", "example": 1000 }, "delivery_earning": { "description": "What one delivery here earns a captain.", "type": "number", "format": "float", "example": 80 }, "earning_source": { "description": "Whether `delivery_earning` was set on this area or taken from its parent city. It matters when editing: changing a city's rate moves every district still inheriting it.", "type": "string", "example": "own", "enum": [ "own", "inherited" ] }, "earning_source_label": { "description": "The source translated for the screen.", "type": "string", "example": "Its own rate" }, "is_active": { "description": "An inactive area is skipped when a drop-off is placed, and keeps its history.", "type": "boolean", "example": true }, "districts": { "description": "Present on a city read as part of the tree; null on a district.", "type": "array", "items": { "$ref": "#/components/schemas/City" }, "nullable": true }, "districts_with_own_earning": { "description": "How many districts would be overwritten by a rate change here. The dashboard warns with this rather than asking a second time.", "type": "integer", "example": 1, "nullable": true }, "created_at": { "description": "When the area was added.", "type": "string", "format": "date-time" } }, "type": "object" }, "Driver": { "description": "A captain application as exposed by the driver resources.", "properties": { "uuid": { "description": "A ULID, not a UUID, despite the format hint — how a captain is named everywhere, including in a handover request.", "type": "string", "format": "uuid", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "description": "The captain's full name. Set at registration and changed only by the back office, never from the app.", "type": "string", "example": "Abdulaziz Al Ajlan" }, "phone": { "description": "Their sign-in identity: the number the OTP goes to. Unique across the fleet and not editable from the app.", "type": "string", "example": "+966500000008" }, "email": { "description": "Optional, and the one contact detail the captain may change themselves.", "type": "string", "example": "aziz.free@example.com", "nullable": true }, "national_id": { "description": "Identity document number, unique across the fleet.", "type": "string", "example": "1000000008" }, "date_of_birth": { "description": "Back office only, like the name — the app cannot change it.", "type": "string", "format": "date", "example": "1991-11-28" }, "employment_type": { "description": "The arrangement, and it decides whether an order can be **directed** rather than offered. An employee may be told what to carry, so their orders can arrive already `accepted`; a freelancer is always offered and always free to refuse.", "type": "string", "example": "freelance", "enum": [ "employee", "freelance" ] }, "employment_type_label": { "description": "The arrangement translated for the screen.", "type": "string", "example": "Freelance captain" }, "status": { "description": "Where the application stands. Only `approved` can work; `documents_required` is the one state the app acts on, by sending fresh files to `POST /documents`.", "type": "string", "example": "approved", "enum": [ "pending", "documents_required", "approved", "rejected", "suspended" ] }, "status_label": { "description": "The status translated for the screen.", "type": "string", "example": "Approved" }, "review_note": { "description": "What the reviewer said — why documents were asked for again, or why the application was refused. Show it whenever it is present.", "type": "string", "example": null, "nullable": true }, "reviewed_at": { "description": "When the back office last decided on this application. Null while it has never been reviewed.", "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59", "nullable": true }, "can_receive_orders": { "description": "Whether this captain may be given work at all — approved, active and not suspended. **It is not a live availability flag**: a captain can be true here and still be offline. Availability lives on `GET /availability`.", "type": "boolean", "example": true }, "driving_license_number": { "description": "As printed on the licence.", "type": "string", "example": "DL-10008" }, "driving_license_expires_at": { "description": "When the licence runs out. The back office watches this and can put the captain back into `documents_required`.", "type": "string", "format": "date", "example": "2029-09-12" }, "is_active": { "description": "Whether the account is switched on. A deactivated captain cannot sign in, which is separate from being suspended and separate again from being offline.", "type": "boolean", "example": true }, "documents": { "description": "Only present when the media collection is loaded.", "properties": { "driving_license": { "description": "The licence on file. Null when none has been uploaded yet — which is what `documents_required` usually means.", "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/3/%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%85%D9%84%D8%A7%D8%A8%D8%B3.png", "nullable": true }, "profile_photo": { "description": "The captain photo on file, shown on their own profile screen.", "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/4/Mask.png", "nullable": true } }, "type": "object" }, "vehicle": { "oneOf": [ { "$ref": "#/components/schemas/Vehicle" } ], "nullable": true, "description": "The car assigned to this captain, when the relation was loaded. Null when they have none on record." }, "created_at": { "description": "When the application was submitted — not when it was approved, which is `reviewed_at`.", "type": "string", "format": "date-time", "example": "2026-09-10 08:36:47" } }, "type": "object" }, "Vehicle": { "description": "A vehicle belonging to a captain.", "properties": { "uuid": { "description": "How the vehicle is addressed.", "type": "string", "format": "uuid", "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" }, "ownership_type": { "description": "Whose car it is, and **whether the captain may edit it at all**: `POST /vehicle` answers 403 on a company car, which the back office maintains.", "type": "string", "example": "personal", "enum": [ "company_owned", "personal" ] }, "ownership_type_label": { "description": "The ownership translated for the screen.", "type": "string", "example": "Personal vehicle owned by the applicant" }, "vehicle_type": { "description": "What the captain drives. Dispatch reads it when an order needs a particular kind of vehicle.", "type": "string", "example": "car", "nullable": true, "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "vehicle_type_label": { "description": "The vehicle type translated for the screen.", "type": "string", "example": "Car", "nullable": true }, "plate_number": { "description": "The registration plate, unique across the fleet. Null on a company car the office has not filled in.", "type": "string", "example": "AZZ-8008", "nullable": true }, "brand": { "description": "Manufacturer, as the captain entered it.", "type": "string", "example": "GMC", "nullable": true }, "model": { "description": "Model name, as the captain entered it.", "type": "string", "example": "Terrain", "nullable": true }, "manufacture_year": { "description": "Year of manufacture.", "type": "integer", "example": 2021, "nullable": true }, "color": { "description": "Body colour — what a shop looks for when the captain pulls up.", "type": "string", "example": "red", "nullable": true }, "registration_number": { "description": "The registration document number.", "type": "string", "example": "REG-8008", "nullable": true }, "registration_expires_at": { "description": "When the registration runs out. `registration_status` is worked out from this.", "type": "string", "format": "date", "example": "2027-09-30", "nullable": true }, "registration_status": { "description": "Worked out on the day of the request; expiring_soon = within 30 days.", "type": "string", "example": "valid", "enum": [ "missing", "expired", "expiring_soon", "valid" ] }, "registration_status_label": { "description": "The registration status translated for the screen.", "type": "string", "example": "Valid" }, "insurance_policy_number": { "description": "The insurance policy number.", "type": "string", "example": "INS-8008", "nullable": true }, "insurance_expires_at": { "description": "When cover ends. `insurance_status` is worked out from this.", "type": "string", "format": "date", "example": "2027-02-28", "nullable": true }, "insurance_status": { "description": "Worked out on the day of the request, like the registration one; `expiring_soon` means within 30 days. Worth surfacing in the app — it is the kind of thing a captain finds out about at the roadside.", "type": "string", "example": "valid", "enum": [ "missing", "expired", "expiring_soon", "valid" ] }, "insurance_status_label": { "description": "The insurance status translated for the screen.", "type": "string", "example": "Valid" }, "driver": { "oneOf": [ { "$ref": "#/components/schemas/Driver" } ], "nullable": true, "description": "Present on the vehicle endpoints (dashboard and captain app), where the captain is loaded; absent inside a captain record." }, "created_at": { "description": "When the vehicle record was created.", "type": "string", "format": "date-time", "example": "2026-09-10 08:36:47" }, "updated_at": { "description": "When it was last changed, by the captain or the office.", "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59" }, "images": { "description": "Only present when the media collection is loaded.", "properties": { "vehicle_image": { "description": "A photo of the car itself. Null when none was uploaded.", "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/1/%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%85%D9%84%D8%A7%D8%A8%D8%B3.png", "nullable": true }, "mechanics_image": { "description": "A photo of the mechanical inspection paperwork. Null when none was uploaded.", "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/2/logo-N.png", "nullable": true } }, "type": "object" }, "is_active": { "description": "Whether the vehicle is in service. An inactive one stops its captain being offered work.", "type": "boolean", "example": true } }, "type": "object" }, "DriverAvailability": { "description": "The on/off availability state of a captain, and whether they are on a break.", "properties": { "is_online": { "description": "The availability switch.", "type": "boolean", "example": true }, "on_break": { "description": "Online, but not offered new orders. Orders already in the car are unaffected — a break stops new work, it does not hand back current work.", "type": "boolean", "example": false }, "last_seen_at": { "description": "When the captain was last heard from, which the GPS ping keeps fresh. Dispatch uses it to tell a live captain from one whose phone went flat.", "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59" }, "updated_at": { "description": "When the availability itself was last switched — not the same as `last_seen_at`, which moves on its own as the app pings.", "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59" } }, "type": "object" }, "DriverAuthResult": { "description": "The result of a successful captain verify: bearer token and the driver record.", "properties": { "token": { "description": "The bearer token for every later call. Store it; there is no refresh endpoint, and `POST /auth/logout` revokes **every** token this captain holds, not just this device.", "type": "string", "example": "28|uLwdstAxt9MYf6Id7OxQfa3wtzdwbNThS44pYkUR1f28838d" }, "driver": { "$ref": "#/components/schemas/Driver" } }, "type": "object" }, "CaptainOrder": { "description": "An order as the captain app shows it: no internal note, no captain block, plus the steps allowed now and the delivery progress.", "properties": { "uuid": { "description": "How every other endpoint addresses this order. The captain app never sees the numeric id.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" }, "order_number": { "description": "The human reference, and what the captain reads out on the phone. A wrapped order collection leg carries its parent number with a `-C` suffix.", "type": "string", "example": "ORD-100002" }, "status": { "description": "Where the order stands. Build the buttons from `next_statuses` rather than from this — an order handed to an employee captain arrives already `accepted`, so the same screen has different moves available depending on how it was assigned.", "type": "string", "example": "picked_up", "enum": [ "pending", "assigned", "accepted", "picked_up", "on_the_way", "delivered", "delivery_failed", "cancelled" ] }, "status_label": { "description": "The status in the language the request asked for, ready to print.", "type": "string", "example": "Picked up" }, "leg": { "description": "What kind of trip this is, and NULL for the ordinary order - nearly all of them. `collection` is an internal run: the captain buys goods from the suppliers and leaves them at a wrapping shop. It has no customer, takes no cash, and earns no delivery rate. Anything else - `delivery` or null - is a parcel going to a person. Do not infer this from other fields: `amount_to_collect` is null on a genuinely prepaid customer delivery too, and a collection leg's `customer_name` is the wrapping shop's name, which reads exactly like a customer's.", "type": "string", "example": null, "nullable": true, "enum": [ "collection", "delivery" ] }, "leg_label": { "description": "The same thing in the language the request asked for, ready to print on the screen.", "type": "string", "example": null, "nullable": true }, "next_statuses": { "description": "The forward steps the app may offer as buttons right now. An offered order answers [\"accepted\"] - the captain must accept before anything else. Declining is NOT in this list: it is not a forward step, and it has its own endpoint.", "type": "array", "items": { "type": "string", "enum": [ "accepted", "picked_up", "on_the_way", "delivered", "delivery_failed" ] }, "example": [ "on_the_way" ] }, "steps": { "description": "Picked up → On the way → Delivered (or Delivery failed), each with its state and time.", "type": "array", "items": { "$ref": "#/components/schemas/OrderDeliveryStep" } }, "customer_name": { "description": "Who receives the parcel. **On a collection leg this holds the wrapping shop, not a person** — it reads exactly like a customer name, so check `leg` before labelling it on a screen.", "type": "string", "example": "Khalid Al Ghamdi" }, "customer_phone": { "description": "Null on a collection leg, which has nobody to ring, and on a customer who left no number.", "type": "string", "example": "+966500000101", "nullable": true }, "customer_note": { "description": "What the customer asked for, in their words. Belongs on the door screen, not the supplier screen.", "type": "string", "example": "Call on arrival.", "nullable": true }, "pickup_address": { "description": "The first stop, mirrored from `pickups[0]` so an app that only knows about one pickup still works. With several suppliers, work through `pickups` instead.", "type": "string", "example": "Store 12, Granada Mall, Riyadh" }, "pickup_lat": { "description": "The first stop, as a coordinate. Null when the store gave an address that could not be placed on the map.", "type": "number", "format": "float", "example": 24.803625499999998993416738812811672687530517578125, "nullable": true }, "pickup_lng": { "description": "See `pickup_lat`.", "type": "number", "format": "float", "example": 46.69935459999999949332050164230167865753173828125, "nullable": true }, "dropoff_address": { "description": "The delivery address.", "type": "string", "example": "Olaya Street, Riyadh" }, "dropoff_lat": { "description": "Where the order ends: the customer, or the wrapping shop on a collection leg.", "type": "number", "format": "float", "example": 24.6887535999999983005182002671062946319580078125, "nullable": true }, "dropoff_lng": { "description": "See `dropoff_lat`.", "type": "number", "format": "float", "example": 46.680810600000000931686372496187686920166015625, "nullable": true }, "items": { "description": "Every line on the order. Where the store said which supplier each line comes from, the same lines appear again split across `pickups[].items` — show those on the stop screen, and fall back to this list when they are empty, which is still the common case.", "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "items_expected": { "description": "Sum of the product quantities.", "type": "integer", "example": 3 }, "items_collected": { "description": "Count confirmed at pickup; null for a one-tap pickup.", "type": "integer", "example": 3, "nullable": true }, "items_mismatch": { "description": "True when what was collected does not match what was expected — at any one stop, or in the total. A flag for the office, not a refusal: the order still travels.", "type": "boolean", "example": false }, "payment_method": { "description": "Whether the captain takes money at the door. A collection leg is always `prepaid`, having no customer to take it from.", "type": "string", "example": "cash_on_delivery", "enum": [ "cash_on_delivery", "prepaid" ] }, "payment_method_label": { "description": "The payment method translated for the screen.", "type": "string", "example": "Cash on delivery" }, "amount_to_collect": { "description": "**What to take from the customer at the door. Null means take nothing** — the order is prepaid, or it is a collection leg. Never read null as zero owed, and never as unknown.", "type": "number", "format": "float", "example": 92.5, "nullable": true }, "currency": { "description": "Always `SYP`. It stays in the payload because ledger balances are grouped by currency, so the field is still read even though the fleet runs on one.", "type": "string", "example": "SYP", "nullable": true }, "picked_up_at": { "description": "When the goods were collected. On a multi-supplier order the **last** stop stamps this, not the first.", "type": "string", "format": "date-time", "example": "2026-09-13 10:05:00", "nullable": true }, "on_the_way_at": { "description": "When the captain set off for the drop-off.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "delivered_at": { "description": "When it was handed over. On a collection leg this is the moment the goods reached the wrapping shop — which is what frees the delivery leg to be assigned.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "failed_at": { "description": "When the delivery was given up on.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "failed_reason": { "description": "Why it failed, in the captain's words. A reason is required to fail an order, so this is never null on one.", "type": "string", "example": null, "nullable": true }, "accepted_at": { "description": "When the captain accepted the offer. Null until they do.", "type": "string", "format": "date-time", "example": "2026-09-13 09:40:00", "nullable": true }, "offer_expires_at": { "description": "The moment an unanswered offer is taken back and the order returns to the pool. Set while the order is assigned, cleared as soon as it is accepted or declined. The app counts down to this.", "type": "string", "format": "date-time", "example": "2026-09-13 09:40:00", "nullable": true }, "proof_of_delivery": { "description": "The photo sent with the delivery. Null until the order is delivered with one.", "type": "string", "format": "uri", "example": "https://api.kapitano.shop/storage/42/doorstep.jpg", "nullable": true }, "expected_goods_cost": { "description": "What the goods should cost at the supplier: the sum of quantity x unit_price. Show it on the pickup screen so the captain confirms or corrects it. Null when no line carries a price - the store never said what the goods are worth, not that they are free.", "type": "number", "format": "float", "example": 300, "nullable": true }, "amount_paid": { "description": "What the captain reported paying the supplier. Null until the pickup names an amount.", "type": "number", "format": "float", "example": 300, "nullable": true }, "amount_variance": { "description": "amount_paid minus expected_goods_cost, signed: negative means the captain paid less than the goods came to. Show it at the end of a multi-supplier collection, when the per-stop figures are three screens back. Null when either half is unknown, because a difference from a missing number is not a difference.", "type": "number", "format": "float", "example": -4, "nullable": true }, "amount_collected": { "description": "What the captain reported taking from the customer. Null on a prepaid delivery and until delivered.", "type": "number", "format": "float", "example": 380, "nullable": true }, "handover": { "description": "A handover waiting for an answer, or null. The captain carrying the order sees who they offered it to; the receiving captain sees who is offering. Money never moves with it — whoever paid the supplier keeps that balance.", "properties": { "to_captain": { "description": "Who the order was offered to. Null on the receiving side, which already knows.", "properties": { "uuid": { "description": "A ULID — the captain identifier a handover request is addressed to.", "type": "string" }, "name": { "description": "Their name, to show on the waiting screen.", "type": "string" } }, "type": "object", "nullable": true }, "from_captain": { "description": "Who is offering the order. This is the side the receiving captain reads.", "properties": { "uuid": { "description": "A ULID — the offering captain identifier.", "type": "string" }, "name": { "description": "Their name, to show in the handover inbox.", "type": "string" } }, "type": "object", "nullable": true }, "requested_at": { "description": "When the handover was offered. There is no deadline on it — an unanswered offer waits until it is withdrawn.", "type": "string", "format": "date-time" } }, "type": "object", "nullable": true }, "pickups": { "description": "Every store this order is collected from, in visiting order. The `pickup_address`/`pickup_lat`/`pickup_lng` fields above mirror the first one; this is the list to work through when there are several, and each entry carries the uuid that PATCH /orders/{uuid}/pickups/{pickup}/collected is addressed to.", "type": "array", "items": { "$ref": "#/components/schemas/OrderPickup" } }, "pickups_pending": { "description": "How many stores are still to collect. Zero once the order is picked up.", "type": "integer", "example": 1 }, "created_at": { "description": "When the order was placed — not when it reached this captain, which is `accepted_at` and `offer_expires_at`.", "type": "string", "format": "date-time", "example": "2026-09-10 08:36:51" } }, "type": "object" }, "OrderPickup": { "description": "A store the order is collected from. An order has at least one and at most three; they are visited in `sequence` order, and all of them before the customer.", "properties": { "uuid": { "description": "Address this store with PATCH /api/driver/orders/{uuid}/pickups/{pickup}/collected.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e999" }, "sequence": { "description": "The visiting order chosen for the stops.", "type": "integer", "example": 1, "nullable": true }, "store_name": { "description": "What to show the captain as the name of this counter. Null when the store sent an address and no name.", "type": "string", "example": "Bait Al Oud", "nullable": true }, "address": { "description": "Where this counter is, for the captain to navigate to.", "type": "string", "example": "Baghdad Street, Damascus" }, "lat": { "description": "This counter as a coordinate. Null when the address could not be placed, in which case the stop is on the route by address only.", "type": "number", "format": "float", "example": 33.51380000000000336513039655983448028564453125, "nullable": true }, "lng": { "description": "Longitude of this counter, paired with `lat`.", "type": "number", "format": "float", "example": 36.27649999999999863575794734060764312744140625, "nullable": true }, "ready_at": { "description": "When the store expects the goods to be ready.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "collected": { "description": "Whether this store has been confirmed.", "type": "boolean", "example": false }, "collected_at": { "description": "When this counter was confirmed. Null while it is still outstanding.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "items_collected": { "description": "How many pieces the captain confirmed at this counter. Null when confirmed in one tap.", "type": "integer", "example": 3, "nullable": true }, "items_mismatch": { "description": "Set when the confirmed count differs from what this store was expected to hand over. A store owning no lines expects nothing and is never flagged.", "type": "boolean", "example": false }, "amount_paid": { "description": "What the captain paid at this supplier.", "type": "number", "format": "float", "example": 120, "nullable": true }, "items": { "description": "The lines collected here. Empty on an order whose items were never split by supplier, which is not the same as nothing to collect.", "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "items_expected": { "description": "The quantities of the lines assigned to this store.", "type": "integer", "example": 3 }, "expected_goods_cost": { "description": "What the lines assigned to this counter come to. The number the captain checks their own against before handing cash over - asked for a figure with nothing to compare it to, people type what the till said and never notice when the two disagree. Null when this stop owns no priced lines, and null on a delivery leg, which buys nothing.", "type": "number", "format": "float", "example": 90, "nullable": true }, "amount_variance": { "description": "amount_paid minus expected_goods_cost, signed: negative means the captain paid less than the goods came to. Null when either half is unknown, because a difference from a missing number is not a difference.", "type": "number", "format": "float", "example": -4, "nullable": true }, "order_amount": { "description": "The same payment read as the order's money rather than the captain's: cash left the company here, so it is negative. amount_paid beside it stays the positive number the captain actually typed.", "type": "number", "format": "float", "example": -90, "nullable": true } }, "type": "object" }, "OrderDeliveryStep": { "description": "One step of the delivery sequence and where it stands.", "properties": { "status": { "description": "One step of the captain's delivery progress.", "type": "string", "example": "picked_up", "enum": [ "picked_up", "on_the_way", "delivered", "delivery_failed" ] }, "label": { "description": "The step name, translated, ready to print beside the tick.", "type": "string", "example": "Picked up" }, "state": { "description": "How to draw this step: `done` behind the captain, `next` the one action open to them now, `upcoming` still ahead, `failed` where the delivery ended. Exactly one step is `next` on a live order, and none once it is finished.", "type": "string", "example": "done", "enum": [ "done", "next", "upcoming", "failed" ] }, "state_label": { "description": "The state translated for the screen.", "type": "string", "example": "Done" }, "at": { "description": "When the step happened; null until it does.", "type": "string", "format": "date-time", "example": "2026-09-13 10:05:00", "nullable": true } }, "type": "object" }, "OrderItem": { "description": "A product line inside an order.", "properties": { "uuid": { "description": "Identifies the line. Nothing in the captain API is addressed by it — confirmation is per stop, not per line.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e777" }, "name": { "description": "What the store called the product. Not unique on an order: two lines can share a name and differ only by `variant`.", "type": "string", "example": "Cotton shirt" }, "quantity": { "description": "How many pieces of this line. `items_expected` is the sum of these.", "type": "integer", "example": 2 }, "unit_price": { "description": "Price of one piece, in the order currency. **Null means the store never said**, not that it is free — which is why an order with unpriced lines reports a null `expected_goods_cost` rather than a zero one.", "type": "number", "format": "float", "example": 45, "nullable": true }, "note": { "description": "Anything the store added about this line.", "type": "string", "example": null, "nullable": true }, "sku": { "description": "The store product code, as they sent it.", "type": "string", "example": "SHIRT-RED-L", "nullable": true }, "image_url": { "description": "The store own picture of this line. A link we keep, never an address we fetch - so it is loaded by the client and may 404 if the store rotates it.", "type": "string", "format": "uri", "example": "https://cdn.example.sy/shirt-red.jpg", "nullable": true }, "variant": { "description": "What distinguishes this line from another with the same name. Draw it beside the name - a captain confirming two of a shirt cannot otherwise tell the red large from the blue small, and finds out at the customer door.", "type": "object", "example": { "color": "red", "size": "L" }, "nullable": true, "additionalProperties": { "type": "string" } } }, "type": "object" }, "RoutePlan": { "description": "One version of a captain's route: the stops left, the line to draw and the arrival times. Render only the highest version you have seen.", "properties": { "uuid": { "description": "Identifies this plan. The push that announces a new route carries it as `route_plan_uuid`.", "type": "string", "format": "uuid", "example": "01a0b41c-7d2e-73a1-9c44-2f8b5d6e9a10" }, "version": { "description": "Climbs by one on every recompute. Keep the highest you have seen and ignore anything lower — a frame or a push can arrive after a newer one.", "type": "integer", "example": 3 }, "trigger": { "description": "What caused this version.", "type": "string", "example": "assigned", "enum": [ "assigned", "stop_completed", "deviation", "manual_reorder" ] }, "trigger_label": { "description": "The trigger translated for the screen.", "type": "string", "example": "Order assigned" }, "stops": { "description": "In visiting order. Only what is left to do: a collected store and a delivered customer are gone.", "type": "array", "items": { "$ref": "#/components/schemas/RoutePlanStop" } }, "polyline": { "description": "The encoded line to draw. Null when degraded — draw the stop list instead of an invented route.", "type": "string", "example": "yzlkEuvdyE...", "nullable": true }, "total_seconds": { "description": "The whole route end to end. An estimate rather than a measurement when `degraded` is true.", "type": "integer", "example": 1420 }, "total_meters": { "description": "The whole route in metres, on the same terms as `total_seconds`.", "type": "integer", "example": 8600 }, "routing_engine": { "description": "Which service drew the route. `fake` only appears in development, where the polyline is straight segments rather than roads — useful to know when a test route looks wrong.", "type": "string", "example": "google", "enum": [ "fake", "google", "osrm" ] }, "degraded": { "description": "True when the map service could not answer: the stops and their order are right, the times are estimates and there is no line.", "type": "boolean", "example": false }, "computed_at": { "description": "When this version was worked out. The arrival times are counted from here, so a plan left open on screen grows stale against the clock.", "type": "string", "format": "date-time", "example": "2026-09-19T14:05:00+03:00" } }, "type": "object" }, "RoutePlanStop": { "description": "One place the captain still has to be. The leg is the hop that leads *to* this stop, so the times add up along the route.", "properties": { "key": { "description": "The stop's stable name, used when a dispatcher reorders the route. Positions are not names: the route can be recomputed between a screen being drawn and a reorder arriving.", "type": "string", "example": "pickup:41" }, "type": { "description": "Whether the captain is collecting here or handing over. On a collection leg the pickups are the suppliers and the drop-off is the wrapping shop.", "type": "string", "example": "pickup", "enum": [ "pickup", "dropoff" ] }, "order_id": { "description": "Internal numeric id of the order this stop belongs to. **Not the uuid the captain API uses elsewhere**, so it cannot be matched against an order read from `GET /orders`.", "type": "integer", "example": 812 }, "pickup_id": { "description": "Internal numeric id of the stop, on the same terms as `order_id`. Null on a drop-off.", "type": "integer", "example": 41, "nullable": true }, "lat": { "description": "Where to drive. This and `lng` are what the app pins on the map.", "type": "number", "format": "float", "example": 24.7135999999999995679900166578590869903564453125 }, "lng": { "description": "Longitude of the stop, paired with `lat`.", "type": "number", "format": "float", "example": 46.67530000000000001136868377216160297393798828125 }, "leg_seconds": { "description": "Time from the previous stop — from the captain's position for the first one.", "type": "integer", "example": 420 }, "leg_meters": { "description": "Distance of that same hop, in metres.", "type": "integer", "example": 2300 }, "eta_at": { "description": "When the captain should arrive here.", "type": "string", "format": "date-time", "example": "2026-09-19T14:12:00+03:00" } }, "type": "object" } }, "securitySchemes": { "driverAuth": { "type": "http", "description": "Bearer token issued by POST /api/driver/auth/verify. Enter in format (Bearer ).", "bearerFormat": "Sanctum", "scheme": "bearer" } } }, "tags": [ { "name": "Captain App — Authentication", "description": "Self-registration, OTP sign in and session end." }, { "name": "Captain App — Profile", "description": "The signed in captain's own record." }, { "name": "Captain App — Documents", "description": "Re-uploading the documents management asked for when it sent the application back." }, { "name": "Captain App — Vehicle", "description": "The signed in captain's own vehicle: view it, and update it when it is their own car." }, { "name": "Captain App — Orders", "description": "The orders offered to the signed in captain: list, full detail, answering an offer (accept / decline), and the delivery steps. See \"The delivery flow\" above — the app must call accept before it can collect a parcel." }, { "name": "Captain App — Handover", "description": "Passing an order already in a car to another captain: offer, inbox, accept, decline, withdraw. The money stays with whoever spent it." }, { "name": "Captain App — Ledger", "description": "The signed in captain's own money: what they are owed or owe, every movement behind it, and\nhanding the company's cash back in.\n\n**Declaring a hand-in clears nothing.** It puts the captain on the desk's queue; the balance\nreaches zero when somebody counts the notes and confirms. An app that hides the balance the\nmoment the button is pressed would be telling a captain they are square while they are still\ncarrying the cash." }, { "name": "Captain App — Presence", "description": "The availability switch and live location reporting.\n\n**Read availability on launch** (`GET /api/driver/availability`) rather than assuming it. The\nswitch survives a restart, a reinstall and a second handset, so an app that assumes offline\neither shows the wrong state or writes one the captain never asked for." }, { "name": "Captain App — Device Token", "description": "Register / forget the FCM push token." }, { "name": "Captain App — Route", "description": "Captain App — Route" } ] }