{ "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": "SYP" } ], "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": "SYP" }, { "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": { "SYP": 300 } }, "Totals": { "description": "currency => what that balance is made of. A cashier settling up is answering \"how did this number happen?\", and a net balance cannot say.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CaptainBalanceBreakdown" } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "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 `SYP`. `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": "SYP", "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": "SYP", "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/cash-hand-ins": { "get": { "tags": [ "Dashboard — Cash Desk" ], "summary": "Captains waiting to hand cash in", "description": "Captains who have said they are bringing the company's cash in and have not been answered\nyet, **oldest first** — the queue serves whoever has been waiting, not the largest sum.\n\n`declared_amount` is a claim and nothing more: while a row is here the captain still owes\nevery riyal of it and their balance is untouched. `Totals` is what the desk should expect\nto receive per currency, with how many captains it is spread across.\n\nRequires `captain_ledger.view`.", "operationId": "cashHandInQueue", "parameters": [ { "name": "rows", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 10 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 3, "minLength": 3 }, "example": "SYP" } ], "responses": { "200": { "description": "The queue, and what it adds up to.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/CashHandIn" } }, "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 => {declared, captains, hand_ins}", "type": "object", "additionalProperties": { "type": "object" } } }, "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" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/cash-hand-ins/{uuid}/confirm": { "post": { "tags": [ "Dashboard — Cash Desk" ], "summary": "The cash is in the drawer", "description": "**This is the call that clears the balance**, because it is the only point at which the\ncompany has the money.\n\n`amount` is what was actually counted. It defaults to the declared figure, and it is allowed\nto be less: a captain fifty short is recorded as fifty short, the ledger moves by what\narrived, and the captain keeps owing the difference. Making the two agree would only mean\nthe gap went unwritten.\n\nThe movement is written by the same service a manual hand-in goes through, so the direction\ncheck, the ceiling at the outstanding balance and the lock against two cashiers taking the\nsame cash twice all apply here unchanged. The entry it wrote comes back as\n`ledger_entry_uuid`.\n\nRequires `captain_ledger.settle` — reading the desk is not enough to move money.", "operationId": "cashHandInConfirm", "parameters": [ { "name": "uuid", "in": "path", "description": "Hand-in UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "amount": { "description": "What was counted. Defaults to the declared figure.", "type": "number", "format": "float", "example": 350, "nullable": true }, "reference": { "type": "string", "example": "VCH-9001", "nullable": true, "maxLength": 100 }, "note": { "type": "string", "nullable": true, "maxLength": 255 } }, "type": "object" } } } }, "responses": { "201": { "description": "Received. The balance has moved.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CashHandIn" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.settle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such hand-in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "Already answered — a second confirmation would take the cash twice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "A zero amount, or more than the captain owes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/cash-hand-ins/{uuid}/decline": { "post": { "tags": [ "Dashboard — Cash Desk" ], "summary": "The cash never arrived", "description": "The captain did not come, or what they brought did not match at all. The balance is left\nexactly where it was: the captain is still holding the company's cash.\n\nA reason is required. The next person to look at that balance needs to know why the last\nattempt failed, and it is shown to the captain in their app.\n\nRequires `captain_ledger.settle`.", "operationId": "cashHandInDecline", "parameters": [ { "name": "uuid", "in": "path", "description": "Hand-in UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "note" ], "properties": { "note": { "type": "string", "example": "The captain never came to the office.", "maxLength": 255, "minLength": 3 } }, "type": "object" } } } }, "responses": { "200": { "description": "Turned away. The balance is unchanged.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/CashHandIn" }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing captain_ledger.settle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such hand-in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "Already answered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "No reason given.", "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/cities": { "get": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "Every city with its districts", "description": "The whole tree, unpaginated: this is a map of where the company works, read as a whole by the\nscreen that edits it. A page of cities would be a page of something nobody thinks of in pages.\n\nEach city carries `districts_with_own_earning` — how many of its districts would be\noverwritten by a rate change — so the editing screen can warn before it asks, without a\nsecond request.\n\nRequires `cities.view`.", "operationId": "citiesIndex", "responses": { "200": { "description": "The tree.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/City" } }, "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 cities.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "Add a city or a district", "description": "With `parent_uuid` this is a district inside that city; without it, a city.\n\n**A district left without `delivery_earning` inherits its city's**, which is the ordinary\ncase: somebody adding six districts to a city they have already priced should not type the\nsame figure six times, because five of them end up right. A **city** without one is refused —\nthere is nothing above it to inherit from, so silence would mean every delivery there earns\nnothing until somebody noticed.\n\nA district cannot be given a parent that is itself a district: the tree is two deep.\n\nRequires `cities.manage`.", "operationId": "citiesStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "lat", "lng", "radius_m" ], "properties": { "name": { "type": "string", "example": "Mezzeh", "maxLength": 120 }, "parent_uuid": { "description": "The city this district belongs to. Omit for a city.", "type": "string", "format": "uuid", "nullable": true }, "lat": { "type": "number", "format": "float", "example": 33.50750000000000028421709430404007434844970703125 }, "lng": { "type": "number", "format": "float", "example": 36.24000000000000198951966012828052043914794921875 }, "radius_m": { "type": "integer", "example": 1000, "maximum": 100000, "minimum": 100 }, "delivery_earning": { "description": "Omit on a district to follow the city's rate.", "type": "number", "format": "float", "example": 8000, "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Added.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/City" }, "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 cities.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "A city with no rate, a third level, or a name already used in that city.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/cities/{uuid}": { "get": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "One area, with its districts", "operationId": "citiesShow", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The area.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/City" }, "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 cities.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such area.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "delete": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "Remove an area that nothing depends on", "description": "Refused with `409` while a city still has districts, and refused while any delivery earning\nnames the area: money that has been paid keeps its explanation. The answer to \"we no longer\ndeliver there\" is `is_active: false`, which stops new deliveries matching it and leaves its\nhistory readable.\n\nRequires `cities.manage`.", "operationId": "citiesDestroy", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "string", "example": null, "nullable": true }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing cities.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such area.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "It still has districts, or captains have been paid for deliveries there.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } } }, "security": [ { "adminAuth": [] } ] }, "patch": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "Change an area, and decide what that does below it", "description": "Every field is optional; what is absent is left alone.\n\n**On a city, `delivery_earning` cascades.** Districts that have never been given a rate of\ntheir own always follow. Districts somebody set deliberately are left alone **unless**\n`overwrite_own_children` is true — and a district overwritten that way is marked as following\nthe city from then on, which is what \"overwrite\" was asked to mean.\n\n**On a district, nothing cascades upward.** Pricing a district never changes its city. That\nasymmetry is the whole point of the feature.\n\n`inherit: true` puts a district back on its city's rate. Sending it together with\n`delivery_earning` is refused rather than resolved by precedence — two different rates in one\nrequest is not a request anybody should have to remember the direction of.\n\nThe response carries `Districts`: how many followed, how many were overwritten, and how many\nkept their own rate. \"Saved\" is not an answer to a question that may have changed nine rows.\n\nRequires `cities.manage`.", "operationId": "citiesUpdate", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 120 }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "radius_m": { "type": "integer", "maximum": 100000, "minimum": 100 }, "delivery_earning": { "type": "number", "format": "float", "example": 7000 }, "inherit": { "description": "Put this district back on its city's rate.", "type": "boolean", "example": false }, "overwrite_own_children": { "description": "Reset districts that carry their own rate.", "type": "boolean", "example": false }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Changed, and what it did below.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/City" }, "Status": { "type": "boolean", "example": true }, "Districts": { "properties": { "followed": { "type": "integer", "example": 2 }, "overwritten": { "type": "integer", "example": 0 }, "kept": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing cities.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such area.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "422": { "description": "A rate and `inherit` together, or `inherit` on a city.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/delivery-earnings": { "get": { "tags": [ "Dashboard — Cities and earnings" ], "summary": "What deliveries have earned, and what each area cost", "description": "Every delivery earning, newest first, with `Totals` per currency and `ByCity` — the same\nfiltered set grouped by area, largest first, which is the reason to read this report.\n\n**The rows that earned nothing are in here on purpose.** Filter `status=unresolved` to see\nthe deliveries whose drop-off matched no area: that list is both the money nobody was paid and\nthe map of where a district is missing. `Totals..unresolved` carries the count beside\nthe money, because a week that looks cheap because eleven deliveries never resolved is a\ndifferent problem from a quiet week.\n\n`city_uuid` on a city means **the city and every district inside it**. A filter naming a\ncaptain or an area that does not exist answers with an empty page, never with everything.\n\nNothing here is recomputed: every figure was written at the moment of delivery, and a report\nthat recalculated would be free to disagree with the balance it exists to explain.\n\nRequires `cities.view`.", "operationId": "deliveryEarningsIndex", "parameters": [ { "name": "rows", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1 }, "example": 15 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 1 }, { "name": "captain_uuid", "in": "query", "description": "Captain ULID.", "required": false, "schema": { "type": "string" } }, { "name": "city_uuid", "in": "query", "description": "A city (with its districts) or one district.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "credited", "unresolved" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Inclusive: the whole day it names.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "A page of earnings, its totals, and the same set by area.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryEarning" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Pages.", "type": "integer", "example": 1 }, "Page": { "type": "integer", "example": 1 }, "Records": { "type": "integer", "example": 3 }, "Totals": { "description": "currency => {earned, deliveries, unresolved}", "type": "object", "additionalProperties": { "type": "object" } }, "ByCity": { "type": "array", "items": { "properties": { "city": { "description": "Null names the unresolved bucket.", "type": "string", "nullable": true }, "parent": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "earned": { "type": "number", "format": "float" }, "deliveries": { "type": "integer" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing cities.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "422": { "description": "A window that ends before it starts, or an unknown status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/delivery-fee-tiers": { "get": { "tags": [ "Dashboard — Delivery pricing" ], "summary": "Every pricing ladder", "description": "The company ladder first, then each store's, cheapest band first inside either.\n\nUnpaginated on purpose: a ladder is read whole or not at all, and a page of one is a page of\nsomething nobody thinks of in pages.\n\nRequires `delivery_fees.view`.", "operationId": "deliveryFeeTiersIndex", "responses": { "200": { "description": "Every band there is.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryFeeTier" } }, "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 delivery_fees.view.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } } }, "security": [ { "adminAuth": [] } ] }, "post": { "tags": [ "Dashboard — Delivery pricing" ], "summary": "Add a band to a ladder", "description": "With `store_uuid` the band joins that store's own ladder, which then prices **all** of its\norders — a store with one negotiated band does not fall back to the company ladder for the\nbaskets that band does not cover, because a price assembled from two documents is one nobody\nagreed to. Without it, the band joins the company ladder.\n\n`max_goods_value` is optional: leaving it out means \"and above\", which is where free delivery\nusually sits. The floor is inclusive and the ceiling exclusive, so `0–100,000` and\n`100,000–300,000` meet without both covering 100,000.\n\n**Overlapping bands answer `409`**, naming the band they clash with. Two bands covering one\norder value would make the fee a coin toss, and the alternative — a priority column — is where\na pricing table stops being readable and starts being something you have to simulate.\n\nRequires `delivery_fees.manage`.", "operationId": "deliveryFeeTiersStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "min_goods_value", "fee" ], "properties": { "store_uuid": { "description": "Omit for the company ladder.", "type": "string", "format": "uuid", "example": null, "nullable": true }, "min_goods_value": { "type": "number", "format": "float", "example": 300000 }, "max_goods_value": { "description": "Omit for \"and above\".", "type": "number", "format": "float", "example": null, "nullable": true }, "fee": { "description": "Zero is free delivery.", "type": "number", "format": "float", "example": 0 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Added.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/DeliveryFeeTier" }, "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 delivery_fees.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "409": { "description": "The range overlaps an existing band on the same ladder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "A ceiling at or below the floor, or an unknown store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" } } } } }, "security": [ { "adminAuth": [] } ] } }, "/api/dashboard/delivery-fee-tiers/{uuid}": { "delete": { "tags": [ "Dashboard — Delivery pricing" ], "summary": "Retire a band", "description": "Allowed even where orders were priced by it. They keep the fee they were charged as a number of\ntheir own and only their pointer to the rule goes null, so retiring last season's offer never\nrewrites what a store was billed.\n\nRequires `delivery_fees.manage`.", "operationId": "deliveryFeeTiersDestroy", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Retired.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "string", "example": null, "nullable": true }, "Status": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Token missing, revoked, or headers missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "403": { "description": "Missing delivery_fees.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such band.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "security": [ { "adminAuth": [] } ] }, "patch": { "tags": [ "Dashboard — Delivery pricing" ], "summary": "Change a band", "description": "Everything is optional; what is absent is left alone. The ladder a band sits on is **not**\neditable — moving one between a store and the company would be two different negotiations in a\nsingle request.\n\n`clear_max: true` opens the band up to \"and above\". It exists because a null in JSON cannot be\ntold apart from a field nobody sent, so removing a ceiling needs a word of its own. Sending it\ntogether with `max_goods_value` is refused rather than resolved by precedence.\n\nThe overlap check runs again on the new range, ignoring this band itself.\n\nRequires `delivery_fees.manage`.", "operationId": "deliveryFeeTiersUpdate", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "min_goods_value": { "type": "number", "format": "float" }, "max_goods_value": { "type": "number", "format": "float" }, "clear_max": { "description": "Remove the ceiling: this band runs to infinity.", "type": "boolean", "example": false }, "fee": { "type": "number", "format": "float" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Changed.", "content": { "application/json": { "schema": { "properties": { "Model": { "$ref": "#/components/schemas/DeliveryFeeTier" }, "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 delivery_fees.manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorForbidden" } } } }, "404": { "description": "No such band.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } }, "409": { "description": "The new range overlaps another band.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorConflict" } } } }, "422": { "description": "A ceiling at or below the floor, or both a ceiling and `clear_max`.", "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": "SYP", "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": "SYP" } } } }, "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/orders/awaiting-collection": { "get": { "tags": [ "Dashboard — Orders" ], "summary": "Deliveries that cannot be assigned yet, longest block first", "description": "Wrapped orders whose goods have not reached the wrapping shop yet.\n\nSome stores have their goods wrapped before delivery. Such an order is **two rows**: a\ncollection leg that gathers the goods from the suppliers and leaves them with the\nwrapper, and a delivery leg — the store's own order — that collects the finished parcel\nand takes it to the customer. The first captain is released as soon as they hand the\ngoods over, which is why these are two orders rather than one.\n\nThe delivery leg sits in ordinary `pending` the whole time. It is **not** given a status\nof its own, because whether its parcel is ready is already recorded completely by the\ncollection leg: a second copy on this row would be free to drift, and would need\nsomebody to press a button to restate what the system already knows. Instead, assignment\nis refused with **409** until every collection leg has reached `delivered`, and this\nendpoint lists the orders in that state so nobody has to find out by clicking.\n\n**Oldest first**, the opposite of every other list here: the order blocked longest is the\none that needs looking at.\n\nEach row carries `can_be_assigned`, `assignment_blocked_reason` and `collection_legs`\nwith their status and any failure reason. A collection leg in `delivery_failed` blocks\npermanently — the goods never arrived — and the back office is notified separately so\nsomebody can send another captain for them or call the order off.\n\nNeeds `orders.view`, the same grant as the order list.", "operationId": "dashboardOrdersAwaitingCollection", "parameters": [ { "name": "rows", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 }, "example": 15 }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "The blocked deliveries, longest block first.", "content": { "application/json": { "schema": { "properties": { "Model": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "Status": { "type": "boolean", "example": true }, "Total": { "description": "Total pages.", "type": "integer", "example": 1 }, "Page": { "type": "integer", "example": 1 }, "Records": { "description": "Total orders blocked.", "type": "integer", "example": 3 } }, "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" } } } } }, "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": { "description": "The silent payload the app reads to decide what to open. **Every value is a string** — FCM carries no other type, so a count arrives as `\"4\"` and a flag as `\"1\"`. `type` says which message it is; the remaining keys depend on it.", "type": "object", "example": { "type": "route_plan.updated", "route_plan_uuid": "01a0e992-5c6a-7057-ba53-de235553a5bb", "version": "20", "stops": "4" }, "nullable": true, "additionalProperties": { "type": "string" } }, "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": "SYP" }, "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": "SYP", "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" }, "wrapping_name": { "type": "string", "nullable": true, "maxLength": 255 }, "wrapping_address": { "description": "Sent together with both coordinates, or all three cleared to switch wrapping off. A wrapping shop with no point on the map is not a place a captain can be sent.", "type": "string", "nullable": true, "maxLength": 255 }, "wrapping_lat": { "type": "number", "format": "float", "nullable": true, "maximum": 90, "minimum": -90 }, "wrapping_lng": { "type": "number", "format": "float", "nullable": true, "maximum": 180, "minimum": -180 } }, "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": "SYP" }, "expected_amount": { "description": "What the system expected: the goods cost for a supplier payment, `amount_to_collect` for a collection. Null for a desk movement.", "type": "number", "format": "float", "example": 300, "nullable": true }, "variance": { "description": "Actual minus expected. Null when nothing was expected.", "type": "number", "format": "float", "example": 0, "nullable": true }, "has_variance": { "type": "boolean", "example": false }, "order": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string", "example": "ORD-100002" } }, "type": "object", "nullable": true }, "pickup": { "description": "Which counter the money changed hands at, on a payment made to one supplier of a multi-supplier order. This is what turns \"the order was 4,000 short\" into \"the second shop was\", and it is the difference between an office ringing the captain and an office ringing the right shop. Null on an order collected in one tap, and on every desk movement.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "store_name": { "type": "string", "example": "بيت العود", "nullable": true }, "address": { "type": "string", "example": "شارع الثورة، دمشق" } }, "type": "object", "nullable": true }, "captain": { "description": "Whose line it is. Present on the money feed, where every row is a different person; absent from a statement that already names one captain beside the page.", "properties": { "uuid": { "description": "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": "SYP" }, "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" }, "CaptainBalanceBreakdown": { "description": "What a balance is actually made of, keyed by currency. The balance on its own is one number standing in for four different things, and two of them ask opposite actions: money the company owes a captain is theirs to claim, cash they are holding belongs to somebody else. Reported as plain positive totals with names that say the direction, so nothing has to be inferred from a sign.", "properties": { "paid_to_suppliers": { "description": "What the captain paid out of pocket at suppliers.", "type": "number", "format": "float", "example": 140 }, "collected_from_customers": { "description": "What they took from customers on delivery.", "type": "number", "format": "float", "example": 200 }, "earned_from_deliveries": { "description": "What the deliveries themselves earned them — their own pay, not money passing through their hands.", "type": "number", "format": "float", "example": 0 }, "reimbursed_by_desk": { "description": "What the cashier has already paid back to them.", "type": "number", "format": "float", "example": 0 }, "handed_in_at_desk": { "description": "What they have already handed in.", "type": "number", "format": "float", "example": 0 }, "adjustments": { "description": "Signed, because a correction is the one entry whose meaning is \"this much, this way\" - flattening it to a magnitude would hide which way it went.", "type": "number", "format": "float", "example": 0 }, "balance": { "description": "The signed net, unchanged: positive still means the company owes the captain. Every movement is inside exactly one of the parts above, so none of this balance is unaccounted for — reading them back to it means applying the direction each name states, since the parts themselves are magnitudes.", "type": "number", "format": "float", "example": -60 } }, "type": "object" }, "CashHandIn": { "description": "A captain saying they are bringing the company's cash in, and what the desk did about it.\n\n**`declared_amount` is a claim, not money.** While the status is `pending` nothing in the ledger\nhas moved and the captain still owes every riyal of it: a screen drawing the declared figure as\nsettled would be telling an operator the company holds cash that is still in somebody's pocket.\n\n`confirmed_amount` is the money — it exists once somebody has counted it — and it is allowed to\ndiffer from the declaration. `shortfall` is the gap, positive when the desk received **less** than\nwas promised, which is the number worth looking at.", "properties": { "uuid": { "description": "A captain's declared cash hand-in.", "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "confirmed", "declined", "cancelled" ] }, "status_label": { "type": "string", "example": "Waiting for the desk" }, "currency": { "type": "string", "example": "SYP" }, "declared_amount": { "description": "What the captain says they are bringing. Moves nothing.", "type": "number", "format": "float", "example": 380 }, "confirmed_amount": { "description": "What the desk counted. Null until it is counted.", "type": "number", "format": "float", "example": null, "nullable": true }, "shortfall": { "description": "Declared minus confirmed. Positive means less arrived than was promised.", "type": "number", "format": "float", "example": null, "nullable": true }, "captain": { "properties": { "uuid": { "description": "ULID", "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "ledger_entry_uuid": { "description": "The movement the confirmation wrote — the claim and the money, linked.", "type": "string", "format": "uuid", "nullable": true }, "decided_by": { "type": "string", "example": null, "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "captain_note": { "type": "string", "nullable": true }, "desk_note": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "City": { "description": "A city, or a district inside one, with the flat amount a captain earns for delivering there.\n\n**The tree is two deep.** A city holds districts; a district holds nothing. The depth is capped\nbecause what a captain is paid has to be explainable to that captain in one sentence.\n\n`delivery_earning` is always the figure **in force on this row**, whether it was typed here or\ncopied down from the city. `earning_source` is what says which, and it is the field an editing\nscreen turns on: a district marked `inherited` follows its city, and one marked `own` is a\ndecision somebody took that a later cascade must not silently destroy.\n\nThe geofence is a centre and a radius rather than a polygon: a hand-drawn boundary is a\nmaintenance job nobody does twice, and a radius is a figure an operations manager can correct\nfrom a map in seconds.", "properties": { "uuid": { "description": "A delivery area and what a delivery there earns a captain.", "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Mezzeh" }, "is_district": { "type": "boolean", "example": true }, "parent_uuid": { "type": "string", "format": "uuid", "nullable": true }, "parent_name": { "type": "string", "example": "Damascus", "nullable": true }, "lat": { "type": "number", "format": "float", "example": 33.50750000000000028421709430404007434844970703125 }, "lng": { "type": "number", "format": "float", "example": 36.24000000000000198951966012828052043914794921875 }, "radius_m": { "description": "How far the area reaches from its centre, in metres.", "type": "integer", "example": 1000 }, "delivery_earning": { "description": "What one delivery here earns a captain.", "type": "number", "format": "float", "example": 8000 }, "earning_source": { "type": "string", "example": "own", "enum": [ "own", "inherited" ] }, "earning_source_label": { "type": "string", "example": "Its own rate" }, "is_active": { "description": "An inactive area is skipped when a drop-off is placed, and keeps its history.", "type": "boolean", "example": true }, "districts": { "description": "Present on a city read as part of the tree; null on a district.", "type": "array", "items": { "$ref": "#/components/schemas/City" }, "nullable": true }, "districts_with_own_earning": { "description": "How many districts would be overwritten by a rate change here. The dashboard warns with this rather than asking a second time.", "type": "integer", "example": 1, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "DeliveryEarning": { "description": "One delivery's earning, and the record of where the figure came from.\n\nThe money itself is a `delivery_earning` entry in the captain's ledger — this row is the\nexplanation that outlives every later edit of the rate. The amount is **copied at the moment of\ndelivery**, so raising a district's rate tomorrow does not restate what captains were paid last\nweek.\n\n**`status: unresolved` means the delivery earned nothing**, because the drop-off fell inside no\narea on record or the order carried no coordinates. Such a row has a zero amount, no area and no\nledger entry, and it is written rather than skipped: a delivery nobody was paid for has to be\nvisible before payday, and `lat`/`lng` are the evidence for where an area is missing from the map.", "properties": { "uuid": { "description": "What one delivery earned a captain.", "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "credited", "enum": [ "credited", "unresolved" ] }, "status_label": { "type": "string", "example": "Paid" }, "currency": { "type": "string", "example": "SYP" }, "amount": { "description": "Zero on an unresolved row.", "type": "number", "format": "float", "example": 8000 }, "earning_source": { "description": "Whether the rate was the district's own or its city's, at the time.", "type": "string", "nullable": true, "enum": [ "own", "inherited" ] }, "earning_source_label": { "type": "string", "nullable": true }, "city": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Mezzeh" }, "parent_name": { "type": "string", "example": "Damascus", "nullable": true } }, "type": "object", "nullable": true }, "captain": { "properties": { "uuid": { "description": "ULID", "type": "string" }, "name": { "type": "string" } }, "type": "object", "nullable": true }, "order": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string" } }, "type": "object", "nullable": true }, "lat": { "description": "The point the resolution ran against.", "type": "number", "format": "float", "nullable": true }, "lng": { "type": "number", "format": "float", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "DeliveryFeeTier": { "description": "A range of merchandise value, and what the delivery costs **the store** inside it. A band whose\n`fee` is zero is the free-delivery offer.\n\n**This prices our invoice, not the customer's receipt.** `orders.fee` is the company's revenue;\n`orders.amount_to_collect` is what the shop told its customer to pay, and a ladder that lowered it\nwould be rewriting a figure somebody has already been given. A shop passing free delivery on to its\ncustomer lowers the amount to collect itself, when it sends the order.\n\n**`min_goods_value` is inclusive and `max_goods_value` is exclusive**, so adjacent bands meet\nwithout overlapping and a basket worth exactly 100,000 belongs to one of them. A null ceiling means\n\"and above\", which is where free delivery usually lives. Overlapping bands are refused outright\nrather than resolved by priority.\n\n**A ladder belongs either to one store or to everybody.** `store` null is the company default; a\nstore with bands of its own is priced by **those alone**, never by a mixture of the two.", "properties": { "uuid": { "description": "One band of a delivery pricing ladder.", "type": "string", "format": "uuid" }, "store": { "description": "Null names the company ladder, which every store without its own falls back to.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Al Nour Sweets" } }, "type": "object", "nullable": true }, "min_goods_value": { "description": "Inclusive floor.", "type": "number", "format": "float", "example": 300000 }, "max_goods_value": { "description": "Exclusive ceiling; null means \"and above\".", "type": "number", "format": "float", "example": null, "nullable": true }, "fee": { "description": "What the delivery costs the store in this band.", "type": "number", "format": "float", "example": 0 }, "is_free": { "description": "Carried rather than left for a screen to infer from `fee === 0`: free delivery is what these ladders exist for.", "type": "boolean", "example": true }, "is_active": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "Driver": { "description": "A captain application as exposed by the driver resources.", "properties": { "uuid": { "description": "A captain as exposed by DriverResource: the application record, its review state, the\ndocuments and, when loaded, the assigned vehicle.", "type": "string", "format": "uuid", "example": "01m24x34bzfbh7resdmkm55mmq" }, "name": { "type": "string", "example": "Abdulaziz Al Ajlan" }, "phone": { "type": "string", "example": "+966500000008" }, "email": { "type": "string", "example": "aziz.free@example.com", "nullable": true }, "national_id": { "type": "string", "example": "1000000008" }, "date_of_birth": { "type": "string", "format": "date", "example": "1991-11-28" }, "employment_type": { "type": "string", "example": "freelance", "enum": [ "employee", "freelance" ] }, "employment_type_label": { "type": "string", "example": "Freelance captain" }, "status": { "type": "string", "example": "approved", "enum": [ "pending", "documents_required", "approved", "rejected", "suspended" ] }, "status_label": { "type": "string", "example": "Approved" }, "review_note": { "type": "string", "example": null, "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59", "nullable": true }, "can_receive_orders": { "type": "boolean", "example": true }, "driving_license_number": { "type": "string", "example": "DL-10008" }, "driving_license_expires_at": { "type": "string", "format": "date", "example": "2029-09-12" }, "is_active": { "type": "boolean", "example": true }, "documents": { "description": "Only present when the media collection is loaded.", "properties": { "driving_license": { "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/3/%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%85%D9%84%D8%A7%D8%A8%D8%B3.png", "nullable": true }, "profile_photo": { "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/4/Mask.png", "nullable": true } }, "type": "object" }, "vehicle": { "oneOf": [ { "$ref": "#/components/schemas/Vehicle" } ], "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-10 08:36:47" } }, "type": "object" }, "Vehicle": { "description": "A vehicle belonging to a captain.", "properties": { "uuid": { "description": "A vehicle record: ownership type plus, for personal vehicles, the plate and appearance.", "type": "string", "format": "uuid", "example": "01a089d1-97c8-7108-bcde-a4ede59fd004" }, "ownership_type": { "type": "string", "example": "personal", "enum": [ "company_owned", "personal" ] }, "ownership_type_label": { "type": "string", "example": "Personal vehicle owned by the applicant" }, "vehicle_type": { "type": "string", "example": "car", "nullable": true, "enum": [ "motorcycle", "car", "van", "pickup_truck", "truck" ] }, "vehicle_type_label": { "type": "string", "example": "Car", "nullable": true }, "plate_number": { "type": "string", "example": "AZZ-8008", "nullable": true }, "brand": { "type": "string", "example": "GMC", "nullable": true }, "model": { "type": "string", "example": "Terrain", "nullable": true }, "manufacture_year": { "type": "integer", "example": 2021, "nullable": true }, "color": { "type": "string", "example": "red", "nullable": true }, "registration_number": { "type": "string", "example": "REG-8008", "nullable": true }, "registration_expires_at": { "type": "string", "format": "date", "example": "2027-09-30", "nullable": true }, "registration_status": { "description": "Worked out on the day of the request; expiring_soon = within 30 days.", "type": "string", "example": "valid", "enum": [ "missing", "expired", "expiring_soon", "valid" ] }, "registration_status_label": { "type": "string", "example": "Valid" }, "insurance_policy_number": { "type": "string", "example": "INS-8008", "nullable": true }, "insurance_expires_at": { "type": "string", "format": "date", "example": "2027-02-28", "nullable": true }, "insurance_status": { "type": "string", "example": "valid", "enum": [ "missing", "expired", "expiring_soon", "valid" ] }, "insurance_status_label": { "type": "string", "example": "Valid" }, "driver": { "oneOf": [ { "$ref": "#/components/schemas/Driver" } ], "nullable": true, "description": "Present on the vehicle endpoints (dashboard and captain app), where the captain is loaded; absent inside a captain record." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-10 08:36:47" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-12 10:21:59" }, "images": { "description": "Only present when the media collection is loaded.", "properties": { "vehicle_image": { "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/1/%D8%AA%D8%B7%D8%A8%D9%8A%D9%82-%D9%85%D9%84%D8%A7%D8%A8%D8%B3.png", "nullable": true }, "mechanics_image": { "type": "string", "format": "url", "example": "http://localhost/kapitano_logistic/storage/images/10-09-2026/04/2/logo-N.png", "nullable": true } }, "type": "object" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" }, "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": "SYP", "nullable": true }, "payment_method": { "type": "string", "example": "cash_on_delivery", "enum": [ "cash_on_delivery", "prepaid" ] }, "payment_method_label": { "type": "string", "example": "Cash on delivery" }, "quoted_fee": { "description": "The delivery fee the caller asked for, when the pricing ladder overruled it. Null when nobody stated one, or when no rule had an opinion. The ladder DOES overrule a stated fee - a store integration that always sends the same number would otherwise never give anybody free delivery - so this is what keeps the override a record rather than a silent edit.", "type": "number", "format": "float", "example": 18000, "nullable": true }, "fee_priced_by_rule": { "description": "Whether a pricing band decided the fee on this order.", "type": "boolean", "example": true }, "fee_waived": { "description": "Free delivery: a band priced this order at nothing. Carried on every read INCLUDING the list, because a waived delivery would otherwise look identical to a shop that never charged for one.", "type": "boolean", "example": true }, "fee_rule": { "description": "The band that decided it, on the reads that load it. Null on an order priced by whoever sent it, and on one whose band has since been retired - the fee itself is a column, so retiring a band never rewrites what was charged.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "min_goods_value": { "type": "number", "format": "float", "example": 300000 }, "max_goods_value": { "description": "Null means \"and above\".", "type": "number", "format": "float", "example": null, "nullable": true } }, "type": "object", "nullable": true }, "amount_to_collect": { "description": "Cash the captain collects; always null for prepaid. NOT touched by the pricing ladder: it is what the shop told its customer to pay.", "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" }, "payment_status": { "description": "Whether the money actually moved, which the payment *method* cannot say. Null on orders written before this existed - guessing would be worse than admitting we do not know, so a missing value must never be drawn as unpaid.", "type": "string", "example": "unpaid", "nullable": true, "enum": [ "paid", "unpaid", "refunded" ] }, "payment_status_label": { "type": "string", "example": "Unpaid", "nullable": true }, "payment_reference": { "description": "The reference the store gave for the payment, when they sent one.", "type": "string", "example": null, "nullable": true }, "payment_verified_at": { "description": "When a prepaid order was confirmed as paid.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "source": { "description": "Where the order came from. Branch on this and never on `store`: the shop name is absent from the create and assign responses, and keying off it there labels a shop own order as back-office.", "type": "string", "example": "store_api", "nullable": true, "enum": [ "dashboard", "store_api" ] }, "external_order_id": { "description": "The reference the shop knows it by, and the one they will quote at us.", "type": "string", "example": "SO-77120", "nullable": true }, "external_order_number": { "type": "string", "example": "77120", "nullable": true }, "store": { "description": "The shop that sent it, on the reads that load it.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "متجر دمشق" } }, "type": "object", "nullable": true }, "leg": { "description": "Which half of a wrapped delivery this row is, and null for the ordinary order - nearly all of them. Some stores have their goods wrapped before delivery: such an order is TWO rows, a collection leg that gathers the goods from the suppliers and leaves them with the wrapper, and a delivery leg - the store's own order - that takes the finished parcel to the customer. Two rows because the first captain is released the moment they hand the goods over.", "type": "string", "example": null, "nullable": true, "enum": [ "collection", "delivery" ] }, "leg_label": { "type": "string", "example": null, "nullable": true }, "parent_order": { "description": "The customer order a collection leg is fetching goods for. Only ever set on a collection leg, whose own customer_name is the wrapping shop.", "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string", "example": "ORD-100002" }, "status": { "type": "string", "example": "pending" }, "status_label": { "type": "string", "example": "Pending" }, "customer_name": { "type": "string", "example": "Khalid Al Ghamdi" } }, "type": "object", "nullable": true }, "collection_legs": { "description": "The internal orders fetching the goods for this delivery. Present on the reads that load them - the order detail and GET /orders/awaiting-collection.", "type": "array", "items": { "properties": { "uuid": { "type": "string", "format": "uuid" }, "order_number": { "type": "string", "example": "ORD-100002-C" }, "status": { "type": "string", "example": "delivered" }, "status_label": { "type": "string", "example": "Delivered" }, "failed_reason": { "description": "A collection leg that failed blocks its delivery for good - the goods never arrived.", "type": "string", "example": null, "nullable": true } }, "type": "object" } }, "can_be_assigned": { "description": "Whether a captain may be sent for this order yet. A wrapped order's delivery leg sits in plain pending while its goods are still being collected, so its status alone cannot be told apart from an order that could be handed out now. ABSENT is not false: it is derived from collection_legs and is only sent where they are loaded. Treat it as blocking only when it is explicitly false.", "type": "boolean", "example": false }, "assignment_blocked_reason": { "description": "Why not, in the language the reader asked for. Null when nothing is in the way. Assignment answers 409 with the same sentence.", "type": "string", "example": "The goods for this order have not arrived at the wrapping location yet - collection ORD-100002-C is Pending. A captain cannot be sent until they do.", "nullable": true }, "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 }, "pickups": { "description": "Every store the order is collected from, each with what was confirmed there. items_mismatch says an order was short; this says which counter was.", "type": "array", "items": { "$ref": "#/components/schemas/OrderPickup" } }, "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_variance": { "description": "What the whole order came to against what it should have, signed: negative means less was paid than the goods came to. The figure a captain wants at the end of a multi-supplier collection, when the per-stop numbers are three screens back.", "type": "number", "format": "float", "example": -4, "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": { "description": "What the CAPTAIN is expected to pay suppliers. Null on a wrapped delivery leg, which buys nothing because its collection leg already did.", "type": "number", "format": "float", "example": 300, "nullable": true }, "goods_value": { "description": "What the items are worth to the CUSTOMER: quantity x unit_price on this row, whoever paid for them. Present on a wrapped delivery leg where `expected_goods_cost` is null, because the parcel is still what the customer is charged for. Null when no line carries a price.", "type": "number", "format": "float", "example": 75000, "nullable": true }, "delivery_fee": { "description": "The delivery fee. A PART of `customer_total`, not an extra on top of it.", "type": "number", "format": "float", "example": 18000, "nullable": true }, "customer_total": { "description": "What the customer owes for this order, delivery included. `amount_to_collect` when the order states one - a store that sent a total has stated the total - otherwise `goods_value` + `delivery_fee` added up, which is the prepaid case. Null when neither is known: a delivery fee alone is not an order total.", "type": "number", "format": "float", "example": 93000, "nullable": true }, "customer_total_is_computed": { "description": "True when the total above was added up here rather than stated by the order, which happens on a prepaid order that collects nothing. A figure the system worked out and a figure a store stated are not equally trustworthy, and a screen should be able to say which it shows.", "type": "boolean", "example": false }, "total_mismatch": { "description": "The stated total minus its own parts, or null when a part is unknown. Positive means the customer is asked for more than the goods and the delivery come to. NOT an error: a discount, a deposit already paid, or a rounding all live here - but nothing in the system enforces the relationship between the two columns, so a non-zero figure is how an order entered wrongly becomes visible instead of being averaged into a report.", "type": "number", "format": "float", "example": 0, "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 }, "amount_variance": { "type": "number", "format": "float", "example": -4, "nullable": true }, "cash_flow": { "description": "The same money read as the ORDER's cash flow: negative for what went out on goods, positive for what came in from the customer. Each entry's own `amount` below is signed the other way because it answers a different question - what the company owes the captain. A captain who spends their own money at a supplier is owed it, so the same event is +90 there and -90 here. Both are on the page on purpose.", "properties": { "goods_paid": { "description": "What left the company for goods on this order. Negative, or zero when nothing was paid.", "type": "number", "format": "float", "example": -140 }, "cash_collected": { "description": "What came in from the customer. Positive, or zero.", "type": "number", "format": "float", "example": 200 }, "net": { "type": "number", "format": "float", "example": 60 }, "across_legs": { "description": "Only on the delivery leg of a wrapped order. Such an order buys its goods on one row and takes the customer cash on the other, so this row alone reads \"money in, nothing out\" for an order that cost something to fulfil - true of the row, and a lie about the order. This adds the collection legs in. Absent on an ordinary order, where the figures above already are the whole story.", "properties": { "goods_paid": { "type": "number", "format": "float", "example": -140 }, "cash_collected": { "type": "number", "format": "float", "example": 200 }, "net": { "type": "number", "format": "float", "example": 60 } }, "type": "object" } }, "type": "object" }, "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 for the CAPTAIN: positive = the company owes them. A supplier payment is positive here.", "type": "number", "format": "float" }, "order_amount": { "description": "The same figure signed for the ORDER: negative for money out. Null for a desk movement or an adjustment, which have no direction of their own here - reimbursing a captain moves money that was already counted when the goods were bought.", "type": "number", "format": "float", "example": -90, "nullable": true }, "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" }, "OrderPickup": { "description": "A store the order is collected from. An order has at least one and at most three; they are visited in `sequence` order, and all of them before the customer.", "properties": { "uuid": { "description": "Address this store with PATCH /api/driver/orders/{uuid}/pickups/{pickup}/collected.", "type": "string", "format": "uuid", "example": "01a089d1-9dc5-7207-b8ec-928fa322e999" }, "sequence": { "description": "The visiting order chosen for the stops.", "type": "integer", "example": 1, "nullable": true }, "store_name": { "type": "string", "example": "Bait Al Oud", "nullable": true }, "address": { "type": "string", "example": "Baghdad Street, Damascus" }, "lat": { "type": "number", "format": "float", "example": 33.51380000000000336513039655983448028564453125, "nullable": true }, "lng": { "type": "number", "format": "float", "example": 36.27649999999999863575794734060764312744140625, "nullable": true }, "ready_at": { "description": "When the store expects the goods to be ready.", "type": "string", "format": "date-time", "example": null, "nullable": true }, "collected": { "description": "Whether this store has been confirmed.", "type": "boolean", "example": false }, "collected_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "items_collected": { "description": "How many pieces the captain confirmed at this counter. Null when confirmed in one tap.", "type": "integer", "example": 3, "nullable": true }, "items_mismatch": { "description": "Set when the confirmed count differs from what this store was expected to hand over. A store owning no lines expects nothing and is never flagged.", "type": "boolean", "example": false }, "amount_paid": { "description": "What the captain paid at this supplier.", "type": "number", "format": "float", "example": 120, "nullable": true }, "items": { "description": "The lines collected here. Empty on an order whose items were never split by supplier, which is not the same as nothing to collect.", "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "items_expected": { "description": "The quantities of the lines assigned to this store.", "type": "integer", "example": 3 }, "expected_goods_cost": { "description": "What the lines assigned to this counter come to. The number the captain checks their own against before handing cash over - asked for a figure with nothing to compare it to, people type what the till said and never notice when the two disagree. Null when this stop owns no priced lines, and null on a delivery leg, which buys nothing.", "type": "number", "format": "float", "example": 90, "nullable": true }, "amount_variance": { "description": "amount_paid minus expected_goods_cost, signed: negative means the captain paid less than the goods came to. Null when either half is unknown, because a difference from a missing number is not a difference.", "type": "number", "format": "float", "example": -4, "nullable": true }, "order_amount": { "description": "The same payment read as the order's money rather than the captain's: cash left the company here, so it is negative. amount_paid beside it stays the positive number the captain actually typed.", "type": "number", "format": "float", "example": -90, "nullable": true } }, "type": "object" }, "OrderItem": { "description": "A product line inside an order.", "properties": { "uuid": { "description": "A line item inside an order.", "type": "string", "format": "uuid" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number", "format": "float", "nullable": true }, "note": { "type": "string", "nullable": true }, "sku": { "description": "The store product code, as they sent it.", "type": "string", "example": "SHIRT-RED-L", "nullable": true }, "image_url": { "description": "The store own picture of this line. A link we keep, never an address we fetch - so it is loaded by the client and may 404 if the store rotates it.", "type": "string", "format": "uri", "example": "https://cdn.example.sy/shirt-red.jpg", "nullable": true }, "variant": { "description": "What distinguishes this line from another with the same name. Draw it beside the name - a captain confirming two of a shirt cannot otherwise tell the red large from the blue small, and finds out at the customer door.", "type": "object", "example": { "color": "red", "size": "L" }, "nullable": true, "additionalProperties": { "type": "string" } } }, "type": "object" }, "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" ] }, "gps_freshness_label": { "description": "How old the point is, translated for the screen.", "type": "string", "example": "Fresh" }, "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" ] }, "batch_verdict_label": { "description": "The verdict translated for the screen.", "type": "string", "example": "Not applicable" }, "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": "SYP" }, "timezone": { "type": "string", "example": "Asia/Riyadh" }, "wrapping": { "description": "Where this store\\x27s parcels are wrapped, when it uses wrapping. Configured once here rather than sent on each order.", "properties": { "configured": { "description": "All of address, lat and lng are set. An order may only ask to be wrapped when this is true.", "type": "boolean", "example": false }, "name": { "type": "string", "example": "Al Nour Wrapping", "nullable": true }, "address": { "type": "string", "example": "Baghdad Street, Damascus", "nullable": true }, "lat": { "type": "number", "format": "float", "example": 33.51919540000000097279553301632404327392578125, "nullable": true }, "lng": { "type": "number", "format": "float", "example": 36.2877103000000005295078153721988201141357421875, "nullable": true } }, "type": "object" }, "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": "The exact body that was POSTed to the store, kept verbatim so a dispute is settled by\nreading it rather than by reconstructing what we think we sent.\n\n`order` is the full order body, identical to what `GET /api/v1/orders/{uuid}` answers\non the store API and documented there.", "properties": { "event": { "type": "string", "example": "order.delivered" }, "event_id": { "description": "The store's deduplication key.", "type": "string", "format": "uuid" }, "occurred_at": { "description": "Advisory. The store orders by `sequence`, not by this.", "type": "string", "format": "date-time" }, "sequence": { "description": "Monotonic per order. Null on a connection test.", "type": "integer", "nullable": true }, "order": { "description": "The full order body, field for field what `GET /api/v1/orders/{uuid}` answers on the store API — see the **integration** document, which is where the store reads it and where it is kept. It is referenced rather than restated because this specification cannot see that one, and a second copy becomes a second shape the first time either is edited.", "type": "object", "additionalProperties": true } }, "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 — Cities and earnings", "description": "The delivery areas, the flat amount a captain earns for delivering into each, and what that has\ncost.\n\n**Two levels.** A city holds districts; a district holds nothing. Editing a city's rate carries\nthe districts that follow it; a district given a rate of its own keeps it unless the editor asks\nfor it to be overwritten — and editing a district never touches its city.\n\n**The earning is credited at delivery**, from the area the drop-off point falls in, and only for\norders delivered to a customer: the collection leg of a wrapped order carries goods to a shop and\nearns nothing. The figure is copied onto the earning row, so changing a rate never restates what\nhas already been paid.\n\n`cities.view` reads the areas and the report; `cities.manage` changes a rate. They are separate\nbecause a rate is payroll, and the people who need to see which districts are served are not the\npeople who decide what a trip is worth." }, { "name": "Dashboard — Delivery pricing", "description": "Value ladders: ranges of merchandise value, each with what the delivery costs **the store** inside\nit. A band priced at zero is free delivery.\n\n**This prices our invoice, not the customer's receipt.** `orders.fee` is the company's revenue —\n`SUM(fee)` in the stats and `fees_charged` on a store statement — while `orders.amount_to_collect`\nis what the shop told its customer to pay. A ladder never touches the second: lowering it would\nrewrite a figure a customer has already been given, and leave the shop short with no record of why.\nA shop passing free delivery on lowers the amount to collect itself, when it sends the order.\n\n**The ladder overrules a fee the caller stated.** A store integration that always sends 18,000\nwould otherwise never give anybody free delivery. What was asked for survives as `quoted_fee` on\nthe order, so the override is a record rather than a silent edit.\n\n**An order is priced when it is opened and again when a store edits its basket** — an order\ncorrected from 320,000 down to 50,000 must not keep the free delivery it no longer qualifies for.\nAn edit that touches neither the lines nor the fee leaves the price alone.\n\nTwo cases where the ladder stays silent and a stated fee stands: an order whose lines carry no\nprices, and a basket that falls outside every band. Neither is an error — the first means the store\nnever said what the goods are worth, the second that the ladder has a hole in it.\n\n`delivery_fees.view` reads; `delivery_fees.manage` changes what the company charges." }, { "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" } ] }