{ "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 the parcel | `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\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### 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\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": "SAR", "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": "SAR" } ], "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": { "SAR": 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 status. Answers in the pagination envelope: `Model` is the array of orders, `Total` the number of pages, `Page` the current page and `Records` the record count.", "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": "SAR", "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": "Customer name and phone, pickup and delivery addresses, product list, customer notes, payment method and amount to collect. This is what the new-order push (`data.order_uuid`) opens. Another captain's order answers 403.", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": "SAR", "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": { "type": "string", "example": "Unauthorized", "nullable": true }, "MessageDebug": { "description": "Diagnostic detail (unauthorized / accept_header / language)." } }, "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": { "type": "string", "example": null, "nullable": true }, "MessageDebug": { "description": "Diagnostic detail (reason / permission message)." } }, "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": { "type": "string", "example": "The item not found" }, "MessageDebug": { "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": { "type": "string", "example": "The item already exists." }, "MessageDebug": { "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": { "type": "string", "example": "Your application is under review." }, "MessageDebug": { "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": { "type": "string", "example": "Too many requests, please slow down and try again shortly" }, "MessageDebug": { "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": { "type": "string", "example": "supplier_payment", "enum": [ "supplier_payment", "cash_collected", "cash_paid_out", "cash_handed_in", "adjustment" ] }, "type_label": { "type": "string", "example": "Paid supplier" }, "amount": { "description": "Signed. Positive = the company owes the captain.", "type": "number", "format": "float", "example": 300 }, "balance_after": { "type": "number", "format": "float", "example": 300 }, "currency": { "type": "string", "example": "SAR" }, "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": { "type": "boolean", "example": false }, "order": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string", "example": "ORD-100002" } }, "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": "ULID", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "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": { "type": "string", "example": "captain", "enum": [ "captain", "back_office", "other" ] }, "name": { "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": { "type": "string", "example": null, "nullable": true }, "created_at": { "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 }, "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. The parts above add up to exactly this.", "type": "number", "format": "float", "example": -60 } }, "type": "object" }, "CaptainOrderEnvelope": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainOrder" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "nullable": true }, "MessageDebug": { "example": null, "nullable": true }, "Total": { "type": "integer", "example": 0 }, "Page": { "type": "integer", "example": 0 }, "Records": { "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": "A captain's declared cash hand-in.", "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "confirmed", "declined", "cancelled" ] }, "status_label": { "type": "string", "example": "Waiting for the desk" }, "currency": { "type": "string", "example": "SAR" }, "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": { "properties": { "uuid": { "description": "ULID", "type": "string" }, "name": { "type": "string" }, "phone": { "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": { "type": "string", "example": null, "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "captain_note": { "type": "string", "nullable": true }, "desk_note": { "type": "string", "nullable": true }, "created_at": { "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": "A delivery area and what a delivery there earns a captain.", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Mezzeh" }, "is_district": { "type": "boolean", "example": true }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "parent_name": { "type": "string", "example": "Damascus", "nullable": true }, "lat": { "type": "number", "format": "float", "example": 33.50750000000000028421709430404007434844970703125 }, "lng": { "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": 8000 }, "earning_source": { "type": "string", "example": "own", "enum": [ "own", "inherited" ] }, "earning_source_label": { "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": { "type": "string", "format": "date-time" } }, "type": "object" }, "Driver": { "description": "A captain application as exposed by the driver resources.", "properties": { "uuid": { "description": "A captain as exposed by DriverResource: the application record, its review state, the\ndocuments and, when loaded, the assigned vehicle.", "type": "string", "format": "uuid", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "type": "string", "example": "Abdulaziz Al Ajlan" }, "phone": { "type": "string", "example": "+966500000008" }, "email": { "type": "string", "example": "aziz.free@example.com", "nullable": true }, "national_id": { "type": "string", "example": "1000000008" }, "date_of_birth": { "type": "string", "format": "date", "example": "1991-11-28" }, "employment_type": { "type": "string", "example": "freelance", "enum": [ "employee", "freelance" ] }, "employment_type_label": { "type": "string", "example": "Freelance captain" }, "status": { "type": "string", "example": "approved", "enum": [ "pending", "documents_required", "approved", "rejected", "suspended" ] }, "status_label": { "type": "string", "example": "Approved" }, "review_note": { "type": "string", "example": null, "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59", "nullable": true }, "can_receive_orders": { "type": "boolean", "example": true }, "driving_license_number": { "type": "string", "example": "DL-10008" }, "driving_license_expires_at": { "type": "string", "format": "date", "example": "2029-09-12" }, "is_active": { "type": "boolean", "example": true }, "documents": { "description": "Only present when the media collection is loaded.", "properties": { "driving_license": { "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": { "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 }, "created_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": "A vehicle record: ownership type plus, for personal vehicles, the plate and appearance.", "type": "string", "format": "uuid", "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" }, "ownership_type": { "type": "string", "example": "personal", "enum": [ "company_owned", "personal" ] }, "ownership_type_label": { "type": "string", "example": "Personal vehicle owned by the applicant" }, "vehicle_type": { "type": "string", "example": "car", "nullable": true, "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "vehicle_type_label": { "type": "string", "example": "Car", "nullable": true }, "plate_number": { "type": "string", "example": "AZZ-8008", "nullable": true }, "brand": { "type": "string", "example": "GMC", "nullable": true }, "model": { "type": "string", "example": "Terrain", "nullable": true }, "manufacture_year": { "type": "integer", "example": 2021, "nullable": true }, "color": { "type": "string", "example": "red", "nullable": true }, "registration_number": { "type": "string", "example": "REG-8008", "nullable": true }, "registration_expires_at": { "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": { "type": "string", "example": "Valid" }, "insurance_policy_number": { "type": "string", "example": "INS-8008", "nullable": true }, "insurance_expires_at": { "type": "string", "format": "date", "example": "2027-02-28", "nullable": true }, "insurance_status": { "type": "string", "example": "valid", "enum": [ "missing", "expired", "expiring_soon", "valid" ] }, "insurance_status_label": { "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": { "type": "string", "format": "date-time", "example": "2026-09-10 08:36:47" }, "updated_at": { "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": { "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": { "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": { "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.", "type": "boolean", "example": false }, "last_seen_at": { "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59" }, "updated_at": { "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 token plus the account issued after sign in.", "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": "An order as the captain carrying it sees it.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" }, "order_number": { "type": "string", "example": "ORD-100002" }, "status": { "type": "string", "example": "picked_up", "enum": [ "pending", "assigned", "accepted", "picked_up", "on_the_way", "delivered", "delivery_failed", "cancelled" ] }, "status_label": { "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": { "type": "string", "example": "Khalid Al Ghamdi" }, "customer_phone": { "type": "string", "example": "+966500000101", "nullable": true }, "customer_note": { "type": "string", "example": "Call on arrival.", "nullable": true }, "pickup_address": { "type": "string", "example": "Store 12, Granada Mall, Riyadh" }, "pickup_lat": { "type": "number", "format": "float", "example": 24.803625499999998993416738812811672687530517578125, "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "example": 46.69935459999999949332050164230167865753173828125, "nullable": true }, "dropoff_address": { "description": "The delivery address.", "type": "string", "example": "Olaya Street, Riyadh" }, "dropoff_lat": { "type": "number", "format": "float", "example": 24.6887535999999983005182002671062946319580078125, "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "example": 46.680810600000000931686372496187686920166015625, "nullable": true }, "items": { "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": { "type": "boolean", "example": false }, "payment_method": { "type": "string", "example": "cash_on_delivery", "enum": [ "cash_on_delivery", "prepaid" ] }, "payment_method_label": { "type": "string", "example": "Cash on delivery" }, "amount_to_collect": { "type": "number", "format": "float", "example": 92.5, "nullable": true }, "currency": { "type": "string", "example": "SAR", "nullable": true }, "picked_up_at": { "type": "string", "format": "date-time", "nullable": true }, "on_the_way_at": { "type": "string", "format": "date-time", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_reason": { "type": "string", "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_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.", "properties": { "to_captain": { "properties": { "uuid": { "description": "ULID", "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "from_captain": { "properties": { "uuid": { "description": "ULID", "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "requested_at": { "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": { "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": { "type": "string", "example": "Bait Al Oud", "nullable": true }, "address": { "type": "string", "example": "Baghdad Street, Damascus" }, "lat": { "type": "number", "format": "float", "example": 33.51380000000000336513039655983448028564453125, "nullable": true }, "lng": { "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": { "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": { "type": "string", "example": "Picked up" }, "state": { "type": "string", "example": "done", "enum": [ "done", "next", "upcoming", "failed" ] }, "state_label": { "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": "A line item inside an order.", "type": "string", "format": "uuid" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number", "format": "float", "nullable": true }, "note": { "type": "string", "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": { "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": { "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": { "type": "integer", "example": 1420 }, "total_meters": { "type": "integer", "example": 8600 }, "routing_engine": { "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": { "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": { "type": "string", "example": "pickup", "enum": [ "pickup", "dropoff" ] }, "order_id": { "type": "integer", "example": 812 }, "pickup_id": { "description": "Null on a drop-off.", "type": "integer", "example": 41, "nullable": true }, "lat": { "type": "number", "format": "float", "example": 24.7135999999999995679900166578590869903564453125 }, "lng": { "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": { "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" } ] }