{ "openapi": "3.0.0", "info": { "title": "Kapitano — Dashboard API", "description": "The Kapitano Logistic **dashboard API** (`/api/dashboard/*`) used by the back office:\nadmin sign in, admin & role management, the captain review queue, vehicle management,\norder assignment with nearest-first captain suggestions, and push notifications.\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 dashboard endpoint takes the `adminAuth` bearer token\nissued by `POST /api/dashboard/auth/login` (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.", "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/dashboard/admins": { "get": { "tags": [ "Dashboard — Admins" ], "summary": "List the back office accounts", "description": "Paginated. Filters: search by name/email/phone, is_active, role name. Requires `admins.view`.", "operationId": "adminIndex", "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": "search", "in": "query", "schema": { "type": "string", "nullable": true, "maxLength": 255 } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "role", "in": "query", "schema": { "type": "string", "example": "operations-manager" } } ], "responses": { "200": { "description": "A page of admins.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/Admin" } }, "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": "Missing admins.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Missing/invalid page or rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Admins" ], "summary": "Create a back office account", "description": "Creates the account and grants the roles sent with it. Requires `admins.create`.", "operationId": "adminStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Monte Kilback", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "enrique.walker@example.org", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500379188" }, "password": { "type": "string", "example": "123456" }, "password_confirmation": { "type": "string", "example": "123456" }, "date_of_birth": { "type": "string", "format": "date", "example": "1979-09-23", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "operations-manager" ], "minItems": 1 } }, "type": "object" }, "example": { "name": "Monte Kilback", "email": "enrique.walker@example.org", "phone": "+966500379188", "password": "123456", "password_confirmation": "123456", "date_of_birth": "1979-09-23", "is_active": true, "roles": [ "operations-manager" ] } } } }, "responses": { "201": { "description": "Account created.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": "Missing admins.create permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/admins/{uuid}": { "get": { "tags": [ "Dashboard — Admins" ], "summary": "One back office account", "description": "With the roles held and the permissions they grant. Requires `admins.view`. Admin records use UUIDs.", "operationId": "adminShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a08600-86f8-72c5-9307-feeac9ae0b5b" } } ], "responses": { "200": { "description": "The admin record.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": "Missing admins.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Admin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Admins" ], "summary": "Change a back office account", "description": "Updates the sent fields and syncs the roles. Requires `admins.update`.", "operationId": "adminUpdate", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a08600-86f8-72c5-9307-feeac9ae0b5b" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Monte Kilback", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "enrique.walker@example.org", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500379188" }, "date_of_birth": { "type": "string", "format": "date", "example": "1979-09-23", "nullable": true }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "operations-manager" ], "minItems": 1 } }, "type": "object" }, "example": { "name": "Monte Kilback", "email": "enrique.walker@example.org", "phone": "+966500379188", "date_of_birth": "1979-09-23", "roles": [ "operations-manager" ] } } } }, "responses": { "200": { "description": "Account updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": "Missing admins.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Admin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/admins/{uuid}/activation": { "patch": { "tags": [ "Dashboard — Admins" ], "summary": "Activate or deactivate an account", "description": "Turns the account on, or off together with every session it is signed in from. Requires `admins.update`.", "operationId": "adminToggleActivation", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a08600-86f8-72c5-9307-feeac9ae0b5b" } } ], "responses": { "200": { "description": "State changed.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": "Missing admins.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Admin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/auth/login": { "post": { "tags": [ "Dashboard — Authentication" ], "summary": "Sign in to the dashboard", "description": "Exchanges an email and password for a Sanctum token plus the admin record. Throttle\n`admin-auth`: 5 requests per minute per email **and** per IP. A disabled account or\nwrong credentials are refused with their own status.", "operationId": "adminLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com", "maxLength": 255 }, "password": { "type": "string", "example": "123456" }, "device_name": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" }, "example": { "email": "super-admin@kapitano-logiistic.com", "password": "123456" } } } }, "responses": { "200": { "description": "Signed in.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/AdminAuthResult" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Signed in successfully" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials (or headers missing).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Email not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "429": { "description": "admin-auth throttle (5/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/dashboard/auth/logout": { "post": { "tags": [ "Dashboard — Authentication" ], "summary": "Sign out", "description": "Revokes every Sanctum token the signed in admin holds.", "operationId": "adminLogout", "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": [ { "adminAuth": [] } ] } }, "/api/dashboard/auth/forgot-password": { "post": { "tags": [ "Dashboard — Authentication" ], "summary": "Send a password reset code", "description": "Sends a code to the phone number on the admin record so they can set a new password.", "operationId": "adminForgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com", "maxLength": 255 } }, "type": "object" }, "example": { "email": "super-admin@kapitano-logiistic.com" } } } }, "responses": { "200": { "description": "Code sent." }, "401": { "description": "headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Email not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "429": { "description": "admin-auth throttle (5/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/dashboard/auth/resend-code": { "post": { "tags": [ "Dashboard — Authentication" ], "summary": "Resend the password reset code", "description": "Sends the code again to the same phone number, for an admin who never received the first one.", "operationId": "adminResendCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com", "maxLength": 255 } }, "type": "object" }, "example": { "email": "super-admin@kapitano-logiistic.com" } } } }, "responses": { "200": { "description": "New code sent." }, "401": { "description": "headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Email not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "429": { "description": "admin-auth throttle (5/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/dashboard/auth/reset-password": { "post": { "tags": [ "Dashboard — Authentication" ], "summary": "Set a new password with the code", "description": "Sets the new password once the code checks out. Password must be confirmed.", "operationId": "adminResetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com", "maxLength": 255 }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "example": "257843" }, "password": { "type": "string", "example": "123456" }, "password_confirmation": { "type": "string", "example": "123456" } }, "type": "object" }, "example": { "email": "super-admin@kapitano-logiistic.com", "code": "257843", "password": "123456", "password_confirmation": "123456" } } } }, "responses": { "200": { "description": "Password reset." }, "401": { "description": "headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Disabled account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Email not registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Code wrong/expired/exhausted or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } }, "429": { "description": "admin-auth throttle (5/min).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorTooManyRequests" } } } } }, "security": [] } }, "/api/dashboard/captain-ledger": { "get": { "tags": [ "Dashboard — Cash Desk" ], "summary": "Who owes and who is owed", "description": "The desk's main screen: one row per captain per currency, **largest amount first whichever\ndirection** — a captain holding 2,000 of the company's cash matters more than one owed 15.\n\nEach row carries `settle_with`, the movement that brings that captain back to zero, so the\nscreen offers \"pay out\" or \"take cash\" without the cashier working out which.\n\n`Totals` is the headline per currency: how much the company owes captains, how much\ncaptains owe it, and how many are on each side. Each captain is netted first — a captain\nwho paid 300 and collected 380 counts once, as owing 80.\n\nRequires `captain_ledger.view`.", "operationId": "captainLedgerDesk", "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": "state", "in": "query", "description": "`owed` — the desk pays out; `owes` — the desk takes cash in; `clear` — square.", "required": false, "schema": { "type": "string", "enum": [ "owed", "owes", "clear" ] } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "example": "SAR" } ], "responses": { "200": { "description": "A page of balances, and the totals.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainBalance" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Pages.", "type": "integer", "example": 1 }, "Page": { "type": "integer", "example": 1 }, "Records": { "type": "integer", "example": 2 }, "Totals": { "description": "currency => totals", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CaptainLedgerTotals" } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "`rows`/`page` missing, or an unknown `state`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/captain-ledger/entries": { "get": { "tags": [ "Dashboard — Cash Desk" ], "summary": "Every movement of money, newest first", "description": "The audit trail behind the balances: every line written for any captain, newest first, with\nthe captain named on each row.\n\n**This is a different question from the desk's list.** That one says where money is sitting\nnow; this one says what happened. A captain who took 5,000 and handed 5,000 back this\nmorning has a balance of zero, and the balances list has nothing to say about their day.\n\n`Totals` follows the filters and reports money **in and out separately** rather than netted,\nper currency, because the day above nets to nothing and a cashier needs the two figures.\n\nFilters: `type`, `currency`, `captain_uuid` (a ULID), `order_uuid`, and a `from`/`to` window\nthat covers the whole of both days it names. A filter naming a captain or an order that does\nnot exist answers with an empty page — not with every row.\n\nRequires `captain_ledger.view`.", "operationId": "captainLedgerFeed", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "supplier_payment", "cash_collected", "cash_paid_out", "cash_handed_in", "adjustment" ] } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "example": "SAR" }, { "name": "captain_uuid", "in": "query", "description": "Captain ULID.", "required": false, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" }, { "name": "order_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive, from the start of that day.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Inclusive, to the end of that day.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A page of movements, and what they add up to.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainLedgerEntry" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Pages.", "type": "integer", "example": 3 }, "Page": { "type": "integer", "example": 1 }, "Records": { "type": "integer", "example": 64 }, "Totals": { "description": "currency => what the filtered set moved", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CaptainLedgerFeedTotals" } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "`rows`/`page` missing, an unknown `type`, or `to` before `from`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/captains/{uuid}/ledger": { "get": { "tags": [ "Dashboard — Cash Desk" ], "summary": "One captain: balance and every movement", "description": "The captain's balance in every currency (`Balances`) and the statement behind it, newest\nfirst. Each line says who recorded it — the captain on their phone, or the back office —\nand, for delivery lines, what was expected beside what happened.\n\n`{uuid}` is the captain's **ULID**. Requires `captain_ledger.view`.", "operationId": "captainLedgerStatement", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" }, { "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 } } ], "responses": { "200": { "description": "The statement.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CaptainLedgerEntry" } }, "Status": { "type": "boolean", "example": true }, "Records": { "type": "integer", "example": 4 }, "Captain": { "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "Balances": { "description": "currency => balance", "type": "object", "example": { "SAR": 300 } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/captains/{uuid}/ledger/settle": { "post": { "tags": [ "Dashboard — Cash Desk" ], "summary": "Pay a captain out, or take cash from them", "description": "Records cash changing hands at the desk. **Only towards zero, and never past it:**\n\n| Captain is | `direction` | `amount` may be |\n|---|---|---|\n| owed | `cash_paid_out` | up to what they are owed |\n| owing | `cash_handed_in` | up to what they owe |\n\nPartial settlement is fine — the drawer may not hold the full amount. The wrong direction,\nmore than the balance, or a captain who is already square all answer **422** and write\nnothing. Each is a silent mistake otherwise: paying a captain who owes turns their debt\ninto a credit.\n\nThe balance is checked under a lock on the captain, so two cashiers settling the same\ncaptain at once cannot both pay.\n\n`currency` defaults to `SAR`. `reference` is the voucher or receipt number.\nRequires `captain_ledger.settle`.", "operationId": "captainLedgerSettle", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "direction", "amount" ], "properties": { "direction": { "type": "string", "example": "cash_paid_out", "enum": [ "cash_paid_out", "cash_handed_in" ] }, "amount": { "type": "number", "format": "float", "example": 300, "maximum": 999999.98999999999068677425384521484375, "minimum": 0.01000000000000000020816681711721685132943093776702880859375 }, "currency": { "type": "string", "example": "SAR", "nullable": true, "maxLength": 3, "minLength": 3 }, "reference": { "type": "string", "example": "VCH-2001", "nullable": true, "maxLength": 100 }, "note": { "type": "string", "example": null, "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Recorded. `Model` is the new ledger line.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainLedgerEntry" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The cash movement has been recorded." } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.settle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Wrong direction for this captain, more than the balance, nothing outstanding, or invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/captains/{uuid}/ledger/adjust": { "post": { "tags": [ "Dashboard — Cash Desk" ], "summary": "Correct a captain's balance, with a reason", "description": "The ledger is append-only, so this is the only way a wrong entry is ever put right: not by\nediting it, but by a second line beside it that says what it corrects.\n\n`amount` is **signed** — positive credits the captain, negative debits them — because a\ncorrection is the one entry whose direction is not implied by what happened. `note` is\nrequired: a balance that moved for a reason nobody wrote down is worse than one that never\nmoved.\n\nRequires `captain_ledger.settle`.", "operationId": "captainLedgerAdjust", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount", "note" ], "properties": { "amount": { "description": "Signed; not zero.", "type": "number", "format": "float", "example": 20 }, "note": { "type": "string", "example": "Customer paid 360, captain mis-entered 380.", "maxLength": 255, "minLength": 3 }, "currency": { "type": "string", "example": "SAR", "nullable": true, "maxLength": 3, "minLength": 3 }, "reference": { "type": "string", "nullable": true, "maxLength": 100 } }, "type": "object" } } } }, "responses": { "201": { "description": "Recorded.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CaptainLedgerEntry" }, "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": "Missing captain_ledger.settle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "No reason, or a zero amount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers": { "get": { "tags": [ "Dashboard — Captains" ], "summary": "Review queue / captain list", "description": "Paginated. Filters: search, status, employment_type, ownership_type, is_active. Requires `drivers.view`. Captain records use ULIDs.", "operationId": "captainIndex", "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": "search", "in": "query", "description": "Name, email, phone or national id.", "schema": { "type": "string", "nullable": true, "maxLength": 255 } }, { "name": "status", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "pending", "documents_required", "approved", "rejected", "suspended" ] } }, { "name": "employment_type", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "employee", "freelance" ] } }, { "name": "ownership_type", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "company_owned", "personal" ] } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of captains.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$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" } } } }, "403": { "description": "Missing drivers.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Missing/invalid page or rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers/{uuid}": { "get": { "tags": [ "Dashboard — Captains" ], "summary": "One captain application", "description": "The full application: personal data, documents, vehicle, review fields. Requires `drivers.view`.", "operationId": "captainShow", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "responses": { "200": { "description": "The application.", "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" } } } }, "403": { "description": "Missing drivers.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Captains" ], "summary": "Correct a captain's record", "description": "Updates the sent fields. Phone, email and national id must stay unique. Requires `drivers.update`.", "operationId": "captainUpdate", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "Nasser Al Otaibi", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+966500000002" }, "email": { "type": "string", "format": "email", "example": "nasser.employee@example.com", "nullable": true, "maxLength": 255 }, "national_id": { "type": "string", "example": "1000000002", "maxLength": 50 }, "date_of_birth": { "description": "Must be before today.", "type": "string", "format": "date", "example": "1988-09-23" }, "employment_type": { "type": "string", "example": "employee", "enum": [ "employee", "freelance" ] }, "driving_license_number": { "type": "string", "example": "DL-10002", "maxLength": 50 }, "driving_license_expires_at": { "description": "Must be after today.", "type": "string", "format": "date", "example": "2029-09-12" } }, "type": "object" }, "example": { "name": "Nasser Al Otaibi", "phone": "+966500000002", "email": "nasser.employee@example.com", "national_id": "1000000002", "date_of_birth": "1988-09-23", "employment_type": "employee", "driving_license_number": "DL-10002", "driving_license_expires_at": "2029-09-12" } } } }, "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" } } } }, "403": { "description": "Missing drivers.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers/{uuid}/activation": { "patch": { "tags": [ "Dashboard — Captains" ], "summary": "Activate or deactivate a captain", "description": "Turns the account on, or off together with every session the app is signed in from. Requires `drivers.update`.", "operationId": "captainToggleActivation", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "responses": { "200": { "description": "State changed.", "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" } } } }, "403": { "description": "Missing drivers.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers/{uuid}/approve": { "patch": { "tags": [ "Dashboard — Captains" ], "summary": "Approve an application", "description": "Approves the application. Company-owned vehicles must be handed over (the `vehicle`\nblock is required for them); personal vehicles are optional — an empty vehicle object\nis treated as \"no car sent\". Approval is final: an approved captain can no longer be\nrejected, only deactivated. Requires `drivers.review`.", "operationId": "captainApprove", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "vehicle": { "properties": { "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 } }, "type": "object" } }, "type": "object" }, "example": { "vehicle": { "plate_number": "AZZ-8008", "brand": "GMC", "model": "Terrain", "manufacture_year": 2021, "color": "red" } } } } }, "responses": { "200": { "description": "Application approved.", "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" } } } }, "403": { "description": "Missing drivers.review permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "Already decided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Illegal transition or missing company vehicle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers/{uuid}/reject": { "patch": { "tags": [ "Dashboard — Captains" ], "summary": "Reject an application", "description": "Turns the application down on the reason sent. A rejected captain may still be reconsidered later. Requires `drivers.review`.", "operationId": "captainReject", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "review_note": { "type": "string", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Application rejected.", "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" } } } }, "403": { "description": "Missing drivers.review permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "Already decided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Illegal transition or missing note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/drivers/{uuid}/request-documents": { "patch": { "tags": [ "Dashboard — Captains" ], "summary": "Request missing documents", "description": "Sends the application back, naming what is missing in the note. Requires `drivers.review`.", "operationId": "captainRequestDocuments", "parameters": [ { "name": "uuid", "in": "path", "description": "Captain ULID.", "required": true, "schema": { "type": "string" }, "example": "01m24x34bzfbh7resdmkm55mmq" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "review_note": { "type": "string", "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Documents requested.", "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" } } } }, "403": { "description": "Missing drivers.review permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "Already decided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Illegal transition or missing note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/dispatch/settings": { "get": { "tags": [ "Dashboard — Dispatch" ], "summary": "Dispatch settings", "description": "The business values the captain dispatch algorithm runs on.\n\n- `editable`: the values the operations team may change — the handoff buffers and the\n batch detour limit — each with the value that applies now, its config default, the\n range it may be set to, and whether it was overridden (by whom, when).\n- `effective`: every value the algorithm currently uses, overrides applied.\n\nOverrides are cached for 60 seconds; a change made through the PUT applies at once.\nRequires `dispatch.view`.", "operationId": "dispatchSettingsShow", "responses": { "200": { "description": "The settings.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "editable": { "type": "array", "items": { "properties": { "key": { "type": "string", "example": "offer_timeout_s", "enum": [ "handoff_buffer_prepaid_min", "handoff_buffer_cod_min", "max_batch_detour_min", "offer_timeout_s" ] }, "label": { "type": "string", "example": "Maximum batch detour (minutes)" }, "value": { "type": "number", "example": 6 }, "default": { "type": "number", "example": 6 }, "min": { "type": "number", "example": 0 }, "max": { "type": "number", "example": 20 }, "overridden": { "type": "boolean", "example": false }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_by": { "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "effective": { "properties": { "max_active_orders": { "type": "integer", "example": 2 }, "radius_steps_km": { "type": "array", "items": { "type": "number" }, "example": [ 5, 8, 12 ] }, "top_n": { "type": "integer", "example": 7 }, "detour_index": { "type": "number", "example": 1.3000000000000000444089209850062616169452667236328125 }, "handoff_buffer_prepaid_min": { "type": "number", "example": 3 }, "handoff_buffer_cod_min": { "type": "number", "example": 5 }, "gps_aging_min": { "type": "number", "example": 1.5 }, "gps_stale_min": { "type": "number", "example": 3 }, "routing_timeout_ms": { "type": "integer", "example": 1000 }, "suggestion_cache_ttl_s": { "type": "integer", "example": 75 }, "max_batch_detour_min": { "type": "number", "example": 6 }, "offer_timeout_s": { "description": "How long an offered order waits for the captain to answer.", "type": "integer", "example": 60 }, "tie_break_band_min": { "type": "number", "example": 2 }, "reroute_deviation_m": { "type": "integer", "example": 250 }, "reroute_deviation_s": { "type": "integer", "example": 30 }, "assign_lock_ttl_s": { "type": "integer", "example": 30 }, "ping_moving_s": { "type": "integer", "example": 8 }, "ping_stationary_s": { "type": "integer", "example": 45 }, "moving_speed_mps": { "type": "number", "example": 2 }, "gps_history_flush_batch": { "type": "integer", "example": 1000 }, "gps_history_retention_days": { "type": "integer", "example": 30 }, "routing_engine": { "type": "string", "example": "fake", "enum": [ "fake", "google", "osrm" ] }, "batch_rejected_policy": { "type": "string", "example": "rank_lower", "enum": [ "rank_lower", "exclude" ] } }, "type": "object" } }, "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" } } } }, "403": { "description": "Missing dispatch.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Dispatch" ], "summary": "Change dispatch settings", "description": "Overrides the editable values sent (JSON); a key left out is not touched, a key sent as\n`null` is reset to its config default. At least one editable key must be sent, each\nwithin its range. The answer is the same body as the GET, with the new values applied.\nRequires `dispatch.settings`.", "operationId": "dispatchSettingsUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "handoff_buffer_prepaid_min": { "type": "number", "example": 3, "nullable": true, "maximum": 15, "minimum": 0 }, "handoff_buffer_cod_min": { "type": "number", "example": 5, "nullable": true, "maximum": 15, "minimum": 0 }, "max_batch_detour_min": { "type": "number", "example": 7, "nullable": true, "maximum": 20, "minimum": 0 }, "offer_timeout_s": { "description": "Seconds a captain has to accept. Bounded at both ends: under the floor an offer is taken back from a captain still reaching for their phone — and that counts as a refusal against them — while over the ceiling a customer waits a quarter of an hour on somebody who will never answer.", "type": "integer", "example": 120, "nullable": true, "maximum": 900, "minimum": 30 } }, "type": "object" } } } }, "responses": { "200": { "description": "Settings updated; the body is the GET body.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "object" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Dispatch settings updated." } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing dispatch.settings permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "No editable key sent, or a value out of its range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/dispatch/live": { "get": { "tags": [ "Dashboard — Dispatch" ], "summary": "Where the fleet is, right now", "description": "Every approved captain who is on duty, with their last known position, what they are\ncarrying, and — the field that matters most — **how old that position is**.\n\n**Not paginated, deliberately.** A map showing page one of the captains is worse than no\nmap: a dispatcher cannot tell whether an empty quarter of the city is really empty or\nsimply on page two.\n\n### Read `gps_state` before you trust the coordinates\n\nA dot looks equally confident whether the fix is four seconds or forty minutes old, and a\ndispatcher who cannot tell the difference will route around a captain who left an hour\nago — or route *to* one. The thresholds are the dispatch algorithm's own\n(`gps_aging_min`, `gps_stale_min`), so this screen and the ranking agree about what\n\"stale\" means.\n\n| State | Means |\n|---|---|\n| `fresh` | reporting normally |\n| `aging` | past the algorithm's aging threshold; still usable |\n| `stale` | the algorithm is already discounting them |\n| `never` | on duty and **has never reported at all** — their app is not sending |\n\n`never` is separate from `stale` because the two need different actions: a stale captain\nwas working and something happened; one who never reported is a support call.\n\nCaptains with no position **are included**. Hiding them would conceal the most\ninteresting row on the screen.\n\n### Two details\n\n`age_seconds` is measured on the **server's** clock. Do not subtract `captured_at` from\nthe browser's time — a laptop that has been asleep is routinely minutes out.\n\n`active_orders` is what the captain is actually carrying, counted from the orders. It is\nnot `drivers.active_orders`, which is a reservation counter that legitimately runs ahead\nof reality for a moment during assignment.\n\nPoll it; roughly every ten seconds matches how often a moving captain reports. Positions\nare frequent and worth pulling. The `dispatch.dashboard` websocket channel carries *route*\nchanges, which are rare and worth pushing.\n\nRequires `dispatch.view`.", "operationId": "dispatchLiveFleet", "responses": { "200": { "description": "The fleet.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "as_of": { "description": "The server's clock when the snapshot was taken.", "type": "string", "format": "date-time" }, "captains": { "type": "array", "items": { "properties": { "uuid": { "description": "The captain ULID.", "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "lat": { "description": "Null when they have never reported.", "type": "number", "nullable": true }, "lng": { "type": "number", "nullable": true }, "accuracy": { "description": "Metres, as the phone reported it.", "type": "number", "nullable": true }, "captured_at": { "type": "string", "format": "date-time", "nullable": true }, "age_seconds": { "description": "How old the fix is, on the server's clock.", "type": "integer", "nullable": true }, "gps_state": { "type": "string", "enum": [ "fresh", "aging", "stale", "never" ] }, "on_break": { "description": "Online, but not taking new orders.", "type": "boolean" }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "active_orders": { "description": "What they are carrying, not what is reserved.", "type": "integer" }, "vehicle": { "properties": { "plate_number": { "type": "string" }, "type": { "type": "string", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } }, "summary": { "description": "Every key present even at zero — a tile that vanishes reads as \"nothing to check\".", "properties": { "on_duty": { "type": "integer" }, "fresh": { "type": "integer" }, "aging": { "type": "integer" }, "stale": { "type": "integer" }, "never_reported": { "type": "integer" }, "on_break": { "type": "integer" }, "carrying": { "type": "integer" }, "idle": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Missing `dispatch.view`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/dispatch/kpis": { "get": { "tags": [ "Dashboard — Dispatch" ], "summary": "What the dispatch algorithm did over a window", "description": "**Every rate is nullable, and that is the most important thing on this endpoint.** A rate\nwith nothing in its denominator is *unknown*, not zero: a day with no assignments has no\nbatch rate, and drawing `0%` would report a fleet that never batches instead of a fleet\nthat did nothing. Render `null` as \"—\". A screen cannot un-see a number it was given.\n\nRates are **fractions between 0 and 1**, not percentages. One place decides how to phrase\na number for a human, and it is not this one.\n\nThe figures come from two sources on purpose: counters answer \"how many\", which is what\nevery rate needs and what a table of millions of rows cannot answer cheaply; the\nsuggestion log answers \"how long\", because a latency percentile needs the individual\nmeasurements and a counter has thrown them away.\n\nThe window is capped. A `from` reaching past the counters' retention is **refused rather\nthan truncated** — a partial answer that looked complete would be worse than an error.\n\nRequires `dispatch.view`.", "operationId": "dispatchKpis", "parameters": [ { "name": "from", "in": "query", "description": "Defaults to the start of the retained window.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Defaults to today. Cannot be in the future.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The KPIs.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "suggestion_to_display": { "description": "How long the system took to build a list — p50/p95 and a count.", "type": "object" }, "display_to_assign": { "description": "How long the dispatcher then took to choose. Measures the human, not the machine.", "type": "object" }, "first_suggestion_acceptance_rate": { "description": "Of assignments made from a list, the share that took its first pick.", "type": "number", "nullable": true }, "batch_rate": { "description": "Of all assignments, the share that joined a route rather than starting one.", "type": "number", "nullable": true }, "assignment_failure_rate": { "description": "Of all attempts, the share refused — no capacity, or a captain no longer eligible.", "type": "number", "nullable": true }, "routing_fallback_rate": { "description": "Of all routing calls, the share the engine did not answer.", "type": "number", "nullable": true }, "routing_elements_per_assignment": { "description": "Billable map units per order assigned.", "type": "number", "nullable": true }, "maps_cost_per_delivery": { "type": "number", "nullable": true }, "recomputes_per_delivery": { "type": "number", "nullable": true }, "totals": { "description": "The raw counters the rates were derived from.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "The window reaches past what the counters retain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/dispatch/drivers/{driver}/route-plan": { "get": { "tags": [ "Dashboard — Dispatch" ], "summary": "A captain's live route", "description": "The stops in the order the captain is told to do them, with the line to draw on a map.\n\n**Read `degraded` before trusting the times.** True means the routing engine could not\nanswer: the stops and their order are still right, the times are straight-line estimates,\nand `polyline` is empty. Drawing estimates as though they were road times is how a\ndispatcher promises a customer something nobody can keep.\n\n`version` matters — pass it back when reordering, or a stale screen will overwrite a\nnewer plan.\n\nThe identifier is a **ULID**, not a uuid: `Driver` uses `HasUlids`.\n\nRequires `dispatch.view`.", "operationId": "dispatchRoutePlanShow", "parameters": [ { "name": "driver", "in": "path", "description": "The captain ULID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePlan" } } } }, "404": { "description": "No captain, or no current plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/dispatch/drivers/{driver}/route-plan/reorder": { "patch": { "tags": [ "Dashboard — Dispatch" ], "summary": "Change the order of a captain's stops", "description": "Send **every** stop key, in the new order — `pickup:{id}` and `dropoff:{id}`, exactly as\nthe `key` field of each stop gives them. A partial list is refused, because it would be\nambiguous about whether the missing stops were dropped or merely not mentioned.\n\n`version` is the plan version you were looking at. If the plan has moved on since — a new\norder was assigned, or the captain advanced — this answers **409** rather than\noverwriting it. That is the whole point: two dispatchers on the same captain must not be\nable to silently undo each other.\n\nA dropoff cannot be ordered before its own pickup.\n\nRequires **`orders.assign`**, not `dispatch.settings`: changing what a captain is told to\ndo next is the same authority as handing them an order in the first place.", "operationId": "dispatchRoutePlanReorder", "parameters": [ { "name": "driver", "in": "path", "description": "The captain ULID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "version", "stops" ], "properties": { "version": { "description": "The version you were shown.", "type": "integer", "example": 4, "minimum": 1 }, "stops": { "description": "Every stop key, in the new order.", "type": "array", "items": { "type": "string", "pattern": "^(pickup|dropoff):\\d+$" }, "example": [ "pickup:12", "pickup:13", "dropoff:44", "dropoff:45" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Reordered, and pushed to the captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutePlan" } } } }, "409": { "description": "The plan moved on since that version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Stops missing, duplicated, or a dropoff before its pickup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/integration/webhooks": { "get": { "tags": [ "Dashboard — Store integration" ], "summary": "Every callback we have tried to send", "description": "The answer to *\"did you tell them?\"*, with the raw payload we sent and whatever their\nendpoint answered.\n\n`Summary` counts deliveries by status, and **every status is present even at zero** — a\ndashboard tile reading \"—\" when the true answer is \"none\" tells somebody checking for\nbreakage exactly the wrong thing. Read it like this:\n\n| Piling up | Means |\n|---|---|\n| `pending` | no queue worker is running. `php artisan queue:work` |\n| `failed` | retrying; `next_attempt_at` says when |\n| `dropped` | six attempts exhausted. Nothing more is coming, and a human has to replay it |\n\nRequires `integration.view`.", "operationId": "integrationWebhookIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "sent", "failed", "dropped" ] } }, { "name": "event", "in": "query", "schema": { "type": "string" }, "example": "order.delivered" }, { "name": "order_uuid", "in": "query", "description": "Everything sent about one order.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A page of deliveries, plus the status summary.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "Summary": { "properties": { "pending": { "type": "integer", "example": 0 }, "sent": { "type": "integer", "example": 128 }, "failed": { "type": "integer", "example": 1 }, "dropped": { "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Missing `integration.view`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/integration/webhooks/{delivery}": { "get": { "tags": [ "Dashboard — Store integration" ], "summary": "One delivery, with the bytes we sent", "description": "The `payload` is kept in full because the first disagreement with an external partner is\nalways \"we sent it\" — and without the bytes there is nothing to settle it with.\n\nRequires `integration.view`.", "operationId": "integrationWebhookShow", "parameters": [ { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "404": { "description": "No such delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/integration/webhooks/{delivery}/replay": { "post": { "tags": [ "Dashboard — Store integration" ], "summary": "Send it again", "description": "The case this exists for is a store that was down past our six attempts: the event is\n`dropped`, nothing more is coming, and somebody has to say \"try now\".\n\nIt **resets** the attempt count rather than continuing it — the previous run is over, and\nwhat was asked for is a fresh set of retries starting at ten seconds.\n\nThe store's handler will see the event a second time. That is what `event_id` is for, and\ntheir contract requires them to deduplicate on it.\n\nRequires `integration.replay`, which `integration.view` does not grant: reading the log\nand changing what another company believes are different acts.", "operationId": "integrationWebhookReplay", "parameters": [ { "name": "delivery", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Queued again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "403": { "description": "Missing `integration.replay`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/notifications": { "get": { "tags": [ "Dashboard — Notifications" ], "summary": "The notifications for the signed-in admin", "description": "Newest first, and only this admin's own.\n\n`title` and `message` arrive **already translated** into whatever `Accept-Language` asked\nfor, so a screen renders them directly. Branch on `type` and `group`, never on the text.\n\nRequires `notifications.view`.", "operationId": "notificationIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "group", "in": "query", "schema": { "type": "string", "enum": [ "order", "vehicle", "application", "system" ] } } ], "responses": { "200": { "description": "A page of notifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminNotification" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/notifications/unread-count": { "get": { "tags": [ "Dashboard — Notifications" ], "summary": "How many are unread", "description": "The number for the badge. Cheap enough to poll. Requires `notifications.view`.", "operationId": "notificationUnreadCount", "responses": { "200": { "description": "The count.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "count": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/notifications/{uuid}/read": { "post": { "tags": [ "Dashboard — Notifications" ], "summary": "Mark one as read", "description": "Only the caller's own. Another admin's notification answers 404 — read state belongs to\nthe person, not to the event.\n\nRequires `notifications.read`.", "operationId": "notificationMarkRead", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Marked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminNotification" } } } }, "404": { "description": "Not one of yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/notifications/read-all": { "post": { "tags": [ "Dashboard — Notifications" ], "summary": "Mark every one of mine as read", "description": "Affects only the caller. Requires `notifications.read`.", "operationId": "notificationReadAll", "responses": { "200": { "description": "All marked." } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders": { "get": { "tags": [ "Dashboard — Orders" ], "summary": "Delivery orders, a page at a time", "description": "Filters: search (order number), status. Requires `orders.view`. Orders use UUIDs. The list can be read open or pre-filtered to one status.", "operationId": "orderIndex", "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": "search", "in": "query", "description": "Order number.", "schema": { "type": "string", "nullable": true, "maxLength": 255 } }, { "name": "status", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "pending", "assigned", "picked_up", "on_the_way", "delivered", "delivery_failed" ] } }, { "name": "items_mismatch", "in": "query", "description": "1 = only orders whose pickup item count did not match the order.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of orders.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "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": "Missing orders.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Missing/invalid page or rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Orders" ], "summary": "Open an order for delivery", "description": "A fake order the back office creates until the live third party integration starts\nfeeding the system (Feature 04 MVP). It writes the same fields the integration will.\nThe pickup/dropoff coordinates are optional but each pair stays intact: a latitude\nwithout its longitude is refused rather than half-recorded. Requires `orders.create`.", "operationId": "orderStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "customer_name", "pickup_address", "dropoff_address" ], "properties": { "customer_name": { "type": "string", "example": "Khalid Al Ghamdi", "maxLength": 255 }, "customer_phone": { "type": "string", "example": "+966500000101", "nullable": true, "maxLength": 30 }, "pickup_address": { "type": "string", "example": "Store 12, Granada Mall, Riyadh", "maxLength": 255 }, "dropoff_address": { "type": "string", "example": "Olaya Street, Riyadh", "maxLength": 255 }, "pickup_lat": { "type": "number", "example": 24.803625499999998993416738812811672687530517578125, "nullable": true, "maximum": 90, "minimum": -90 }, "pickup_lng": { "type": "number", "example": 46.69935459999999949332050164230167865753173828125, "nullable": true, "maximum": 180, "minimum": -180 }, "dropoff_lat": { "type": "number", "example": 24.6887535999999983005182002671062946319580078125, "nullable": true, "maximum": 90, "minimum": -90 }, "dropoff_lng": { "type": "number", "example": 46.680810600000000931686372496187686920166015625, "nullable": true, "maximum": 180, "minimum": -180 }, "customer_note": { "description": "What the customer asked for; shown to the captain.", "type": "string", "example": "Call on arrival.", "nullable": true, "maxLength": 1000 }, "note": { "description": "Internal note for the operations team; never shown to the captain.", "type": "string", "example": "Repeat customer.", "nullable": true, "maxLength": 1000 }, "fee": { "type": "number", "example": 18.5, "nullable": true, "minimum": 0 }, "currency": { "type": "string", "example": "SAR", "maxLength": 10 }, "payment_method": { "type": "string", "example": "cash_on_delivery", "enum": [ "cash_on_delivery", "prepaid" ] }, "amount_to_collect": { "description": "Required for cash_on_delivery; ignored for prepaid.", "type": "number", "example": 92.5, "nullable": true, "minimum": 0 }, "items": { "type": "array", "items": { "required": [ "name", "quantity" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "integer", "maximum": 999, "minimum": 1 }, "unit_price": { "type": "number", "nullable": true, "minimum": 0 }, "note": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" }, "maxItems": 50 } }, "type": "object" }, "example": { "customer_name": "Khalid Al Ghamdi", "customer_phone": "+966500000101", "pickup_address": "Store 12, Granada Mall, Riyadh", "dropoff_address": "Olaya Street, Riyadh", "pickup_lat": 24.803625499999998993416738812811672687530517578125, "pickup_lng": 46.69935459999999949332050164230167865753173828125, "dropoff_lat": 24.6887535999999983005182002671062946319580078125, "dropoff_lng": 46.680810600000000931686372496187686920166015625, "note": "Call on arrival.", "fee": 18.5, "currency": "SAR" } } } }, "responses": { "201": { "description": "Order opened.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Order" }, "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": "Missing orders.create permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders/{uuid}": { "get": { "tags": [ "Dashboard — Orders" ], "summary": "One order with items, captain and timeline", "description": "Requires `orders.view`. Orders use UUIDs.", "operationId": "orderShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Order" }, "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": "Missing orders.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders/{uuid}/captains": { "get": { "tags": [ "Dashboard — Orders" ], "summary": "Ranked captain suggestions for an order", "description": "The captains worth putting this order in front of, best first, with every number that\ndecided the order they are in. It is a suggestion only — the dispatcher picks who\ncarries it — so it sits on the same `orders.assign` permission as the assignment that\nfollows it.\n\n**Busy captains are included.** A captain finishing a delivery two streets from the\npickup often beats an idle one across town, so each row is priced on an *adjusted ETA*:\nthe time left on their current delivery, plus a handoff buffer, plus the road time from\nthere to this pickup. An idle captain simply has the first two at zero. `state` says\nwhich kind of captain a row is, and `reasons` says it in words, already translated.\n\nNote that the assignment endpoint is stricter than this list: until stacking ships it\nstill refuses a busy captain, so a name shown here can come back `422`.\n\n**The list survives a maps outage.** When the routing engine times out or refuses, the\nlist is still returned, ranked on straight-line estimates, with `ranking_degraded: true`,\na `degraded_reason`, and `eta_estimated: true` on every row whose time was guessed. This\nendpoint does not fail because maps did.\n\n**An empty list is an answer.** Nobody eligible, nobody within the widest search radius,\nor everybody set aside for a GPS point too old to trust all return `200` with\n`candidates: []` and a `no_candidates_reason` to show the dispatcher.\n\nEvery response is written to the Suggestion Log; `suggestion_uuid` is that entry, so any\nlist a dispatcher saw can be explained afterwards.", "operationId": "orderCaptainSuggestions", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" } } ], "responses": { "200": { "description": "The ranked suggestions, possibly empty.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/SuggestionList" }, "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": "Missing orders.assign permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "The order has no pickup that can be placed on a map.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders/{uuid}/assign": { "patch": { "tags": [ "Dashboard — Orders" ], "summary": "Hand the order to a captain", "description": "Hands the order to the captain the dispatcher picked, identified by ULID. Requires\n`orders.assign`.\n\n**A captain carrying an order can be given another.** Up to `max_active_orders` (2 by\ndefault), which is what makes the batching the suggestion list proposes actually possible.\n\n**Expect `409`, and handle it.** The dispatcher confirms from a list that was true when it\nwas drawn, so between the two the captain may have been taken by somebody else, filled up,\nor gone off duty. The capacity is taken by a single conditional statement, so two\ndispatchers cannot both succeed — the one who loses gets `409` with a `MessageDebug.reason`\nsaying which happened:\n\n- `locked` — another dispatcher is confirming this captain right now; retry in a moment.\n- `at_capacity` — the captain filled up; ask for a fresh list and choose again.\n- `not_eligible` — the captain went offline, started a break, or was suspended; ask for a\n fresh list.\n\n`locked` is worth a retry; the other two are not, and the screen should refresh the\nsuggestions instead.\n\nSending `suggestion_uuid` and `rank` records which list the captain was chosen from and\nwhere they sat on it. Both are optional — an order assigned from a phone call has neither\n— but sending them is what lets anyone ask afterwards whether dispatchers take the\nranking's first pick. An unknown `suggestion_uuid` is recorded as no list rather than\nrefused: a missing statistic must never stop a captain getting their order.", "operationId": "orderAssign", "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": [ "driver_uuid" ], "properties": { "driver_uuid": { "description": "The captain's ULID.", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "suggestion_uuid": { "description": "The suggestion list the captain was chosen from, when there was one.", "type": "string", "format": "uuid", "example": "01a0b389-019d-7a5c-9f7e-3d1b0c2a4e77", "nullable": true }, "rank": { "description": "The captain's place on that list. 1 is the top suggestion.", "type": "integer", "example": 1, "nullable": true, "minimum": 1 } }, "type": "object" }, "example": { "driver_uuid": "01m24x34bzfbh7resdmkm55mmq", "suggestion_uuid": "01a0b389-019d-7a5c-9f7e-3d1b0c2a4e77", "rank": 1 } } } }, "responses": { "200": { "description": "Order handed over.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Order" }, "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": "Missing orders.assign permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order or captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "The captain could not take the order after all — held by another dispatcher, full, or off duty. MessageDebug.reason says which.", "content": { "application/json": { "schema": { "properties": { "Status": { "type": "boolean", "example": false }, "Message": { "type": "string", "example": "This captain filled up while the list was open. Refresh the suggestions and choose again." }, "MessageDebug": { "properties": { "reason": { "type": "string", "example": "at_capacity", "enum": [ "locked", "at_capacity", "not_eligible" ] } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Missing or malformed driver_uuid, or the order cannot leave its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders/{uuid}/assign-enforced": { "patch": { "tags": [ "Dashboard — Orders" ], "summary": "Direct an employee captain: assigned and accepted in one move", "description": "The same hand-over as `assign`, without the captain's answer. The order is assigned and\naccepted together, no offer deadline is written, and nothing is queued to take it back.\n\n**Employee captains only** — `422` for a freelance one. A freelancer's arrangement is that\nthey may refuse, and a company that can force work on them is not using freelancers. The\nsuggestion list says which arrangement each captain is on (`captain.employment_type`), so a\nscreen can offer this only where it will work.\n\nThe order still passes through `assigned` internally, because that is the transition that\nrecomputes the captain's route and puts the order on their phone. The timeline therefore shows\nboth steps, and **the accepted step carries the manager as its actor** rather than pretending\nthe captain answered.\n\nRequires `orders.assign_enforced`, which is separate from `orders.assign`: offering work and\ndirecting it are different authorities.", "operationId": "ordersAssignEnforced", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "driver_uuid" ], "properties": { "driver_uuid": { "description": "The captain ULID.", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "suggestion_uuid": { "description": "The list this captain was chosen from, for the KPIs.", "type": "string", "format": "uuid", "nullable": true }, "rank": { "description": "Their row on that list.", "type": "integer", "nullable": true, "minimum": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "The order, already accepted.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Order" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order was assigned to the captain, who does not need to accept it." } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing orders.assign_enforced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order or captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "The captain is full, or no longer eligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "A freelance captain, or an order that cannot be assigned from its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/orders/{uuid}/cancel": { "post": { "tags": [ "Dashboard — Orders" ], "summary": "Call the order off", "description": "Ends the order, for the reason given. **Terminal** — a cancelled order cannot be revived,\nreassigned or delivered.\n\nA named POST rather than a status field on an update, because cancelling is not an edit.\nIt writes a timeline entry naming the admin who did it, and **hands back the carrying\ncaptain's capacity** in the same transaction that moves the status, so the captain becomes\nassignable again at once. An order with no captain simply releases nothing.\n\n**Its own permission.** `orders.cancel`, not `orders.assign` — somebody who may hand work\nout is not by that fact somebody who may call it off.\n\n`reason` is required. A cancelled order with no reason is unanswerable later: to the store\nthat placed it, to the captain who lost the job, and to whoever asks why the numbers moved.\n\nAnswers **422** if the order has already ended — a delivered order cannot be un-delivered\nby cancelling it.\n\nCaptains cannot reach this. A captain who cannot take an order **declines** it\n(`POST /api/driver/orders/{uuid}/decline`), which returns it to the pool for somebody else\nrather than ending it; after the pickup they use `failed`.", "operationId": "dashboardOrderCancel", "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 changed their mind.", "maxLength": 255 } }, "type": "object" }, "example": { "reason": "Customer changed their mind." } } } }, "responses": { "200": { "description": "Order cancelled; any carrying captain is free again.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Order" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The order has been cancelled.", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing orders.cancel permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "No reason given, or the order has already ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/profile": { "get": { "tags": [ "Dashboard — Profile" ], "summary": "Signed in admin's own record", "operationId": "adminProfileShow", "responses": { "200": { "description": "The admin record, roles included.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Profile" ], "summary": "Update the signed in admin's own record", "operationId": "adminProfileUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "محمد الجاعور", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^\\+[0-9]{8,15}$", "example": "+963932174371" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-01-01", "nullable": true } }, "type": "object" }, "example": { "name": "محمد الجاعور", "email": "super-admin@kapitano-logiistic.com", "phone": "+963932174371", "date_of_birth": "1990-01-01" } } } }, "responses": { "200": { "description": "Record updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": [ { "adminAuth": [] } ] } }, "/api/dashboard/profile/photo": { "post": { "tags": [ "Dashboard — Profile" ], "summary": "Replace the profile photo", "operationId": "adminProfilePhoto", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "photo": { "description": "jpg/jpeg/png, max 5120KB", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Photo replaced.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Admin" }, "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": [ { "adminAuth": [] } ] } }, "/api/dashboard/profile/password": { "post": { "tags": [ "Dashboard — Profile" ], "summary": "Replace the password", "description": "Requires the current password first. A wrong current password answers 422 on the `current_password` field.", "operationId": "adminChangePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "current_password": { "type": "string", "example": "123456" }, "password": { "type": "string", "example": "123456" }, "password_confirmation": { "type": "string", "example": "123456" } }, "type": "object" }, "example": { "current_password": "123456", "password": "123456", "password_confirmation": "123456" } } } }, "responses": { "200": { "description": "Password changed." }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "422": { "description": "Current password wrong or validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/deliveries": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Push delivery log", "description": "Every push the application sent, one row per device, newest first — the answer to\n\"did the captain get it?\".\n\n- `status`: `sent` (Firebase accepted it for that device), `failed` (Firebase refused\n it, or sending crashed; `error` says why), `no_device` (the recipient had no\n registered handset, so nothing was sent). Broadcasts skip captains without a device\n instead of logging `no_device` for each.\n- `device` is the last 12 characters of the token: enough to tell handsets apart, not\n enough to push to one.\n- `driver_uuid` narrows to one captain (unknown → 404); `broadcast_uuid` to one broadcast.\n\nRows older than `PUSH_RETENTION_DAYS` (30) are deleted nightly. Requires `push.view`.", "operationId": "pushDeliveriesIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "example": 10, "maximum": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sent", "failed", "no_device" ] } }, { "name": "driver_uuid", "in": "query", "required": false, "schema": { "type": "string", "example": "01m2fantc1662x43w8aajdfnq0" } }, { "name": "broadcast_uuid", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "notification", "in": "query", "required": false, "schema": { "type": "string", "example": "NewOrderAssignedNotification" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-01" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-17" } } ], "responses": { "200": { "description": "A page of deliveries.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "recipient": { "properties": { "uuid": { "type": "string" }, "name": { "type": "string", "example": "Captain C1" }, "type": { "type": "string", "example": "Driver" } }, "type": "object", "nullable": true }, "broadcast_uuid": { "type": "string", "format": "uuid", "nullable": true }, "notification": { "type": "string", "example": "NewOrderAssignedNotification" }, "title": { "type": "string", "example": "New order assigned", "nullable": true }, "body": { "type": "string", "nullable": true }, "data": { "type": "object", "example": { "type": "order_assigned", "order_uuid": "01a09eaa-ea72-7175-ab76-d721b0ee2ce5" }, "nullable": true }, "device": { "type": "string", "example": "…0123456789ab", "nullable": true }, "status": { "type": "string", "enum": [ "sent", "failed", "no_device" ] }, "status_label": { "type": "string", "example": "Failed" }, "message_id": { "type": "string", "example": "projects/captain-app-43cfa/messages/0:1726512345", "nullable": true }, "error": { "type": "string", "example": "The registration token is not a valid FCM registration token", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Pages", "type": "integer" }, "Page": { "type": "integer" }, "Records": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown driver_uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Invalid filter or missing rows/page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/deliveries/{uuid}/resend": { "post": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Resend a logged push", "description": "Sends a logged push again — same title, body and data, plus `data.resent_from` — to the\nrecipient's **current** devices. The original device is often gone (a failed push usually\nmeans the app was reinstalled), so the resend follows the recipient, not the token.\n\nThe answer is Firebase's, read back from the log; see \"Send a test push\" for the fields.\n404 when the delivery or its recipient no longer exists. Requires `push.send`; limited to\n30 per minute.", "operationId": "pushDeliveryResend", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Firebase's answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSendOutcome" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.send permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown delivery, or its recipient was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "429": { "description": "More than 30 sends a minute." } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/stats": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Push health", "description": "How push has been doing over the last `PUSH_HEALTH_WINDOW_HOURS` (24): the count per\noutcome, the share that failed, and the thresholds it is judged against.\n\n`healthy` turns false only when at least `thresholds.minimum_failures` pushes failed\n*and* they are at least `thresholds.failure_percent` of the total — a couple of\nuninstalled apps is not an outage. The hourly `push:health` command uses the same rule\nand, when unhealthy, notifies the admins' inbox once per `PUSH_HEALTH_ALERT_COOLDOWN_DAYS`.\nThe thresholds are deploy configuration, not dashboard settings. Requires `push.view`.", "operationId": "pushStats", "responses": { "200": { "description": "The window's health.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "window_hours": { "type": "integer", "example": 24 }, "counts": { "properties": { "sent": { "type": "integer", "example": 120 }, "failed": { "type": "integer", "example": 3 }, "no_device": { "type": "integer", "example": 7 } }, "type": "object" }, "total": { "type": "integer", "example": 130 }, "failure_percent": { "type": "integer", "example": 2 }, "healthy": { "type": "boolean", "example": true }, "thresholds": { "properties": { "failure_percent": { "type": "integer", "example": 25 }, "minimum_failures": { "type": "integer", "example": 5 } }, "type": "object" } }, "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" } } } }, "403": { "description": "Missing push.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/test": { "post": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Send a test push to a captain", "description": "Pushes a test notification (`data.type = test`) to every registered device of one\ncaptain, **for real** — the phone shows it. Title and body default to a translated text.\n\nThe answer is what Firebase said, read back from the delivery log, not how many devices\nthe captain has:\n\n- `sent`: at least one device was accepted by Firebase.\n- `delivered` / `failed`: per-device outcome. `null` when the delivery log is switched\n off, because then there is nothing to read the answer from.\n- `devices: 0`: nothing was sent; the captain has no registered handset.\n\nRequires `push.send`; limited to 30 per minute.", "operationId": "pushTest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "driver_uuid" ], "properties": { "driver_uuid": { "type": "string", "example": "01m2fantc1662x43w8aajdfnq0" }, "title": { "type": "string", "example": "Kapitano test", "nullable": true, "maxLength": 100 }, "body": { "type": "string", "example": "Can you see this?", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Firebase's answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSendOutcome" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.send permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown captain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "driver_uuid missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } }, "429": { "description": "More than 30 sends a minute." } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/devices": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Registered devices", "description": "Every handset push can reach, most recently seen first, or one captain's with\n`driver_uuid`. A captain missing from this list will get nothing.\n\n`locale` is the language the app registered in; the captain's notifications are built in\nit. `token` is shortened the same way as in the delivery log. Requires `push.view`.", "operationId": "pushDevicesIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "example": 10, "maximum": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "driver_uuid", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of devices.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "owner": { "properties": { "uuid": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "example": "Driver" } }, "type": "object", "nullable": true }, "device_id": { "type": "string", "nullable": true }, "locale": { "type": "string", "example": "ar", "nullable": true }, "token": { "type": "string", "example": "…0123456789ab" }, "registered_at": { "type": "string", "format": "date-time" }, "last_seen_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "Status": { "type": "boolean", "example": true }, "Records": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown driver_uuid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/devices/{uuid}": { "delete": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Remove a device", "description": "Removes a handset from push — a lost or handed-over phone that must stop receiving a\ncaptain's orders. If the captain's app registers again from it, it comes back. Requires\n`push.manage`.", "operationId": "pushDeviceDestroy", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "properties": { "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The device was removed and will receive no more notifications." } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.manage permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown device.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/broadcasts": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Broadcast history", "description": "Broadcasts newest first, with who sent them and how far each got. Requires `push.view`.", "operationId": "pushBroadcastsIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "example": 10, "maximum": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } } ], "responses": { "200": { "description": "A page of broadcasts.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/PushBroadcast" } }, "Status": { "type": "boolean", "example": true }, "Records": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Broadcast to captains", "description": "Sends one message to many captains, **for real**, in the background. Only approved,\nactive captains are ever included:\n\n- `all`: every approved, active captain.\n- `online`: only those on duty right now.\n- `captains`: the ones named in `driver_uuids` (at most `PUSH_BROADCAST_MAX_NAMED_CAPTAINS`, 500).\n\nThe broadcast is queued as a batch of small jobs (`PUSH_BROADCAST_CHUNK_SIZE`, 50 captains\neach) so no job outlives the queue's retry window and nobody is pushed twice. Captains\nwithout a registered device are skipped. Answers 201 at once; follow progress with\n\"One broadcast and its progress\".\n\n- **409** — the same admin sent the same title, body and audience within\n `PUSH_BROADCAST_DUPLICATE_WINDOW_S` (120 s): a double click is not sent twice.\n- **422** — nobody matches the audience.\n\nRequires `push.broadcast`; limited to 5 per minute.", "operationId": "pushBroadcastStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "body", "audience" ], "properties": { "title": { "type": "string", "example": "Eid holiday", "maxLength": 100 }, "body": { "type": "string", "example": "The depot is closed on Friday.", "maxLength": 500 }, "audience": { "type": "string", "enum": [ "all", "online", "captains" ] }, "driver_uuids": { "description": "Required for, and only allowed with, audience=captains.", "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Queued.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/PushBroadcast" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "The broadcast was queued and is being sent in the background." } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.broadcast permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "409": { "description": "The same broadcast was just sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Invalid input, or nobody matches the audience.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } }, "429": { "description": "More than 5 broadcasts a minute." } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/broadcasts/{uuid}": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "One broadcast and its progress", "description": "Poll this after sending: `status` moves queued → sending → completed and the counts grow as chunks run. Requires `push.view`.", "operationId": "pushBroadcastShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The broadcast.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/PushBroadcast" }, "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": "Missing push.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/failed-jobs": { "get": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Failed push jobs", "description": "The queued push work that ran out of attempts — order-assigned and application-decision\nnotifications and broadcast chunks — newest first, with the first line of the error.\nOther failed jobs are not listed here. Requires `push.manage`.", "operationId": "pushFailedJobsIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "example": 10, "maximum": 25, "minimum": 1 } }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "example": 1, "minimum": 1 } } ], "responses": { "200": { "description": "A page of failed push jobs.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "job": { "type": "string", "example": "NotifyCaptainOfAssignment" }, "queue": { "type": "string", "example": "default" }, "error": { "type": "string", "example": "ModelNotFoundException: No query results for model [App\\Models\\Order]." }, "failed_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "Status": { "type": "boolean", "example": true }, "Records": { "type": "integer" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.manage permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/failed-jobs/{uuid}/retry": { "post": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Retry a failed push job", "description": "Puts the job back on its queue. A job that fails again returns to the list. Only push jobs are in reach; any other uuid answers 404. Requires `push.manage`.", "operationId": "pushFailedJobRetry", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Re-queued." }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.manage permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown job, or not a push job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/push/failed-jobs/{uuid}": { "delete": { "tags": [ "Dashboard — Push Notifications" ], "summary": "Forget a failed push job", "description": "Removes the failed job for good. Only push jobs are in reach; any other uuid answers 404. Requires `push.manage`.", "operationId": "pushFailedJobDestroy", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed." }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing push.manage permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Unknown job, or not a push job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/roles": { "get": { "tags": [ "Dashboard — Roles & Permissions" ], "summary": "List the roles", "description": "Paginated, each role with the permissions it grants. Requires `roles.view`. Roles use UUIDs.", "operationId": "roleIndex", "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 } ], "responses": { "200": { "description": "A page of roles.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "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": "Missing roles.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Missing/invalid page or rows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Roles & Permissions" ], "summary": "Create a role", "description": "Creates a role on the `admin` guard and grants the permissions sent with it. Requires `roles.create`.", "operationId": "roleStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "operations-manager", "maxLength": 255 }, "permissions": { "type": "array", "items": { "type": "string", "example": "orders.view" }, "minItems": 1 } }, "type": "object" }, "example": { "name": "operations-manager", "permissions": [ "drivers.view", "drivers.update", "drivers.review", "vehicles.view", "vehicles.create", "vehicles.update", "orders.view", "orders.create", "orders.assign" ] } } } }, "responses": { "201": { "description": "Role created.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Role" }, "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": "Missing roles.create permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/roles/{uuid}": { "get": { "tags": [ "Dashboard — Roles & Permissions" ], "summary": "One role with its permissions", "operationId": "roleShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a08576-829e-71a7-8823-8bac31159cd1" } } ], "responses": { "200": { "description": "The role.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Role" }, "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": "Missing roles.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Role not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Roles & Permissions" ], "summary": "Rename a role and sync its permissions", "operationId": "roleUpdate", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "01a08576-829e-71a7-8823-8bac31159cd1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "support", "maxLength": 255 }, "permissions": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "example": { "name": "support", "permissions": [ "drivers.view", "vehicles.view", "orders.view" ] } } } }, "responses": { "200": { "description": "Role updated.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/Role" }, "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": "Missing roles.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Role not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/permissions": { "get": { "tags": [ "Dashboard — Roles & Permissions" ], "summary": "Permission catalogue", "description": "Every permission a role may be granted, not paginated (a fixed list used by the role form). Requires any of roles.view / roles.create / roles.update.", "operationId": "permissionIndex", "responses": { "200": { "description": "The permission catalogue.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "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": "Missing any role permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/settlements/preview": { "get": { "tags": [ "Dashboard — Settlements" ], "summary": "Total a period up, without writing anything", "description": "**Run this before drawing a payment up.** It writes nothing; the point is that the\nfigures reach a human before they become a payment, rather than being retyped off another\nscreen — which is where a transposed digit gets into a bank transfer.\n\nBoth dates are required, unlike the store's own statement. A payout covers a stated\nperiod, and silently defaulting one would put \"the last thirty days from whenever you\nclicked\" into a financial record.\n\nOne row per currency, never summed across them.\n\nRequires `settlements.manage`.", "operationId": "settlementPreview", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "What the period came to.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "totals": { "type": "array", "items": { "properties": { "currency": { "type": "string", "example": "SAR" }, "delivered_count": { "type": "integer" }, "cash_collected": { "type": "number" }, "prepaid_value": { "type": "number" }, "fees_charged": { "type": "number" }, "net_due_to_store": { "type": "number" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Dates missing, or the range is backwards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/settlements": { "get": { "tags": [ "Dashboard — Settlements" ], "summary": "One store's payouts", "description": "Drafts included, unlike the store's own view of the same ledger. Requires `settlements.view`.", "operationId": "settlementIndex", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "settled", "cancelled" ] } } ], "responses": { "200": { "description": "A page of settlements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Settlements" ], "summary": "Draw a payout up, as a draft", "description": "**A draft is invisible to the store.** They see it once somebody has stood behind it — a\nfigure still being checked is not one worth having an argument about.\n\nThe amounts you send are recorded **as sent**, and are allowed to differ from the\npreview: an adjustment, a rounding, a dispute settled halfway. What is recorded is what a\nhuman agreed to pay, not what the orders imply. That is also why they are copied in\nrather than joined to — if an order is corrected next month, a payment already made must\nnot change underneath the people holding it.\n\n`net_amount` may be **negative**. A mostly-prepaid month where our fees exceed the cash\ncollected leaves the shop owing us, and a ledger that could only express one direction\nwould force somebody to fudge it.\n\nRequires `settlements.manage`.", "operationId": "settlementStore", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "period_start", "period_end", "currency", "cash_collected", "fees_charged", "net_amount" ], "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "description": "On or after period_start.", "type": "string", "format": "date" }, "currency": { "type": "string", "example": "SAR", "maxLength": 3 }, "cash_collected": { "type": "number" }, "fees_charged": { "type": "number" }, "net_amount": { "description": "What is actually paid. Sent rather than derived, because it is allowed to differ from cash − fees.", "type": "number" }, "orders_count": { "type": "integer", "nullable": true }, "reference": { "type": "string", "nullable": true, "maxLength": 255 }, "note": { "type": "string", "nullable": true, "maxLength": 1000 } }, "type": "object" } } } }, "responses": { "201": { "description": "Drafted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/settlements/{settlement}": { "put": { "tags": [ "Dashboard — Settlements" ], "summary": "Correct a draft", "description": "Only while it is a draft. A settled one answers **409 `settlement_not_editable`**: the way\nto correct a payment both sides are holding is another payment, not a rewrite of the one\nthey agreed.\n\nRequires `settlements.manage`.", "operationId": "settlementUpdate", "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "period_start", "period_end", "currency", "cash_collected", "fees_charged", "net_amount" ], "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "currency": { "type": "string", "maxLength": 3 }, "cash_collected": { "type": "number" }, "fees_charged": { "type": "number" }, "net_amount": { "type": "number" }, "orders_count": { "type": "integer", "nullable": true }, "reference": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "409": { "description": "Already settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/settlements/{settlement}/settle": { "post": { "tags": [ "Dashboard — Settlements" ], "summary": "Mark it paid", "description": "From here the store can see it, and **neither side may edit it**. The figures are frozen\nrather than recomputed, so a later correction to an order cannot change a payment that\nhas already been made.\n\nRequires `settlements.manage`.", "operationId": "settlementSettle", "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "409": { "description": "Not a draft. Nothing leads out of settled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/settlements/{settlement}/cancel": { "post": { "tags": [ "Dashboard — Settlements" ], "summary": "Abandon a draft", "description": "Only from draft. Requires `settlements.manage`.", "operationId": "settlementCancel", "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "409": { "description": "Not a draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/stats": { "get": { "tags": [ "Dashboard — Stats" ], "summary": "Everything the overview screen draws", "description": "One call for the whole landing page, rather than a dozen — the screen draws all of it at\nonce, so splitting it would only buy a slower first paint.\n\n**Cached for a short period and shared by every admin**, which is why `generated_at` is\nreturned: a figure a minute old is fine on this screen, and a figure whose age is unknown\nis not. Show it.\n\nCounts are **zero-filled across every status**, so a tile never disappears because its\nnumber happens to be nought — \"no failed deliveries\" and \"we forgot to ask\" must not look\nalike.\n\nRequires `dispatch.view`.", "operationId": "dashboardStats", "responses": { "200": { "description": "The overview.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "generated_at": { "description": "When the cached snapshot was built. Show it.", "type": "string", "format": "date-time" }, "orders": { "properties": { "total": { "type": "integer" }, "today": { "type": "integer" }, "yesterday": { "type": "integer" }, "active": { "description": "Everything not yet in a terminal state.", "type": "integer" }, "by_status": { "description": "Every OrderStatus, zero-filled.", "type": "object" } }, "type": "object" }, "revenue": { "properties": { "today": { "type": "number" }, "yesterday": { "type": "number" }, "total": { "type": "number" }, "by_payment_method": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "deliveries": { "properties": { "today": { "type": "integer" }, "yesterday": { "type": "integer" } }, "type": "object" }, "drivers": { "properties": { "by_status": { "description": "Every DriverStatus, zero-filled.", "type": "object" }, "online": { "type": "integer" }, "ready_to_assign": { "description": "Approved, on duty, not on a break, and carrying fewer than the maximum — the same rule the assignment screen applies.", "type": "integer" }, "idle": { "description": "Of those, the ones carrying nothing at all.", "type": "integer" } }, "type": "object" }, "vehicles": { "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "awaiting_assignment": { "description": "Company vehicles with no plate yet.", "type": "integer" }, "by_ownership": { "type": "object" }, "by_type": { "type": "object" }, "documents": { "properties": { "registration": { "type": "object" }, "insurance": { "type": "object" } }, "type": "object" } }, "type": "object" }, "trends": { "properties": { "days": { "description": "How many days the series covers.", "type": "integer" }, "series": { "description": "One entry per day: created, delivered, revenue.", "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "403": { "description": "Missing permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients": { "get": { "tags": [ "Dashboard — Stores" ], "summary": "The stores, and the applications waiting for a decision", "description": "Newest first. Filter by `status=pending` for the review queue.\n\nNote that this list deliberately **includes inactive rows**, unlike most listings here.\nAn application awaiting review is inactive by definition, so a queue that hid them would\nalways look empty.\n\nRequires `store_clients.view`.", "operationId": "storeClientIndex", "parameters": [ { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "suspended" ] } }, { "name": "search", "in": "query", "description": "Name or handle.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of stores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "403": { "description": "Missing permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}": { "get": { "tags": [ "Dashboard — Stores" ], "summary": "One store", "description": "No secret is returned here. Support can read a store's whole configuration without being able to read its signing key. Requires `store_clients.view`.", "operationId": "storeClientShow", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "404": { "description": "No such store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Stores" ], "summary": "Correct a store's configuration on its behalf", "description": "For when a shop cannot fix it itself — the owner is the person who left, or the callback\nURL is wrong in a way that only shows up in our delivery log.\n\nThe URL goes through the **same SSRF check** the store's own screen uses. Being an admin\nis not a reason to skip it: the outbound request is still made by our server, to whatever\nwas typed, so the check protects us rather than the person typing.\n\n`slug`, `status` and `is_active` are refused with 422. The handle is in our rate-limit\nkeys and our logs; the other two move through the review decisions, where they collect a\nreason and a name.\n\nRequires `store_clients.manage`.", "operationId": "storeClientUpdate", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "webhook_url": { "description": "https, public host, standard port, no credentials.", "type": "string", "nullable": true }, "allowed_ips": { "description": "Empty switches the check off.", "type": "array", "items": { "type": "string", "format": "ipv4" }, "maxItems": 20 }, "default_currency": { "type": "string", "maxLength": 3 }, "timezone": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "422": { "description": "A private callback URL, or a field that is never editable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/users": { "get": { "tags": [ "Dashboard — Stores" ], "summary": "The people who can sign in to this store", "description": "Worth checking after an approval: *\"approved store, nobody can sign in\"* is the\nonboarding failure that looks like nothing at all from our side.\n\nRequires `store_clients.view`.", "operationId": "storeClientUsers", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rows", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 25 }, "example": 25 }, { "name": "page", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "A page of people.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUser" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/approve": { "post": { "tags": [ "Dashboard — Stores" ], "summary": "Approve a store — and how a suspended one comes back", "description": "Switches the store on and moves every `pending` person at it to `active`.\n\n**This is also the unpause.** `Suspended → Approved` is an allowed move, so a pause that\nhas run its course ends by approving again — there is no separate endpoint, because it\nwould mean exactly the same thing.\n\n**It does not mint the API token.** A plaintext token exists only at the moment it is\ncreated, so it is issued deliberately through `POST {client}/tokens` rather than printed\ninto the answer to a question nobody asked.\n\nThe note is optional here — an approval usually explains itself.\n\nRequires `store_clients.review`.", "operationId": "storeClientApprove", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "type": "string", "example": "Contract signed", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "409": { "description": "The application cannot move that way from its current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/reject": { "post": { "tags": [ "Dashboard — Stores" ], "summary": "Turn an application down", "description": "**The note is required**, unlike on an approval. This is one of the two decisions a shop\nrings up about, and \"no reason recorded\" makes that call unanswerable by whoever picks it\nup rather than by whoever made the decision.\n\nRevokes every portal session at the store immediately.\n\nRequires `store_clients.review`.", "operationId": "storeClientReject", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "note" ], "properties": { "note": { "type": "string", "example": "Could not verify the business", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "409": { "description": "Not allowed from the current status — an approved store is suspended, not rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "The note is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/suspend": { "post": { "tags": [ "Dashboard — Stores" ], "summary": "Stop a store trading, without unpicking its approval", "description": "A pause is meant to end, and a suspended store is not a rejected one — so this leaves the\nreview decision intact and approving again brings it back.\n\nTakes effect on the **very next request**: portal tokens are revoked immediately rather\nthan left to expire, because a Sanctum token does not expire on its own.\n\nRequires `store_clients.manage` — pausing a shop that is already trading stops another\ncompany's orders, which is operations' call rather than a reviewer's.", "operationId": "storeClientSuspend", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "note" ], "properties": { "note": { "type": "string", "example": "Unpaid invoices", "maxLength": 255 } }, "type": "object" } } } }, "responses": { "200": { "description": "Suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreClient" } } } }, "409": { "description": "Not allowed from the current status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/tokens": { "post": { "tags": [ "Dashboard — Stores" ], "summary": "Mint a machine credential — shown once", "description": "The token a store's **servers** authenticate with, as opposed to the password its staff\nsign in with.\n\n**The plaintext is returned once and cannot be recovered.** The response carries\n`Cache-Control: no-store`; hand it over on a secure channel and do not log it.\n\nDeliberately separate from approving a store: asking for a token is asking for a secret,\nand that should be an act somebody chose rather than a side effect of a decision.\n\nExisting tokens are **left alone** — replacing them silently would cut a store off\nmid-trade. Use the DELETE below when that is what you mean.\n\nOmit `abilities` for both. Send a narrower set for a reporting or staging integration\nthat has no business creating orders.\n\nRequires `store_clients.manage`.", "operationId": "storeClientIssueToken", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "abilities": { "description": "Defaults to both.", "type": "array", "items": { "type": "string", "enum": [ "orders:read", "orders:write" ] }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "The token, once.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "token": { "type": "string", "example": "12|xxxxxxxxxxxxxxxxxxxx" }, "abilities": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "adminAuth": [] } ] }, "delete": { "tags": [ "Dashboard — Stores" ], "summary": "Kill every machine credential this store holds", "description": "**The emergency path for a leaked token.** Until this existed the only way to do it was a\nshell on the server, which is the wrong requirement for something that has to happen in\nthe next minute and be recorded against a name.\n\nTheir **portal access is untouched**. A leaked *server* credential is not a reason to\nlock the shop's staff out of the screen where they can read what happened and set up a\nnew one.\n\nRequires `store_clients.manage`.", "operationId": "storeClientRevokeTokens", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "properties": { "Model": { "properties": { "revoked": { "description": "How many were killed.", "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/store-clients/{client}/users/{user}/activation": { "patch": { "tags": [ "Dashboard — Stores" ], "summary": "Turn one of a store's people on or off", "description": "Normally the store's own owner does this from their portal. Two cases need us to: the\nowner **is** the person who left, so nobody at the shop can remove their access; or the\nshop has been asked to and has not.\n\nTurning somebody off revokes their sessions at once.\n\nA person belonging to a different store answers **404** — an endpoint nested under one\nstore that quietly acted on another's would be a surprise nobody needs.\n\nRequires `store_clients.manage`.", "operationId": "storeClientUserActivation", "parameters": [ { "name": "client", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "is_active" ], "properties": { "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreUser" } } } }, "404": { "description": "Not somebody at this store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/vehicles": { "get": { "tags": [ "Dashboard — Vehicles" ], "summary": "Vehicle list", "description": "Paginated, newest first, switched off vehicles included. Filters: search (plate, brand,\nmodel, registration / insurance number, captain name or phone), ownership_type,\nvehicle_type, document_status, driver_uuid, is_active, awaiting_assignment.\n\n`document_status` narrows to vehicles with **at least one** document in that state\n(`missing`, `expired`, `expiring_soon` = within 30 days); `valid` narrows to vehicles\nwhose registration **and** insurance are both valid for more than 30 days.\nRequires `vehicles.view`.", "operationId": "vehicleIndex", "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": "search", "in": "query", "schema": { "type": "string", "nullable": true, "maxLength": 255 } }, { "name": "ownership_type", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "company_owned", "personal" ] } }, { "name": "vehicle_type", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] } }, { "name": "document_status", "in": "query", "schema": { "type": "string", "nullable": true, "enum": [ "missing", "expired", "expiring_soon", "valid" ] } }, { "name": "driver_uuid", "in": "query", "description": "Captain ULID.", "schema": { "type": "string", "nullable": true } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "awaiting_assignment", "in": "query", "description": "Company-owned rows with no plate yet — captains waiting for a fleet car.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of vehicles.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$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": "Missing vehicles.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "Missing/invalid page, rows or filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Vehicles" ], "summary": "Add a vehicle for a captain", "description": "Puts a vehicle on record for a captain who has none (a captain has exactly one vehicle — one who already has one answers 409). Plate numbers are unique. Photos are optional. Requires `vehicles.create`.", "operationId": "vehicleStore", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "driver_uuid", "ownership_type", "vehicle_type", "plate_number", "brand", "model", "manufacture_year", "color" ], "properties": { "driver_uuid": { "description": "Captain ULID.", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "ownership_type": { "type": "string", "example": "company_owned", "enum": [ "company_owned", "personal" ] }, "vehicle_type": { "type": "string", "example": "van", "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "plate_number": { "type": "string", "example": "KAP-5050", "maxLength": 20 }, "brand": { "type": "string", "example": "Toyota", "maxLength": 100 }, "model": { "type": "string", "example": "Hiace", "maxLength": 100 }, "manufacture_year": { "type": "integer", "example": 2024, "maximum": 2027, "minimum": 1950 }, "color": { "type": "string", "example": "white", "maxLength": 50 }, "registration_number": { "type": "string", "example": "REG-7788", "nullable": true, "maxLength": 50 }, "registration_expires_at": { "type": "string", "format": "date", "example": "2027-09-30", "nullable": true }, "insurance_policy_number": { "type": "string", "example": "INS-4411", "nullable": true, "maxLength": 50 }, "insurance_expires_at": { "type": "string", "format": "date", "example": "2027-03-31", "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": { "201": { "description": "Vehicle added.", "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": "Missing vehicles.create permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Captain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "The captain already has a vehicle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "Validation failed (e.g. plate number already on record).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/vehicles/{uuid}": { "get": { "tags": [ "Dashboard — Vehicles" ], "summary": "One vehicle", "description": "The vehicle with the captain driving it, its photos and the state of its documents. Requires `vehicles.view`.", "operationId": "vehicleShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" } ], "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" } } } }, "403": { "description": "Missing vehicles.view permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Vehicle not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "put": { "tags": [ "Dashboard — Vehicles" ], "summary": "Correct a vehicle's record", "description": "Updates only the fields sent (JSON). Identifying fields may be changed but not blanked;\nregistration and insurance fields may be sent as `null` to clear them. The plate number\nmust stay unique. Filling in a company car still awaiting assignment lets its captain\nbe approved without a `vehicle` block. Requires `vehicles.update`.", "operationId": "vehicleUpdate", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "ownership_type": { "type": "string", "enum": [ "company_owned", "personal" ] }, "vehicle_type": { "type": "string", "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "plate_number": { "type": "string", "maxLength": 20 }, "brand": { "type": "string", "maxLength": 100 }, "model": { "type": "string", "maxLength": 100 }, "manufacture_year": { "type": "integer", "maximum": 2027, "minimum": 1950 }, "color": { "type": "string", "maxLength": 50 }, "registration_number": { "type": "string", "nullable": true, "maxLength": 50 }, "registration_expires_at": { "type": "string", "format": "date", "nullable": true }, "insurance_policy_number": { "type": "string", "nullable": true, "maxLength": 50 }, "insurance_expires_at": { "type": "string", "format": "date", "nullable": true } }, "type": "object" }, "example": { "vehicle_type": "van", "color": "black", "insurance_policy_number": "INS-9900", "insurance_expires_at": "2027-12-31" } } } }, "responses": { "200": { "description": "Record 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": "Missing vehicles.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Vehicle not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/vehicles/{uuid}/images": { "post": { "tags": [ "Dashboard — Vehicles" ], "summary": "Replace vehicle photos", "description": "Multipart. Send `vehicle_image`, `mechanics_image`, or both — the one not sent stays as it is; at least one is required. Requires `vehicles.update`.", "operationId": "vehicleUpdateImages", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "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": "Photos replaced.", "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": "Missing vehicles.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Vehicle not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "No photo sent, or not a jpg/png under 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/vehicles/{uuid}/activation": { "patch": { "tags": [ "Dashboard — Vehicles" ], "summary": "Activate or deactivate a vehicle", "description": "Flips the vehicle on or off. Vehicles are never deleted. Requires `vehicles.update`.", "operationId": "vehicleToggleActivation", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" } ], "responses": { "200": { "description": "State changed.", "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": "Missing vehicles.update permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "Vehicle not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] } } }, "components": { "schemas": { "Admin": { "description": "A back office account as exposed by the admin resources.", "properties": { "uuid": { "description": "A back office account as exposed by AdminResource. Roles and the permissions they\ngrant are present only when the roles relation is loaded.", "type": "string", "format": "uuid", "example": "01a08576-8432-72a4-908c-c75a11a98bad" }, "name": { "type": "string", "example": "محمد الجاعور" }, "email": { "type": "string", "format": "email", "example": "super-admin@kapitano-logiistic.com" }, "phone": { "type": "string", "example": "+963932174371" }, "date_of_birth": { "type": "string", "format": "date", "example": "1990-01-01", "nullable": true }, "photo": { "type": "string", "format": "url", "nullable": true }, "is_active": { "type": "boolean", "example": true }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "super-admin" ] }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [] }, "is_super_admin": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-09 12:18:51" } }, "type": "object" }, "AdminAuthResult": { "description": "The result of a successful dashboard login: bearer token and the admin record.", "properties": { "token": { "description": "The login response: token and the admin's own record.", "type": "string", "example": "27|XBzYv3uBanTHHldOHWvrngVIwcRvP1Ts2Yrk6fOL3688db7e" }, "admin": { "$ref": "#/components/schemas/Admin" } }, "type": "object" }, "Role": { "description": "A role on the admin guard with the permissions it grants.", "properties": { "uuid": { "description": "A role with the permissions it grants.", "type": "string", "format": "uuid", "example": "01a08576-829e-71a7-8823-8bac31159cd1" }, "name": { "type": "string", "example": "operations-manager" }, "guard_name": { "type": "string", "example": "admin" }, "is_super_admin": { "type": "boolean", "example": false }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-09 12:18:51" } }, "type": "object" }, "Permission": { "description": "A permission in the catalogue.", "properties": { "uuid": { "description": "A single permission from the fixed catalogue.", "type": "string", "format": "uuid", "example": "01a089d1-853a-7129-a071-d5079ff01060" }, "name": { "type": "string", "example": "orders.view" }, "label": { "type": "string", "example": "View orders" }, "group": { "type": "string", "example": "orders" }, "group_label": { "type": "string", "example": "Orders" } }, "type": "object" }, "AdminNotification": { "properties": { "uuid": { "description": "One item in the back office's bell.\n\n`title` and `message` arrive already translated into whatever `Accept-Language` asked for, so\na screen renders them directly. Branch on `type` and `group`, never on the text.", "type": "string", "format": "uuid" }, "title": { "description": "Already translated.", "type": "string" }, "message": { "description": "Already translated.", "type": "string" }, "type": { "description": "How loudly to draw it. `danger` means somebody has to act.", "type": "string", "enum": [ "info", "warning", "success", "danger" ] }, "group": { "description": "What it is about, for filtering.", "type": "string", "enum": [ "order", "vehicle", "application", "system" ] }, "action_url": { "description": "Where clicking it should go.", "type": "string", "nullable": true }, "is_read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "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 } }, "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" }, "CaptainLedgerFeedTotals": { "description": "What a filtered window of the money feed moved, in one currency.\n\n**In and out are reported apart, never netted.** A day that paid out 5,000 and took 5,000 back\nnets to zero, which tells a cashier nothing about the 10,000 that changed hands.\n\nFollowing the ledger's sign convention, `in` is what grew the company's debt to captains —\nsupplier runs and cash handed in — and `out` is what shrank it.", "properties": { "in": { "type": "number", "format": "float", "example": 5000 }, "out": { "description": "Negative.", "type": "number", "format": "float", "example": -5000 }, "net": { "type": "number", "format": "float", "example": 0 }, "entries": { "description": "How many lines made it.", "type": "integer", "example": 2 } }, "type": "object" }, "CaptainBalance": { "properties": { "captain": { "properties": { "uuid": { "description": "ULID", "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "type": "string", "example": "Ahmed" }, "phone": { "type": "string", "example": "+966500000001" } }, "type": "object" }, "currency": { "type": "string", "example": "SAR" }, "balance": { "description": "Signed. Positive = the company owes the captain.", "type": "number", "format": "float", "example": 300 }, "outstanding": { "description": "The absolute amount, for the desk to count out.", "type": "number", "format": "float", "example": 300 }, "state": { "type": "string", "example": "owed", "enum": [ "owed", "owes", "clear" ] }, "state_label": { "type": "string", "example": "Owed to the captain" }, "settle_with": { "description": "The movement that brings this captain back to zero. Null when square.", "properties": { "direction": { "type": "string", "example": "cash_paid_out", "enum": [ "cash_paid_out", "cash_handed_in" ] }, "label": { "type": "string", "example": "Reimbursed by cashier" } }, "type": "object", "nullable": true }, "entries_count": { "type": "integer", "example": 4 }, "last_movement_at": { "type": "string", "format": "date-time", "example": "2026-09-21 10:15:00", "nullable": true } }, "type": "object" }, "CaptainLedgerTotals": { "description": "Per captain first, then split by sign. A captain who paid 300 and collected 380 counts once, as owing 80 — never as both owed 300 and owing 380.", "properties": { "owed_to_captains": { "description": "What the company owes captains in total.", "type": "number", "format": "float", "example": 300 }, "owed_by_captains": { "description": "What captains owe the company in total.", "type": "number", "format": "float", "example": 380 }, "captains_owed": { "type": "integer", "example": 1 }, "captains_owing": { "type": "integer", "example": 1 } }, "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" }, "Order": { "description": "A delivery order as the back office sees it (internal note included).", "properties": { "uuid": { "description": "A delivery order as exposed by OrderResource: the customer, the addresses, the payment, the\nfee, the pickup item check, and — when loaded — the carrying captain, the items and the\nstatus history.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e342" }, "order_number": { "type": "string", "example": "ORD-100002" }, "customer_name": { "type": "string", "example": "Khalid Al Ghamdi" }, "customer_phone": { "type": "string", "example": "+966500000101", "nullable": true }, "pickup_address": { "type": "string", "example": "Store 12, Granada Mall, Riyadh" }, "dropoff_address": { "description": "The delivery address.", "type": "string", "example": "Olaya Street, Riyadh" }, "pickup_lat": { "type": "number", "format": "float", "example": 24.803625499999998993416738812811672687530517578125, "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "example": 46.69935459999999949332050164230167865753173828125, "nullable": true }, "dropoff_lat": { "type": "number", "format": "float", "example": 24.6887535999999983005182002671062946319580078125, "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "example": 46.680810600000000931686372496187686920166015625, "nullable": true }, "customer_note": { "description": "What the customer asked for; shown to the captain.", "type": "string", "example": "Call on arrival.", "nullable": true }, "note": { "description": "Internal note for the operations team; never shown to the captain.", "type": "string", "example": "Repeat customer.", "nullable": true }, "fee": { "type": "number", "format": "float", "example": 18.5, "nullable": true }, "currency": { "type": "string", "example": "SAR", "nullable": true }, "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": { "description": "Cash the captain collects; always null for prepaid.", "type": "number", "format": "float", "example": 92.5, "nullable": true }, "status": { "type": "string", "example": "on_the_way", "enum": [ "pending", "assigned", "accepted", "picked_up", "on_the_way", "delivered", "delivery_failed", "cancelled" ] }, "status_label": { "type": "string", "example": "On the way" }, "offer_expires_at": { "description": "When an unanswered offer is taken back and the order returns to the pool.", "type": "string", "format": "date-time", "example": "2026-09-26T14:20:30+03:00", "nullable": true }, "accepted_at": { "description": "When the captain accepted. Null while the offer is still open.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "driver": { "oneOf": [ { "$ref": "#/components/schemas/Driver" } ], "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "example": [] }, "items_expected": { "description": "Sum of the product quantities.", "type": "integer", "example": 3 }, "items_collected": { "description": "Count the captain confirmed at pickup; null if not confirmed.", "type": "integer", "example": 2, "nullable": true }, "items_mismatch": { "description": "True when the confirmed count differs from items_expected.", "type": "boolean", "example": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/OrderHistory" }, "example": [] }, "cancelled_at": { "description": "Only ever set on an order that ended that way.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "cancel_reason": { "description": "Why the order was called off. Always present on a cancelled order - the endpoint requires it.", "type": "string", "example": null, "nullable": true }, "failed_reason": { "type": "string", "example": null, "nullable": true }, "proof_of_delivery": { "description": "The photo the captain sent with the delivery, and the only evidence behind a disputed one. Null until an order is delivered with a photo.", "type": "string", "format": "uri", "example": "https://api.kapitano.shop/storage/42/doorstep.jpg", "nullable": true }, "amount_paid": { "description": "What a captain paid the supplier for this order.", "type": "number", "format": "float", "example": 300, "nullable": true }, "amount_collected": { "description": "What a captain took from the customer for this order.", "type": "number", "format": "float", "example": 380, "nullable": true }, "settlement": { "description": "On the detail read only. Every movement of money on the order and the captain behind each - the captain who paid and the captain who collected need not be the same person.", "properties": { "expected_goods_cost": { "type": "number", "format": "float", "example": 300, "nullable": true }, "amount_to_collect": { "type": "number", "format": "float", "example": 380, "nullable": true }, "amount_paid": { "type": "number", "format": "float", "example": 300, "nullable": true }, "amount_collected": { "type": "number", "format": "float", "example": 380, "nullable": true }, "entries": { "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "supplier_payment", "cash_collected", "cash_paid_out", "cash_handed_in", "adjustment" ] }, "type_label": { "type": "string" }, "amount": { "description": "Signed. Positive = the company owes the captain.", "type": "number", "format": "float" }, "currency": { "type": "string" }, "expected_amount": { "type": "number", "format": "float", "nullable": true }, "variance": { "type": "number", "format": "float", "nullable": true }, "captain": { "properties": { "uuid": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-10 08:36:51" } }, "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 } }, "type": "object" }, "OrderHistory": { "description": "One step in an order's status timeline.", "properties": { "uuid": { "description": "A status step of an order's timeline.", "type": "string", "format": "uuid", "example": "01a08600-878b-726b-8df7-0c1bc4374db6" }, "status": { "type": "string", "example": "assigned", "enum": [ "pending", "assigned", "accepted", "picked_up", "on_the_way", "delivered", "delivery_failed", "cancelled" ] }, "status_label": { "type": "string", "example": "Assigned" }, "note": { "type": "string", "example": null, "nullable": true }, "actor": { "description": "Name of the admin or captain who caused the change.", "type": "string", "example": "Monte Kilback", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-09 14:49:36" } }, "type": "object" }, "SuggestionList": { "description": "The ranked captains for an order, with how the list was found and what it cost.", "properties": { "suggestion_uuid": { "description": "The Suggestion Log entry this list was written to.", "type": "string", "format": "uuid", "example": "01a0b389-019d-7a5c-9f7e-3d1b0c2a4e77" }, "candidates": { "description": "Best first. Empty when nobody could be offered — see no_candidates_reason.", "type": "array", "items": { "$ref": "#/components/schemas/SuggestionCandidate" } }, "radius_km": { "description": "The radius the search settled on.", "type": "number", "format": "float", "example": 5 }, "search_expanded": { "description": "True when the first radius held too few captains and the search had to widen.", "type": "boolean", "example": false }, "excluded_stale": { "description": "Captains set aside because their GPS point was too old to trust. Reported, never hidden.", "type": "array", "items": { "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" } }, "routing_elements": { "description": "How many origin-destination pairs the routing engine was asked for.", "type": "integer", "example": 3 }, "cache_hit": { "description": "Whether the routing answer came from the suggestion cache.", "type": "boolean", "example": false }, "ranking_degraded": { "description": "True when the routing engine could not answer and the list is ranked on straight-line estimates.", "type": "boolean", "example": false }, "degraded_reason": { "type": "string", "example": null, "nullable": true, "enum": [ "routing_timeout", "routing_error", "routing_partial", "routing_not_configured" ] }, "degraded_reason_label": { "description": "The reason translated for the screen.", "type": "string", "example": null, "nullable": true }, "no_candidates_reason": { "description": "Why the list is empty, translated. Null whenever there are candidates.", "type": "string", "example": null, "nullable": true }, "timings": { "$ref": "#/components/schemas/SuggestionTimings" }, "total_ms": { "description": "How long the whole pipeline took.", "type": "integer", "example": 96 } }, "type": "object" }, "SuggestionCandidate": { "description": "One captain on a suggestion list, with every number that put them in their place. Times are minutes; the Suggestion Log keeps the seconds.", "properties": { "rank": { "description": "1 is the best suggestion.", "type": "integer", "example": 1 }, "captain": { "properties": { "uuid": { "type": "string", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "type": "string", "example": "Faisal Al Harbi" }, "employment_type": { "description": "Which arrangement the captain is on. Only an employee may be directed with assign-enforced; a freelancer has to be offered the order.", "type": "string", "example": "employee", "enum": [ "employee", "freelance" ] }, "employment_type_label": { "type": "string", "example": "Employee captain" } }, "type": "object" }, "state": { "description": "Whether the captain is free, carrying an order but able to take another, or at their limit. The other states the enum holds (offline, on_break, unapproved) never reach a list: eligibility removes them first.", "type": "string", "example": "idle", "enum": [ "idle", "batchable", "full" ] }, "state_label": { "type": "string", "example": "Idle" }, "at_store_batch": { "description": "True when the captain is already at this pickup, so the order can be handed over without a trip.", "type": "boolean", "example": false }, "gps_freshness": { "type": "string", "example": "fresh", "enum": [ "fresh", "aging", "stale", "missing" ] }, "distance_km": { "description": "Straight-line distance from the point the captain is judged from to the pickup.", "type": "number", "format": "float", "example": 1.520000000000000017763568394002504646778106689453125 }, "road_eta_min": { "description": "Road time to the pickup.", "type": "number", "format": "float", "example": 4.5, "nullable": true }, "remaining_delivery_eta_min": { "description": "Time left on the delivery the captain is already carrying. Zero for an idle captain.", "type": "number", "format": "float", "example": 0, "nullable": true }, "handoff_buffer_min": { "description": "Allowance for handing the current order over. Zero for an idle captain.", "type": "number", "format": "float", "example": 0, "nullable": true }, "adjusted_eta_min": { "description": "The number the list is ranked by: the three above added together.", "type": "number", "format": "float", "example": 4.5, "nullable": true }, "detour_delta_min": { "description": "How much longer the current customer waits if this order is added. Null when nothing would be batched.", "type": "number", "format": "float", "example": null, "nullable": true }, "batch_verdict": { "description": "Whether this order may ride along with the one the captain is carrying. `not_applicable` for an idle captain; the two rejections say whether the current customer would wait too long or their promised time would be missed.", "type": "string", "example": "not_applicable", "enum": [ "not_applicable", "accepted", "rejected_detour", "rejected_promise" ] }, "eta_estimated": { "description": "True when the time was estimated from the straight-line distance because the routing engine did not answer.", "type": "boolean", "example": false }, "reasons": { "description": "Why this captain is on the list and in this place, translated and ready to show.", "type": "array", "items": { "type": "string" }, "example": [ "Idle — no orders in progress." ] } }, "type": "object" }, "SuggestionTimings": { "description": "What each phase cost, in milliseconds. Measured and logged, never enforced: a slow phase is recorded rather than abandoned, because half a list helps nobody.", "properties": { "filter_ms": { "description": "Narrowing every captain down to the shortlist. No routing engine is called here.", "type": "integer", "example": 12 }, "routing_ms": { "description": "Pricing the shortlist: road times and the batch checks.", "type": "integer", "example": 71 }, "assembly_ms": { "description": "Ranking and building the answer.", "type": "integer", "example": 13 } }, "type": "object" }, "PushSendOutcome": { "description": "What Firebase answered for a push to one recipient, read back from the delivery log.", "properties": { "Model": { "properties": { "sent": { "description": "At least one device was accepted by Firebase.", "type": "boolean", "example": false }, "devices": { "type": "integer", "example": 1 }, "delivered": { "description": "Null when the delivery log is switched off.", "type": "integer", "example": 0, "nullable": true }, "failed": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" }, "Status": { "type": "boolean", "example": true }, "Message": { "type": "string", "example": "Firebase rejected the notification on 1 of 1 device(s). The delivery log shows why." } }, "type": "object" }, "PushBroadcast": { "description": "A broadcast, who sent it, and how far it got.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "example": "Eid holiday" }, "body": { "type": "string" }, "audience": { "type": "string", "enum": [ "all", "online", "captains" ] }, "audience_label": { "type": "string", "example": "All approved captains" }, "target_count": { "description": "Captains the audience resolved to, with or without a device.", "type": "integer", "example": 240 }, "status": { "type": "string", "enum": [ "queued", "sending", "completed" ] }, "status_label": { "type": "string", "example": "Completed" }, "counts": { "properties": { "reached": { "description": "Devices Firebase accepted.", "type": "integer", "example": 212 }, "failed": { "type": "integer", "example": 4 } }, "type": "object" }, "sent_by": { "properties": { "uuid": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "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" }, "Settlement": { "properties": { "uuid": { "description": "One payment between us and a store.\n\nThe amounts are a snapshot of what both sides agreed on the day, not a live view. They do not\nmove if an order is corrected afterwards — a payment already made must not change underneath\nthe people holding it.", "type": "string", "format": "uuid" }, "reference": { "description": "The bank or transfer reference.", "type": "string", "nullable": true }, "period": { "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "type": "object" }, "cash_collected": { "type": "number" }, "fees_charged": { "type": "number" }, "net_amount": { "description": "What is actually paid. May be negative when fees exceeded the cash collected.", "type": "number" }, "currency": { "type": "string" }, "orders_count": { "type": "integer" }, "status": { "description": "A draft is ours; the store never sees one.", "type": "string", "enum": [ "draft", "settled", "cancelled" ] }, "status_label": { "type": "string" }, "settled_at": { "type": "string", "format": "date-time", "nullable": true }, "note": { "type": "string", "nullable": true }, "created_by": { "description": "Who drew it up.", "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "StoreClient": { "properties": { "uuid": { "description": "A store that feeds us orders, as the back office reads it.\n\nNo secret appears here. Support can read a store's whole configuration without being able to\nread its signing key — those come only from the store's own portal, behind its own password.", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Fresh Market" }, "slug": { "description": "Our handle. Appears in rate-limit keys and logs, so it is never editable.", "type": "string", "example": "fresh-market" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "suspended" ] }, "status_label": { "type": "string" }, "is_active": { "description": "The operational pause switch, separate from the review status.", "type": "boolean" }, "is_live": { "description": "Approved **and** not paused. Only then do orders flow.", "type": "boolean" }, "review_note": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "webhook_url": { "type": "string", "nullable": true }, "allowed_ips": { "description": "Empty means the check is off.", "type": "array", "items": { "type": "string" } }, "default_currency": { "type": "string", "example": "SAR" }, "timezone": { "type": "string", "example": "Asia/Riyadh" }, "secrets": { "description": "Metadata only — never the values.", "properties": { "has_secrets": { "type": "boolean" }, "rotated_at": { "type": "string", "format": "date-time", "nullable": true }, "previous_valid_until": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "StoreUser": { "properties": { "uuid": { "description": "A person at a store who can sign in to the store portal.", "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "description": "Their sign-in identifier, unique across every store.", "type": "string", "format": "email" }, "phone": { "description": "Where their recovery codes go.", "type": "string" }, "role": { "type": "string", "enum": [ "owner", "staff" ] }, "role_label": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "status_label": { "type": "string" }, "is_active": { "type": "boolean" }, "can_manage_integration": { "description": "True for an owner.", "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "WebhookDelivery": { "properties": { "uuid": { "description": "One attempt to tell a store something.\n\nThe raw `payload` is kept because the first disagreement with an external partner is always\n\"we sent it\" — and without the bytes there is nothing to settle it with.", "type": "string", "format": "uuid" }, "event": { "type": "string", "example": "order.delivered" }, "event_label": { "type": "string" }, "event_id": { "description": "The store's deduplication key. A retry carries the same one.", "type": "string", "format": "uuid" }, "sequence": { "description": "Increases per order. Null on a connection test.", "type": "integer", "nullable": true }, "status": { "description": "`dropped` means six attempts were exhausted and a human has to look.", "type": "string", "enum": [ "pending", "sent", "failed", "dropped" ] }, "status_label": { "type": "string" }, "attempts": { "type": "integer" }, "url": { "type": "string" }, "response_status": { "type": "integer", "nullable": true }, "response_body": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "payload": { "description": "Exactly what was sent.", "type": "object" }, "order": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string" }, "external_order_id": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "store": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "type": "object", "nullable": true } }, "type": "object" } }, "securitySchemes": { "adminAuth": { "type": "http", "description": "Bearer token issued by POST /api/dashboard/auth/login. Enter in format (Bearer ).", "bearerFormat": "Sanctum", "scheme": "bearer" } } }, "tags": [ { "name": "Dashboard — Cash Desk", "description": "What captains paid out of their own pockets at suppliers, what they took from customers, and\nthe cash that clears the difference. The company sits in the middle: captains never owe each\nother.\n\n**Positive means the company owes the captain**; negative means the captain owes the company.\nEvery figure is per currency and never summed across them.\n\n**Cash only ever moves towards zero.** Pay out to a captain who is owed, take cash from one\nwho owes, never past their balance. Anything else is a correction and goes through `adjust`,\nwhich requires a reason." }, { "name": "Dashboard — Authentication", "description": "Back office sign in and password recovery." }, { "name": "Dashboard — Profile", "description": "The signed in admin's own account." }, { "name": "Dashboard — Admins", "description": "Management of the other back office accounts." }, { "name": "Dashboard — Roles & Permissions", "description": "The role catalogue and the permissions behind it." }, { "name": "Dashboard — Captains", "description": "The review queue, decisions and corrections." }, { "name": "Dashboard — Vehicles", "description": "The vehicles captains drive: list, detail, records, photos, documents and activation." }, { "name": "Dashboard — Orders", "description": "Order list, detail, creation and manual assignment." }, { "name": "Dashboard — Dispatch", "description": "Captain dispatch: the business values the algorithm runs on." }, { "name": "Dashboard — Push Notifications", "description": "The push delivery log, its health, registered devices and a test push." }, { "name": "Dashboard — Store integration", "description": "Dashboard — Store integration" }, { "name": "Dashboard — Notifications", "description": "Dashboard — Notifications" }, { "name": "Dashboard — Settlements", "description": "Dashboard — Settlements" }, { "name": "Dashboard — Stats", "description": "Dashboard — Stats" }, { "name": "Dashboard — Stores", "description": "Dashboard — Stores" } ] }