{ "openapi": "3.1.0", "info": { "title": "Fleximotion Ops API", "version": "1.0.0", "description": "Operational source of truth for operators, vehicles, platform accounts, daily activity, alerts, cash, P&L inputs, and transfer-price events." }, "servers": [ { "url": "https://api.fleximotion.example/ops/v1", "description": "Production placeholder" }, { "url": "http://127.0.0.1:4030/ops/v1", "description": "Local development" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Operators" }, { "name": "Vehicles" }, { "name": "Platform Accounts" }, { "name": "Ingestion" }, { "name": "Daily Activity" }, { "name": "Alerts" }, { "name": "Cash" }, { "name": "Performance" }, { "name": "Fuel and Mileage" }, { "name": "Transfer Pricing" }, { "name": "Audit" }, { "name": "Media" }, { "name": "Incidents" }, { "name": "Inspections" }, { "name": "Maintenance" }, { "name": "Expenses" }, { "name": "P&L" }, { "name": "Leaderboard" }, { "name": "Escalations" }, { "name": "Attendance", "description": "Operator check-in / resumption discipline." } ], "paths": { "/operators": { "get": { "tags": [ "Operators" ], "summary": "List operators", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorPage" } } } } } }, "post": { "tags": [ "Operators" ], "summary": "Create operator", "description": "Creates the operational actor linked to Identity person_id. HR may call this through the onboarding handoff.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOperatorRequest" } } } }, "responses": { "201": { "description": "Operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/activate": { "post": { "tags": [ "Operators" ], "summary": "Activate operator", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Activated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}": { "get": { "tags": [ "Operators" ], "summary": "Get operator", "parameters": [ { "$ref": "#/components/parameters/OperatorId" } ], "responses": { "200": { "description": "Operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } }, "patch": { "tags": [ "Operators" ], "summary": "Update operational assignment or status", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOperatorRequest" } } } }, "responses": { "200": { "description": "Updated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/platform-registrations": { "post": { "tags": [ "Platform Accounts" ], "summary": "Register operator with a platform account", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlatformRegistrationRequest" } } } }, "responses": { "201": { "description": "Registration created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformRegistration" } } } } } } }, "/vehicles": { "get": { "tags": [ "Vehicles" ], "summary": "List vehicles", "responses": { "200": { "description": "Vehicles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiclePage" } } } } } }, "post": { "tags": [ "Vehicles" ], "summary": "Create vehicle", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleRequest" } } } }, "responses": { "201": { "description": "Vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } } } } }, "/vehicles/{vehicle_id}": { "patch": { "tags": [ "Vehicles" ], "summary": "Update vehicle assignment, status, or details", "parameters": [ { "name": "vehicle_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } }, "responses": { "200": { "description": "Updated vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } } } } }, "/platform-accounts": { "get": { "tags": [ "Platform Accounts" ], "summary": "List platform accounts", "responses": { "200": { "description": "Platform accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAccountPage" } } } } } }, "post": { "tags": [ "Platform Accounts" ], "summary": "Create platform connector configuration", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlatformAccountRequest" } } } }, "responses": { "201": { "description": "Platform account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAccount" } } } } } }, "patch": { "tags": [ "Platform Accounts" ], "summary": "Update a ride platform's status or integration mode (activate/retire, switch feed)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Platform account updated" }, "404": { "description": "Platform account not found" } } } }, "/operators/{operator_id}/daily-activity": { "get": { "tags": [ "Daily Activity" ], "summary": "Get operator daily activity", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Daily records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyActivityPage" } } } } } } }, "/ingestion-runs": { "get": { "tags": [ "Ingestion" ], "summary": "List platform ingestion runs", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Ingestion runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionRunPage" } } } } } }, "post": { "tags": [ "Ingestion" ], "summary": "Ingest normalized daily platform records", "description": "Connector boundary for Bolt, Uber, migration, and manual-correction workers. Each record is resolved through the selected platform account and platform_operator_id. Valid records are upserted independently; rejected records are returned in the run errors array.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIngestionRunRequest" } } } }, "responses": { "201": { "description": "Completed ingestion run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionRun" } } } } } } }, "/daily-performance": { "get": { "tags": [ "Daily Activity" ], "summary": "List canonical daily platform performance", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Daily platform records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPerformancePage" } } } } } } }, "/team-board": { "get": { "tags": [ "Performance" ], "summary": "Get the risk-sorted live team board", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Aggregated operator operating picture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamBoardResponse" } } } } } } }, "/pacing": { "get": { "tags": [ "Performance" ], "summary": "Get the resumption-aware pacing board (online target, delivery pacing, combined pace)", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-operator pacing snapshot: scheduled attributed earnings, online target, resumption deadline, delivery behind-schedule flag, and the combined (online + scheduled) pace" } } } }, "/onboarding/ramp-profiles": { "get": { "tags": [ "Onboarding" ], "summary": "List onboarding ramp profiles (rider/driver target curves)", "responses": { "200": { "description": "Ramp profiles" } } }, "post": { "tags": [ "Onboarding" ], "summary": "Create/version a ramp profile (daily targets, parcels-per-hour ramp, completion bonus)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created" } } } }, "/onboarding/ramp-profiles/{rampProfileId}": { "patch": { "tags": [ "Onboarding" ], "summary": "Edit a ramp profile in place", "parameters": [ { "name": "rampProfileId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Updated" } } } }, "/onboarding/cohorts": { "get": { "tags": [ "Onboarding" ], "summary": "List onboarding cohorts (weekly intake batches)", "responses": { "200": { "description": "Cohorts" } } }, "post": { "tags": [ "Onboarding" ], "summary": "Start a cohort (shared Day-1 start date)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created" } } } }, "/onboarding/cohorts/{cohortId}/members": { "post": { "tags": [ "Onboarding" ], "summary": "Add riders to a cohort", "parameters": [ { "name": "cohortId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Assigned" } } } }, "/onboarding/cohort-board": { "get": { "tags": [ "Onboarding" ], "summary": "Cohort monitoring board: per-rider ramp day, target, targets-hit, projected bonus", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Cohort board" } } } }, "/onboarding/operators/{operatorId}": { "get": { "tags": [ "Onboarding" ], "summary": "One rider's onboarding + completion snapshot", "parameters": [ { "name": "operatorId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Onboarding status" } } } }, "/supervisor-onboardings": { "get": { "tags": [ "Onboarding" ], "summary": "List supervisor onboardings (assist assignments)", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Supervisor onboardings" } } }, "post": { "tags": [ "Onboarding" ], "summary": "Start a supervisor onboarding (host amoeba + mentor)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created" } } } }, "/supervisor-onboardings/{onboardingId}/phase": { "post": { "tags": [ "Onboarding" ], "summary": "Advance the assist phase (scheduled -> on-demand)", "parameters": [ { "name": "onboardingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Updated" } } } }, "/supervisor-onboardings/{onboardingId}/graduate": { "post": { "tags": [ "Onboarding" ], "summary": "Graduate the supervisor (explicit HR action; reassign or cell-split)", "parameters": [ { "name": "onboardingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Graduated" } } } }, "/accommodation-units": { "get": { "tags": [ "Onboarding" ], "summary": "List company accommodation units with occupancy and free beds", "responses": { "200": { "description": "Accommodation units" } } }, "post": { "tags": [ "Onboarding" ], "summary": "Create an accommodation unit (finite bed capacity)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created" } } } }, "/accommodation-units/{unitId}": { "patch": { "tags": [ "Onboarding" ], "summary": "Edit a unit (name/location/capacity/status); capacity cannot drop below occupancy", "parameters": [ { "name": "unitId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Onboarding" ], "summary": "Delete a unit (only when empty)", "parameters": [ { "name": "unitId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Deleted" } } } }, "/daily-reports": { "get": { "tags": [ "Daily Activity" ], "summary": "List generated daily report snapshots", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Daily report snapshots" } } }, "post": { "tags": [ "Daily Activity" ], "summary": "Generate an immutable daily report snapshot", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "record_date" ], "properties": { "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Generated report snapshot" } } } }, "/daily-reports/{report_id}": { "get": { "tags": [ "Daily Activity" ], "summary": "Get a generated daily report snapshot", "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Daily report snapshot" } } }, "delete": { "tags": [ "Reporting" ], "summary": "Delete a daily report snapshot", "description": "System admin only. Removes a generated snapshot revision; the deletion is recorded in the audit log with the full report payload.", "operationId": "deleteDailyReport", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; repeated deletes with the same key return the first response." } ], "responses": { "200": { "description": "Report deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "report_id": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing or non-admin credentials" }, "404": { "description": "Report not found" } } } }, "/scheduled-jobs": { "get": { "tags": [ "Audit" ], "summary": "List scheduled job registry health", "responses": { "200": { "description": "Registered jobs with freshness and finality state" } } } }, "/scheduled-job-runs": { "get": { "tags": [ "Audit" ], "summary": "List scheduled job runs", "parameters": [ { "name": "job_name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scheduled job run history" } } } }, "/notification-deliveries": { "get": { "tags": [ "Audit" ], "summary": "List notification outbox delivery attempts", "responses": { "200": { "description": "Notification delivery history for management users" } } } }, "/scheduled-jobs/{job_name}/runs": { "post": { "tags": [ "Audit" ], "summary": "Enqueue a registered scheduled job", "parameters": [ { "name": "job_name", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requested_window_start": { "type": "string", "format": "date-time" }, "requested_window_end": { "type": "string", "format": "date-time" }, "scheduler_trigger_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Queued job run" } } } }, "/scheduled-job-runs/{run_id}/complete": { "post": { "tags": [ "Audit" ], "summary": "Record completion or failure of a scheduled job run", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ] }, "records_received": { "type": "integer" }, "records_upserted": { "type": "integer" }, "records_rejected": { "type": "integer" }, "error_summary": { "type": "string" } } } } } }, "responses": { "200": { "description": "Completed job run" } } } }, "/revenue-pace-profiles": { "get": { "tags": [ "Performance" ], "summary": "List effective-dated revenue pace profiles", "responses": { "200": { "description": "Pace profiles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfilePage" } } } } } }, "post": { "tags": [ "Performance" ], "summary": "Create a vehicle-class revenue pace profile", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRevenuePaceProfileRequest" } } } }, "responses": { "201": { "description": "Pace profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } } } } }, "/revenue-pace-profiles/{profile_id}": { "patch": { "tags": [ "Performance" ], "summary": "Update a revenue pace profile", "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRevenuePaceProfileRequest" } } } }, "responses": { "200": { "description": "Updated pace profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } } } } }, "/economics-policies": { "get": { "tags": [ "Performance" ], "summary": "List finance economics policies used by analytics dashboards", "responses": { "200": { "description": "Economics policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicsPolicyPage" } } } } } }, "post": { "tags": [ "Performance" ], "summary": "Create a finance economics policy for labour, overhead and expected-hour assumptions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEconomicsPolicyRequest" } } } }, "responses": { "201": { "description": "Economics policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EconomicsPolicy" } } } } } } }, "/vehicle-efficiency-policies": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "List fuel and mileage expectation policies", "responses": { "200": { "description": "Efficiency policies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicyPage" } } } } } }, "post": { "tags": [ "Fuel and Mileage" ], "summary": "Create a fuel and mileage expectation policy", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } }, "responses": { "201": { "description": "Efficiency policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } } } } }, "/fuel-issues": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "List supervisor-confirmed fuel issues", "parameters": [ { "name": "operating_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Fuel issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelIssuePage" } } } } } }, "post": { "tags": [ "Fuel and Mileage" ], "summary": "Confirm fuel issued to an operator and vehicle", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFuelIssueRequest" } } } }, "responses": { "201": { "description": "Fuel issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FuelIssue" } } } } } } }, "/mileage-reconciliations": { "get": { "tags": [ "Fuel and Mileage" ], "summary": "Calculate daily fuel-efficiency and tracker mileage exceptions", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Mileage reconciliations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MileageReconciliationPage" } } } } } } }, "/alerts": { "get": { "tags": [ "Alerts" ], "summary": "List alerts", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "resolution_status", "in": "query", "schema": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "snoozed", "escalated" ] } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Alerts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertPage" } } } } } } }, "/alerts/{alert_id}/acknowledge": { "post": { "tags": [ "Alerts" ], "summary": "Acknowledge alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgeAlertRequest" } } } }, "responses": { "200": { "description": "Alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/resolve": { "post": { "tags": [ "Alerts" ], "summary": "Resolve alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAlertRequest" } } } }, "responses": { "200": { "description": "Alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/cash/status": { "get": { "tags": [ "Cash" ], "summary": "Get expected versus remitted cash status", "description": "Finance and manager-facing closeout view. Expected cash is currently derived from platform cash-trip share until exact cash receipts are available from connectors.", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Scoped cash status rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashStatusPage" } } } } } } }, "/cash/adjustments": { "get": { "tags": [ "Cash" ], "summary": "List finance cash adjustments and evidence references", "parameters": [ { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "adjustment_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive adjustment-date range bound; both default to today (Lagos)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive adjustment-date range bound; both default to today (Lagos)." } ], "responses": { "200": { "description": "Scoped cash adjustments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashAdjustmentPage" } } } } } }, "post": { "tags": [ "Cash" ], "summary": "Record a finance cash adjustment or reversal", "description": "Requires service, owner/admin, or an active scoped Finance assignment. Manager-scoped users can review cash status and adjustment history but cannot create adjustments. The API rejects adjustments for accounting periods already closed by Payments.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCashAdjustmentRequest" } } } }, "responses": { "201": { "description": "Cash adjustment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashAdjustment" } } } }, "403": { "description": "Missing Finance authority, or the selected accounting period is locked." } } } }, "/daily-closeouts": { "get": { "tags": [ "Closeouts" ], "summary": "List submitted daily closeouts", "parameters": [ { "name": "record_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive). Defaults to date_to, record_date, or today (Lagos). Ranges are capped at 92 days." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive). Defaults to date_from, record_date, or today (Lagos)." } ], "responses": { "200": { "description": "Scoped closeouts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCloseoutPage" } } } } } }, "post": { "tags": [ "Closeouts" ], "summary": "Submit or update a supervisor daily closeout", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDailyCloseoutRequest" } } } }, "responses": { "201": { "description": "Daily closeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyCloseout" } } } } } } }, "/cash/transactions": { "get": { "tags": [ "Cash" ], "summary": "List Monnify-derived cash transactions", "parameters": [ { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Scoped cash transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashTransactionPage" } } } } } }, "post": { "tags": [ "Cash" ], "summary": "Accept a verified Monnify cash transaction", "description": "Internal service endpoint called by the Payments Integration service after provider verification and account matching.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCashTransactionRequest" } } } }, "responses": { "201": { "description": "Cash transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashTransaction" } } } } } } }, "/operators/{operator_id}/monnify-account": { "patch": { "tags": [ "Cash" ], "summary": "Attach a provisioned Monnify account to an operator", "description": "Internal service endpoint called by the Payments Integration service after reserved-account provisioning.", "parameters": [ { "$ref": "#/components/parameters/OperatorId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "monnify_account_number" ], "properties": { "monnify_account_number": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated operator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } } } }, "/operators/{operator_id}/cash": { "get": { "tags": [ "Cash" ], "summary": "Get an operator cash position", "parameters": [ { "$ref": "#/components/parameters/OperatorId" } ], "responses": { "200": { "description": "Operator cash position" } } } }, "/amoebas/{amoeba_id}/performance": { "get": { "tags": [ "Performance" ], "summary": "Get amoeba performance", "description": "Canonical operational performance snapshot for TMS and management dashboards.", "parameters": [ { "$ref": "#/components/parameters/AmoebaId" }, { "name": "window", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "quarter" ] } }, { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Performance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmoebaPerformance" } } } } } } }, "/transfer-price-events": { "post": { "tags": [ "Transfer Pricing" ], "summary": "Accept transfer-price event from TMS", "description": "Records TMS-created transfer-price events as Ops P&L inputs. This endpoint is idempotent and service-token only.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferPriceEventRequest" } } } }, "responses": { "202": { "description": "Accepted transfer-price event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPriceEvent" } } } } } }, "get": { "tags": [ "Transfer Pricing" ], "summary": "List transfer-price events", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPriceEventPage" } } } } } } }, "/audit": { "get": { "tags": [ "Audit" ], "summary": "List append-only Ops audit entries", "responses": { "200": { "description": "Audit entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEntryPage" } } } } } } }, "/media": { "post": { "tags": [ "Media" ], "summary": "Register a camera capture", "description": "Uploads a base64-encoded camera capture with GPS coordinates and capture timestamp. Capture-time drift beyond the configured tolerance is rejected when MEDIA_STRICT_CAPTURE is enabled.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMediaRequest" } } } }, "responses": { "201": { "description": "Stored media metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFile" } } } } } } }, "/media/{media_id}": { "get": { "tags": [ "Media" ], "summary": "Get media metadata", "parameters": [ { "$ref": "#/components/parameters/MediaId" } ], "responses": { "200": { "description": "Media metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaFile" } } } } } } }, "/media/{media_id}/content": { "get": { "tags": [ "Media" ], "summary": "Download media content", "parameters": [ { "$ref": "#/components/parameters/MediaId" } ], "responses": { "200": { "description": "Binary media content in the stored content type" } } } }, "/deviation-reason-codes": { "get": { "tags": [ "Alerts" ], "summary": "List standardised deviation reason codes", "responses": { "200": { "description": "Array of reason codes" } } } }, "/alerts/{alert_id}/deviation-reason": { "post": { "tags": [ "Alerts" ], "summary": "Submit an operator deviation reason for an alert", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitDeviationReasonRequest" } } } }, "responses": { "200": { "description": "Alert with pending deviation review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/deviation-reason/review": { "post": { "tags": [ "Alerts" ], "summary": "Accept or reject an operator deviation reason", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDeviationReasonRequest" } } } }, "responses": { "200": { "description": "Alert with reviewed deviation reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/alerts/{alert_id}/escalate": { "post": { "tags": [ "Alerts" ], "summary": "Escalate an alert to the manager escalation queue", "parameters": [ { "$ref": "#/components/parameters/AlertId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalateAlertRequest" } } } }, "responses": { "200": { "description": "Escalated alert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } } } } }, "/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List incidents in scope", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ] } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } }, { "name": "incident_type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Incident collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentCollection" } } } } } }, "post": { "tags": [ "Incidents" ], "summary": "Report a field incident", "description": "Accident and police incidents are high severity and enter the manager escalation queue if unacknowledged past the configured window.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncidentRequest" } } } }, "responses": { "201": { "description": "Created incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/incidents/{incident_id}/acknowledge": { "post": { "tags": [ "Incidents" ], "summary": "Acknowledge an incident", "parameters": [ { "$ref": "#/components/parameters/IncidentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Acknowledged incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/incidents/{incident_id}/resolve": { "post": { "tags": [ "Incidents" ], "summary": "Resolve an incident with notes", "parameters": [ { "$ref": "#/components/parameters/IncidentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIncidentRequest" } } } }, "responses": { "200": { "description": "Resolved incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/inspections": { "get": { "tags": [ "Inspections" ], "summary": "List vehicle inspections in scope", "parameters": [ { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "review_status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inspection collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionCollection" } } } } } }, "post": { "tags": [ "Inspections" ], "summary": "Submit a supervisor vehicle inspection", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInspectionRequest" } } } }, "responses": { "201": { "description": "Created inspection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } } } } }, "/inspections/compliance": { "get": { "tags": [ "Inspections" ], "summary": "48-hour inspection compliance summary", "responses": { "200": { "description": "Compliance summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionCompliance" } } } } } } }, "/inspections/{inspection_id}/review": { "post": { "tags": [ "Inspections" ], "summary": "Approve an inspection or request follow-up", "parameters": [ { "$ref": "#/components/parameters/InspectionId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewInspectionRequest" } } } }, "responses": { "200": { "description": "Reviewed inspection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } } } } }, "/maintenance-reports": { "get": { "tags": [ "Maintenance" ], "summary": "List maintenance reports in scope", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] } }, { "name": "vehicle_id", "in": "query", "schema": { "type": "string" } }, { "name": "operator_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Maintenance report collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReportCollection" } } } } } }, "post": { "tags": [ "Maintenance" ], "summary": "Report a vehicle maintenance issue", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMaintenanceReportRequest" } } } }, "responses": { "201": { "description": "Created maintenance report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReport" } } } } } } }, "/maintenance-reports/{maintenance_id}/status": { "post": { "tags": [ "Maintenance" ], "summary": "Move a maintenance report between open, in_repair and resolved", "description": "Resolved reports may carry a cost_ngn which feeds the amoeba P&L as a variable maintenance cost.", "parameters": [ { "$ref": "#/components/parameters/MaintenanceId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMaintenanceStatusRequest" } } } }, "responses": { "200": { "description": "Updated maintenance report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceReport" } } } } } } }, "/expenses": { "get": { "tags": [ "Expenses" ], "summary": "List expenses for a period", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Expense collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpenseCollection" } } } } } }, "post": { "tags": [ "Expenses" ], "summary": "Record a direct amoeba expense or a central cost", "description": "Central expenses (allocation=central, no amoeba_id) are allocated across amoebas by active-operator headcount in the P&L view.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExpenseRequest" } } } }, "responses": { "201": { "description": "Created expense", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } } } } }, "/pnl": { "get": { "tags": [ "P&L" ], "summary": "Amoeba P&L for a period", "description": "Net Earnings minus direct expenses, resolved maintenance costs and headcount-allocated central costs, adjusted by transfer-price credits and charges.", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "P&L summary and per-amoeba rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfitAndLoss" } } } } } } }, "/leaderboard": { "get": { "tags": [ "Leaderboard" ], "summary": "Sortable operator leaderboard with weighted Performance Score", "description": "Performance Score combines acceptance, time online, cash receipt and revenue components using admin-configured weights. Operator-role callers receive the revenue component as null.", "parameters": [ { "name": "period_start", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "period_end", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "amoeba_id", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "score", "net_earnings", "acceptance", "trips", "online", "cash" ] } } ], "responses": { "200": { "description": "Ranked leaderboard entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Leaderboard" } } } } } } }, "/leaderboard-config": { "get": { "tags": [ "Leaderboard" ], "summary": "Get leaderboard weights and visibility", "responses": { "200": { "description": "Leaderboard configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } } } }, "post": { "tags": [ "Leaderboard" ], "summary": "Update leaderboard weights and visibility", "description": "Weights must sum to 1.0.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } }, "responses": { "200": { "description": "Updated configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardConfig" } } } } } } }, "/escalations": { "get": { "tags": [ "Escalations" ], "summary": "Manager escalation queue", "description": "Escalated or tier-2+ alerts, unacknowledged high-severity incidents, overdue vehicle inspections, missing daily closeouts and open maintenance reports for the caller's scope.", "responses": { "200": { "description": "Escalation queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationQueue" } } } } } } }, "/fleet-policy": { "get": { "tags": [ "Fleet" ], "summary": "Read the fleet inspection/service policy", "operationId": "getFleetPolicy", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string" }, "inspection_interval_hours": { "type": "number", "description": "Vehicles must be inspected at least this often (default 48h). Drives compliance and overdue states." }, "service_interval_days": { "type": "number", "description": "Preventive service cadence (default 14 days). Surfaced to fleet views; scheduling arrives with the supervisor S2 slice." }, "updated_by_person_id": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "post": { "tags": [ "Fleet" ], "summary": "Update the fleet inspection/service policy (system admin only; audited)", "operationId": "updateFleetPolicy", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inspection_interval_hours": { "type": "number", "minimum": 1, "maximum": 720 }, "service_interval_days": { "type": "number", "minimum": 1, "maximum": 365 } } } } } }, "responses": { "200": { "description": "Updated policy" }, "400": { "description": "Out-of-range interval" }, "401": { "description": "Not a system admin" } } } }, "/revenue-sources": { "get": { "tags": [ "Deliveries" ], "summary": "List every revenue source (ride platforms + delivery customers) with integration mode and connector state", "description": "Unifies ride platforms and delivery customers. Each row carries kind, status, integration_mode (api|headless|file|manual), a connector block (provider, required_env names, configured) for automated modes, and pricing for delivery customers. Contract price is finance/manager-facing.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-customers": { "get": { "tags": [ "Deliveries" ], "summary": "List prescheduled-delivery customers with contract prices", "description": "Contract prices are finance/manager-facing; operators never see them.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } }, "post": { "tags": [ "Deliveries" ], "summary": "Define a delivery customer", "description": "System admin. Contract price is the per-delivered-package company revenue rate.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-customers/{customer_id}": { "patch": { "tags": [ "Deliveries" ], "summary": "Update a delivery customer", "description": "System admin. Contract price, contact, notes, status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-allocated-prices": { "get": { "tags": [ "Deliveries" ], "summary": "List global allocated-price versions", "description": "Effective-dated; the operator-facing value per delivered package.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } }, "post": { "tags": [ "Deliveries" ], "summary": "Set a new allocated price", "description": "System admin. Drives operator earnings, targets, leaderboard and fee calculations.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-batches": { "get": { "tags": [ "Deliveries" ], "summary": "List delivery batches with derived totals", "description": "Assigned/delivered/failed/returned totals derive from driver assignments; every count carries its source label.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the batch-date range; defaults to today (Lagos)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the batch-date range; defaults to date_from." }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by delivery customer." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "open, in_progress or closed." } ] }, "post": { "tags": [ "Deliveries" ], "summary": "Create a delivery batch", "description": "Supervisor+. Customer, amoeba, date, manifest ref, pre-assignment counts.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-batches/{batch_id}/counts": { "patch": { "tags": [ "Deliveries" ], "summary": "Update batch stage counts", "description": "Supervisor+. Expected/received/sorted with a counts_source label; locked once closed.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-batches/{batch_id}/close": { "post": { "tags": [ "Deliveries" ], "summary": "Close a batch and lock its counts", "description": "Supervisor+.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-batches/{batch_id}/assignments": { "post": { "tags": [ "Deliveries" ], "summary": "Assign a driver a daily target for the batch", "description": "Supervisor+. Upserts per (batch, operator).", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-assignments": { "get": { "tags": [ "Deliveries" ], "summary": "List driver assignments with allocated values", "description": "Operators see their own; supervisors their team; earned/target values priced at the global allocated price.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the batch-date range; defaults to today (Lagos)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the batch-date range; defaults to date_from." }, { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by operator." } ] } }, "/delivery-assignments/{assignment_id}": { "patch": { "tags": [ "Deliveries" ], "summary": "Update driver delivery progress", "description": "Supervisor entry where no customer API exists (spec v0.2 D1); delivered+failed cannot exceed assigned.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "assignment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-batches/{batch_id}/exceptions": { "post": { "tags": [ "Deliveries" ], "summary": "Record a delivery exception", "description": "Category, note, optional camera-only photo media_ids.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-exceptions": { "get": { "tags": [ "Deliveries" ], "summary": "List delivery exceptions", "description": "Scoped; filter by batch or status.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by batch." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "open or resolved." } ] } }, "/delivery-exceptions/{exception_id}/resolve": { "post": { "tags": [ "Deliveries" ], "summary": "Resolve a delivery exception", "description": "Supervisor+.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "exception_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/delivery-summary": { "get": { "tags": [ "Deliveries" ], "summary": "Range rollup for cockpits and manager views", "description": "Batches, packages outstanding, exceptions, allocated vs contract value and margin.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } }, "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive start of the batch-date range; defaults to today (Lagos)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Inclusive end of the batch-date range; defaults to date_from." } ] } }, "/platform-payment-records": { "get": { "tags": [ "Cash" ], "summary": "List platform payment-report totals", "description": "The second cash source (e.g. the Uber Payment Transactions report), recorded per operator/platform/day. Finance/manager visibility.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or non-oversight credentials" } } }, "post": { "tags": [ "Cash" ], "summary": "Record/replace a payment-report total", "description": "Finance only. Upserts per (operator, platform, date). Where present, expected cash becomes the HIGHER of the performance-derived cash earnings and this figure, and the gap is flagged as source variance.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Saved" }, "400": { "description": "Validation failed" }, "401": { "description": "Requires Finance" } } } }, "/performance-cash-records": { "get": { "tags": [ "Cash" ], "summary": "List performance-report cash totals", "description": "Uber performance-report cash figures recorded against a declared covering period (the export itself carries no dates). Finance/manager visibility.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or non-oversight credentials" } } }, "post": { "tags": [ "Cash" ], "summary": "Record/replace a performance-report cash total for a declared period", "description": "Finance only. The caller MUST supply period_start and period_end declaring the dates the imported export covers (max 92 days). Upserts per (operator, platform, period). Within a queried cash-status range that fully contains the period, the performance side of the dual-source comparison becomes the HIGHER of the derived cash-trip share and this figure.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Saved" }, "400": { "description": "Validation failed (missing period, reversed period, or span over 92 days)" }, "401": { "description": "Requires Finance" } } } }, "/delivery-batches/{batch_id}/stops": { "post": { "tags": [ "Deliveries" ], "summary": "Add stops (manifest import or manual; optional per batch)", "description": "Stops carry customer, address, phone, parcel count and sequence. Delivered/failed stop transitions drive the assignment counts.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthorized" } } } }, "/delivery-stops": { "get": { "tags": [ "Deliveries" ], "summary": "List stops (riders see their own)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assignment_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } } } }, "/delivery-stops/{stop_id}/status": { "post": { "tags": [ "Deliveries" ], "summary": "Advance a stop through the delivery workflow", "description": "pending -> en_route -> arrived -> delivered/failed. Riders record their own stops (operator_manual); failed requires a reason from the fixed taxonomy; POD photos/signature attach via media_ids.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "stop_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "409": { "description": "Stop already completed or batch closed" } } } }, "/delivery-assignments/{assignment_id}/confirm": { "post": { "tags": [ "Deliveries" ], "summary": "Supervisor confirms rider-entered figures at closeout", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "assignment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } } ], "responses": { "200": { "description": "Confirmed" }, "401": { "description": "Requires Supervisor" } } } }, "/incidents/{incident_id}": { "patch": { "tags": [ "Incidents" ], "summary": "Set incident ownership, required action, or cost implication", "parameters": [ { "$ref": "#/components/parameters/IncidentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIncidentDetailsRequest" } } } }, "responses": { "200": { "description": "Updated incident", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/tracker/devices": { "get": { "tags": [ "Mileage" ], "summary": "Live tracker device inventory with vehicle mapping status", "description": "Business-oversight roles only. FlexiMOS stores tracker distances daily because the vendor cannot be relied on to serve past days.", "responses": { "200": { "description": "Inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerDeviceInventory" } } } } } } }, "/tracker-daily-records": { "get": { "tags": [ "Mileage" ], "summary": "List stored tracker daily distances", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Records", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrackerDailyRecord" } }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "post": { "tags": [ "Mileage" ], "summary": "Record a tracker daily distance manually (vendor-API-down fallback)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrackerDailyRecordRequest" } } } }, "responses": { "201": { "description": "Stored record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerDailyRecord" } } } } } } }, "/tracker/ingest": { "post": { "tags": [ "Mileage" ], "summary": "Pull today's tracker distances now (same capture the scheduler runs hourly)", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "record_date": { "type": "string", "format": "date", "description": "Defaults to today (Lagos)." } } } } } }, "responses": { "200": { "description": "Capture summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "integer" }, "upserted": { "type": "integer" }, "rejected": { "type": "integer" } } } } } } } } }, "/vehicle-positions": { "get": { "tags": [ "Mileage" ], "summary": "Latest known position per vehicle (map view), scoped to the caller", "description": "Aggregated across every configured tracker connector. Vehicles with no feed are listed separately \u2014 absence of a pin is shown, never hidden.", "responses": { "200": { "description": "Positions and the no-feed list", "content": { "application/json": { "schema": { "type": "object", "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/VehiclePosition" } }, "no_feed": { "type": "array", "items": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "plate": { "type": "string" }, "reason": { "type": "string" } } } } } } } } } } } }, "/vehicles/{vehicle_id}/battery-control": { "post": { "tags": [ "Mileage" ], "summary": "Remote battery power control (Tankvolt) with reason, safety interlock and audit", "description": "command 0 cuts power, 1 restores it. A power-off on a vehicle whose last reading shows movement is refused (409) unless stolen_override is true. Every command is recorded with actor and reason.", "parameters": [ { "name": "vehicle_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "command", "reason" ], "properties": { "command": { "type": "integer", "enum": [ 0, 1 ] }, "reason": { "type": "string" }, "stolen_override": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Recorded control action with the vendor's true result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleControlAction" } } } }, "409": { "description": "Blocked by the moving-vehicle safety interlock" } } } }, "/vehicle-control-actions": { "get": { "tags": [ "Mileage" ], "summary": "Recent remote power commands (audit view)", "responses": { "200": { "description": "Actions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleControlAction" } }, "next_cursor": { "type": "string", "nullable": true } } } } } } } } }, "/integration-status": { "get": { "tags": [ "Status" ], "summary": "Live health of every external integration (trackers, platforms, payments, core)", "description": "Cached ~60s; pass refresh=true to force a fresh probe. Status transitions are persisted so status_since shows how long a provider has been down.", "parameters": [ { "name": "refresh", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Integration health snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "generated_at": { "type": "string" }, "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationStatus" } } } } } } } } } }, "/delivery-courier-aliases": { "get": { "tags": [ "Deliveries" ], "summary": "List courier-name aliases", "description": "Free-text customer courier names mapped to real operators.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } }, "post": { "tags": [ "Deliveries" ], "summary": "Map a courier name to an operator", "description": "Supervisor. Used to resolve delivery imports to the roster.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-imports": { "get": { "tags": [ "Deliveries" ], "summary": "List delivery-export imports", "description": "Capture log of Speedaf exports ingested (manual or scheduled pull).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } }, "post": { "tags": [ "Deliveries" ], "summary": "Ingest a Speedaf delivery-waybill export", "description": "Supervisor. Parsed rows fold onto batches/assignments (counts_source=customer_app_import); unmapped couriers are returned for mapping.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } } }, "/checkins": { "get": { "tags": [ "Attendance" ], "summary": "List operator check-ins", "description": "Scoped to the caller; supervisors see their team, operators their own.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "check_in_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Attendance register: start/end of the check-in date range (inclusive)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Attendance register: start/end of the check-in date range (inclusive)." } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } }, "post": { "tags": [ "Attendance" ], "summary": "File a GPS operator check-in", "description": "Operator self-check-in (pending supervisor confirmation), or a supervisor filing for an operator. Geofenced against amoeba Sites.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } } }, "/checkins/{checkin_id}/decision": { "post": { "tags": [ "Attendance" ], "summary": "Approve or reject a check-in", "description": "Supervisor. Required even when GPS passes (an office-resident could pass from bed).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." }, { "name": "checkin_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Validation failed" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-imports/pull": { "post": { "tags": [ "Deliveries" ], "summary": "Run the headless Speedaf pull now", "description": "System admin. Logs into the Speedaf portal, exports today's waybills and ingests them \u2014 the same job the scheduler runs hourly when configured.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "Client-generated key; replays return the first response." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Not configured / validation failed" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-customers/{customerId}": { "delete": { "tags": [ "Deliveries" ], "summary": "Delete a delivery customer", "description": "System admin. Only when it has no batches or imports; otherwise set it inactive.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } }, { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found" }, "409": { "description": "Has batches/imports" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-allocated-prices/{priceId}": { "delete": { "tags": [ "Deliveries" ], "summary": "Delete an allocated-price version", "description": "System admin. Clears a stale/seed rate; refuses to delete the last remaining price.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } }, { "name": "priceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found" }, "409": { "description": "Only price remaining" }, "401": { "description": "Missing or invalid credentials" } } } }, "/delivery-imports/couriers": { "get": { "tags": [ "Deliveries" ], "summary": "Per-courier summary from raw imported waybills", "description": "Works with zero mappings. Each courier's delivered/attempted counts plus the operator it maps to (if any).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid credentials" } } } }, "/daily-records/overrides": { "get": { "tags": [ "Reporting" ], "summary": "List manual-override history (before-images of corrected daily records)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "operator_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "record_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of the operating-date range (inclusive)." }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of the operating-date range (inclusive)." }, { "name": "amoeba_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Override history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyRecordOverridePage" } } } } } } }, "/daily-performance/by-amoeba": { "get": { "tags": [ "Reporting" ], "summary": "Per-amoeba daily rollup of headline metrics over a range", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Per-amoeba daily totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmoebaDailyRollupPage" } } } } } } }, "/operators/{operator_id}/reset-pin": { "post": { "tags": [ "Operators" ], "summary": "Reset an operator's sign-in PIN (supervisor of their amoeba, or manager/admin)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New PIN (shown once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "operator_id", "pin" ], "properties": { "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "pin": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT or service token" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 160 } }, "OperatorId": { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^operator_" } }, "AlertId": { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^alert_" } }, "AmoebaId": { "name": "amoeba_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^amoeba_" } }, "MediaId": { "name": "media_id", "in": "path", "required": true, "description": "Media file identifier", "schema": { "type": "string" } }, "IncidentId": { "name": "incident_id", "in": "path", "required": true, "description": "Incident identifier", "schema": { "type": "string" } }, "InspectionId": { "name": "inspection_id", "in": "path", "required": true, "description": "Inspection identifier", "schema": { "type": "string" } }, "MaintenanceId": { "name": "maintenance_id", "in": "path", "required": true, "description": "Maintenance report identifier", "schema": { "type": "string" } } }, "schemas": { "Operator": { "type": "object", "required": [ "operator_id", "person_id", "operator_status", "amoeba_id" ], "properties": { "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "operator_status": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "supervisor_person_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] } } }, "CreateOperatorRequest": { "type": "object", "required": [ "person_id", "operator_type", "amoeba_id", "site_id" ], "properties": { "person_id": { "type": "string" }, "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ] }, "supervisor_person_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] }, "legacy_source": { "type": "object" } } }, "UpdateOperatorRequest": { "type": "object", "properties": { "operator_type": { "type": "string", "enum": [ "driver", "rider", "courier" ] }, "operator_status": { "type": "string", "enum": [ "pending_activation", "active", "inactive", "suspended" ] }, "amoeba_id": { "type": "string" }, "site_id": { "type": "string" }, "supervisor_person_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": [ "string", "null" ] }, "daily_revenue_target_ngn": { "type": [ "number", "null" ] } } }, "OperatorPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } } } }, "Vehicle": { "type": "object", "required": [ "vehicle_id", "plate", "vehicle_type", "status" ], "properties": { "vehicle_id": { "type": "string" }, "plate": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "van" ] }, "amoeba_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "in_repair" ] }, "tracker_device_id": { "type": "string", "nullable": true, "description": "Tracker device mapped to this vehicle; auto-mapped by plate when the device name contains it." }, "tracker_provider": { "type": "string", "nullable": true, "description": "Tracker vendor for this vehicle (cartracker, tankvolt)." } } }, "CreateVehicleRequest": { "type": "object", "required": [ "plate", "vehicle_type", "amoeba_id" ], "properties": { "plate": { "type": "string" }, "vehicle_type": { "type": "string" }, "amoeba_id": { "type": "string" } } }, "VehiclePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } } } }, "PlatformAccount": { "type": "object", "required": [ "platform_account_id", "platform", "display_name", "vehicle_type", "account_subtype", "credentials_key", "is_active" ], "properties": { "platform_account_id": { "type": "string" }, "platform": { "type": "string", "enum": [ "bolt", "uber", "indrive", "other" ] }, "display_name": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "any" ] }, "account_subtype": { "type": "string", "enum": [ "ride_hailing", "courier", "general" ] }, "credentials_key": { "type": "string", "description": "Environment/secrets prefix only; credentials are never returned." }, "external_account_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } } }, "CreatePlatformAccountRequest": { "type": "object", "required": [ "platform", "display_name", "vehicle_type", "account_subtype", "credentials_key" ], "properties": { "platform": { "type": "string", "enum": [ "bolt", "uber", "indrive", "other" ] }, "display_name": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "any" ] }, "account_subtype": { "type": "string", "enum": [ "ride_hailing", "courier", "general" ] }, "credentials_key": { "type": "string" }, "external_account_id": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "default": true } } }, "PlatformRegistration": { "type": "object", "required": [ "registration_id", "operator_id", "platform_account_id", "platform_operator_id", "registration_status" ], "properties": { "registration_id": { "type": "string" }, "operator_id": { "type": "string" }, "platform_account_id": { "type": "string" }, "platform_operator_id": { "type": "string" }, "registration_status": { "type": "string", "enum": [ "registered", "active", "inactive", "suspended" ] } } }, "CreatePlatformRegistrationRequest": { "type": "object", "required": [ "platform_account_id", "platform_operator_id" ], "properties": { "platform_account_id": { "type": "string" }, "platform_operator_id": { "type": "string" }, "registration_status": { "type": "string", "enum": [ "registered", "active", "inactive", "suspended" ] } } }, "PlatformAccountPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformAccount" } } } }, "NormalizedDailyRecordInput": { "type": "object", "required": [ "platform_operator_id", "trips_total", "trips_completed", "ride_revenue_ngn", "hours_online" ], "properties": { "platform_operator_id": { "type": "string" }, "trips_total": { "type": "integer", "minimum": 0 }, "trips_completed": { "type": "integer", "minimum": 0 }, "trips_cancelled": { "type": "integer", "minimum": 0 }, "trips_no_response": { "type": "integer", "minimum": 0 }, "trips_rejected": { "type": "integer", "minimum": 0 }, "ride_revenue_ngn": { "type": "number", "minimum": 0 }, "net_earnings_ngn": { "type": "number", "minimum": 0 }, "booking_fees_ngn": { "type": "number", "minimum": 0 }, "cash_trips": { "type": "integer", "minimum": 0 }, "card_trips": { "type": "integer", "minimum": 0 }, "acceptance_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "cancellation_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "completion_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "hours_online": { "type": "number", "minimum": 0 }, "official_distance_km": { "type": [ "number", "null" ], "minimum": 0 }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "current_status": { "type": "string", "enum": [ "online", "offline", "not_seen_today", "checked_out", "unknown" ] }, "data_quality": { "type": "string", "enum": [ "authoritative", "derived", "heuristic", "degraded" ] }, "provenance": { "type": "object" }, "raw_payload": { "type": "object" } } }, "CreateIngestionRunRequest": { "type": "object", "required": [ "platform_account_id", "record_date", "records" ], "properties": { "platform_account_id": { "type": "string" }, "record_date": { "type": "string", "format": "date", "description": "Africa/Lagos business date." }, "source": { "type": "string", "enum": [ "live", "migration", "manual_correction", "connector_test" ], "default": "live" }, "records": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/NormalizedDailyRecordInput" } }, "override": { "type": "boolean", "default": false, "description": "Manual corrections only: overwrite an existing authoritative record. Ignored by automated (live) syncs." }, "override_reason": { "type": "string", "description": "Reason for the correction. Required when override=true targets an authoritative record." } } }, "IngestionRun": { "type": "object", "properties": { "ingestion_run_id": { "type": "string" }, "platform_account_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "completed", "completed_with_errors", "failed" ] }, "records_received": { "type": "integer" }, "records_upserted": { "type": "integer" }, "records_rejected": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object" } } } }, "IngestionRunPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IngestionRun" } } } }, "DailyPerformancePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "TeamBoardResponse": { "type": "object", "required": [ "record_date", "data" ], "properties": { "record_date": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object" } } } }, "RevenueCheckpoint": { "type": "object", "required": [ "time", "expected_pct" ], "properties": { "time": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$" }, "expected_pct": { "type": "number", "minimum": 0, "maximum": 100 } } }, "RevenuePaceProfile": { "type": "object", "required": [ "pace_profile_id", "vehicle_type", "daily_target_ngn", "checkpoints" ], "properties": { "pace_profile_id": { "type": "string" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorbike", "other" ] }, "day_type": { "type": "string" }, "daily_target_ngn": { "type": "number" }, "daily_target_accommodated_ngn": { "type": [ "number", "null" ], "description": "Steady-state daily target for accommodated riders; null = same as daily_target_ngn." }, "checkpoints": { "type": "array", "items": { "$ref": "#/components/schemas/RevenueCheckpoint" } }, "warning_tolerance_pct": { "type": "number" }, "critical_tolerance_pct": { "type": "number" }, "effective_from": { "type": "string", "format": "date" }, "effective_to": { "type": [ "string", "null" ], "format": "date" } } }, "CreateRevenuePaceProfileRequest": { "allOf": [ { "$ref": "#/components/schemas/RevenuePaceProfile" } ], "description": "pace_profile_id is generated by the service." }, "RevenuePaceProfilePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevenuePaceProfile" } } } }, "EconomicsPolicy": { "type": "object", "required": [ "policy_name", "admin_staff_daily_cost_ngn", "operator_labour_share_pct", "daily_overhead_ngn", "expected_hours_per_operator", "effective_from" ], "properties": { "economics_policy_id": { "type": "string" }, "policy_name": { "type": "string" }, "admin_staff_daily_cost_ngn": { "type": "number" }, "operator_labour_share_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "daily_overhead_ngn": { "type": "number" }, "expected_hours_per_operator": { "type": "number" }, "effective_from": { "type": "string", "format": "date" }, "effective_to": { "type": [ "string", "null" ], "format": "date" } } }, "CreateEconomicsPolicyRequest": { "allOf": [ { "$ref": "#/components/schemas/EconomicsPolicy" } ], "description": "economics_policy_id is generated by the service." }, "EconomicsPolicyPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EconomicsPolicy" } } } }, "VehicleEfficiencyPolicy": { "type": "object", "required": [ "vehicle_type", "standard_daily_fuel_quantity", "fuel_unit", "expected_distance_km" ], "properties": { "efficiency_policy_id": { "type": "string" }, "vehicle_type": { "type": "string" }, "make_model": { "type": [ "string", "null" ] }, "fuel_type": { "type": "string" }, "standard_daily_fuel_quantity": { "type": "number" }, "fuel_unit": { "type": "string" }, "expected_distance_km": { "type": "number" }, "allowed_variance_pct": { "type": "number", "default": 10 }, "effective_from": { "type": "string", "format": "date" }, "price_per_unit_ngn": { "type": "number", "nullable": true, "description": "Price per fuel unit (naira per litre or per kWh); feeds fuel cost and cost-per-KM figures." } } }, "VehicleEfficiencyPolicyPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleEfficiencyPolicy" } } } }, "FuelIssue": { "type": "object", "required": [ "fuel_issue_id", "operator_id", "vehicle_id", "operating_date", "quantity", "unit" ], "properties": { "fuel_issue_id": { "type": "string" }, "operator_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "operating_date": { "type": "string", "format": "date" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } }, "CreateFuelIssueRequest": { "type": "object", "required": [ "operator_id", "vehicle_id", "operating_date", "quantity", "unit" ], "properties": { "operator_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "operating_date": { "type": "string", "format": "date" }, "quantity": { "type": "number", "minimum": 0 }, "unit": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } }, "FuelIssuePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FuelIssue" } } } }, "MileageReconciliationPage": { "type": "object", "required": [ "record_date", "data" ], "properties": { "record_date": { "type": "string", "format": "date" }, "data": { "type": "array", "items": { "type": "object", "properties": { "official_distance_status": { "type": "string", "enum": [ "acceptable", "exception", "not_available" ] }, "tracker_variance_status": { "type": "string", "enum": [ "acceptable", "exception", "tracker_unavailable", "no_tracker_data" ] } } } } } }, "DailyActivityPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "Alert": { "type": "object", "required": [ "alert_id", "operator_id", "alert_type", "resolution_status" ], "properties": { "alert_id": { "type": "string" }, "operator_id": { "type": "string" }, "platform": { "type": "string" }, "alert_type": { "type": "string" }, "alert_date": { "type": "string", "format": "date" }, "tier": { "type": "integer" }, "resolution_status": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "snoozed", "escalated" ] }, "metadata": { "type": "object" } } }, "AlertPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } } }, "AcknowledgeAlertRequest": { "type": "object", "properties": { "note": { "type": "string" } } }, "ResolveAlertRequest": { "type": "object", "required": [ "resolution_notes" ], "properties": { "resolution_notes": { "type": "string" } } }, "CreateCashTransactionRequest": { "type": "object", "required": [ "operator_id", "amount_ngn", "transaction_ref", "paid_at", "monnify_account_number" ], "properties": { "operator_id": { "type": "string" }, "amount_ngn": { "type": "number", "exclusiveMinimum": 0 }, "transaction_ref": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time" }, "monnify_account_number": { "type": "string" }, "reconciliation_status": { "type": "string" }, "provider_payload": { "type": [ "object", "null" ] } } }, "CashTransaction": { "type": "object", "properties": { "cash_transaction_id": { "type": "string" }, "operator_id": { "type": "string" }, "amount_ngn": { "type": "number" }, "transaction_ref": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time" }, "monnify_account_number": { "type": "string" }, "reconciliation_status": { "type": "string" } } }, "CashTransactionPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashTransaction" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CashStatus": { "type": "object", "properties": { "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "expected_cash_ngn": { "type": "number" }, "remitted_cash_ngn": { "type": "number" }, "adjustment_ngn": { "type": "number" }, "net_position_ngn": { "type": "number" }, "cash_status": { "type": "string", "enum": [ "balanced", "shortfall", "in_credit", "no_expected_cash" ] }, "expected_cash_basis": { "type": "string" }, "transaction_count": { "type": "integer" }, "latest_paid_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CashStatusPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashStatus" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CreateCashAdjustmentRequest": { "type": "object", "required": [ "operator_id", "adjustment_date", "amount_ngn", "adjustment_type", "reason" ], "properties": { "operator_id": { "type": "string" }, "adjustment_date": { "type": "string", "format": "date" }, "amount_ngn": { "type": "number" }, "adjustment_type": { "type": "string", "enum": [ "credit", "debit", "reversal" ] }, "reason": { "type": "string" }, "related_transaction_ref": { "type": [ "string", "null" ] }, "evidence_reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } } }, "CashAdjustment": { "type": "object", "properties": { "cash_adjustment_id": { "type": "string" }, "operator_id": { "type": "string" }, "adjustment_date": { "type": "string", "format": "date" }, "amount_ngn": { "type": "number" }, "adjustment_type": { "type": "string" }, "reason": { "type": "string" }, "related_transaction_ref": { "type": [ "string", "null" ] }, "evidence_reference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "created_by_person_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CashAdjustmentPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CashAdjustment" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "CreateDailyCloseoutRequest": { "type": "object", "required": [ "record_date", "amoeba_id" ], "properties": { "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "supervisor_person_id": { "type": "string" }, "status": { "type": "string" }, "unresolved_alert_count": { "type": "integer", "minimum": 0 }, "notes": { "type": [ "string", "null" ] } } }, "DailyCloseout": { "type": "object", "properties": { "closeout_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": "string" }, "supervisor_person_id": { "type": "string" }, "status": { "type": "string" }, "unresolved_alert_count": { "type": "integer" }, "cash_summary": { "type": "object" }, "notes": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string", "format": "date-time" } } }, "DailyCloseoutPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyCloseout" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "AmoebaPerformance": { "type": "object", "properties": { "amoeba_id": { "type": "string" }, "window": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "revenue_ngn": { "type": "number" }, "utilisation_pct": { "type": "number" }, "he_ngn_per_hour": { "type": "number" }, "active_operator_count": { "type": "integer" } } }, "CreateTransferPriceEventRequest": { "type": "object", "required": [ "transfer_price_event_id", "date", "provider_amoeba_id", "consumer_amoeba_id", "amount_ngn" ], "properties": { "transfer_price_event_id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "provider_amoeba_id": { "type": "string" }, "consumer_amoeba_id": { "type": "string" }, "amount_ngn": { "type": "number" }, "source_tms_url": { "type": "string" } } }, "TransferPriceEvent": { "type": "object", "properties": { "transfer_price_event_id": { "type": "string" }, "ops_record_id": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted", "posted_to_pnl" ] } } }, "TransferPriceEventPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransferPriceEvent" } } } }, "AuditEntryPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "CreateMediaRequest": { "type": "object", "required": [ "content_type", "content_base64", "captured_at" ], "properties": { "kind": { "type": "string", "description": "What the capture evidences, e.g. incident_evidence, inspection_photo, vehicle_return" }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "video/mp4" ] }, "content_base64": { "type": "string", "description": "Base64-encoded bytes, max 3MB decoded" }, "captured_at": { "type": "string", "format": "date-time" }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] } } }, "MediaFile": { "type": "object", "properties": { "media_id": { "type": "string" }, "kind": { "type": "string" }, "content_type": { "type": "string" }, "byte_size": { "type": "integer" }, "sha256": { "type": "string" }, "captured_at": { "type": "string", "format": "date-time" }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] }, "uploaded_by_person_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SubmitDeviationReasonRequest": { "type": "object", "required": [ "reason_code" ], "properties": { "reason_code": { "type": "string", "enum": [ "network_app_issue", "vehicle_fault", "fuel_charging_problem", "platform_account_blocked", "personal_emergency", "other" ] }, "note": { "type": "string", "maxLength": 140, "description": "Required when reason_code is 'other'" } } }, "ReviewDeviationReasonRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accepted", "rejected" ] }, "note": { "type": "string" } } }, "EscalateAlertRequest": { "type": "object", "properties": { "note": { "type": "string" } } }, "CreateIncidentRequest": { "type": "object", "required": [ "operator_id", "incident_type" ], "properties": { "operator_id": { "type": "string" }, "vehicle_id": { "type": [ "string", "null" ] }, "incident_type": { "type": "string", "enum": [ "accident", "breakdown", "police", "fuel_funds", "low_battery", "other", "driver_misconduct", "customer_complaint", "revenue_anomaly", "fuel_anomaly", "vehicle_damage", "documentation", "safety" ] }, "description": { "type": "string", "maxLength": 500 }, "gps_lat": { "type": [ "number", "null" ] }, "gps_lng": { "type": [ "number", "null" ] }, "media_ids": { "type": "array", "items": { "type": "string" } }, "occurred_at": { "type": "string", "format": "date-time" }, "required_action": { "type": "string", "nullable": true, "maxLength": 300 }, "cost_implication_ngn": { "type": "number", "nullable": true } } }, "Incident": { "type": "object", "properties": { "incident_id": { "type": "string" }, "operator_id": { "type": "string" }, "vehicle_id": { "type": [ "string", "null" ] }, "incident_type": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "normal" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "acknowledged", "resolved" ] }, "media_ids": { "type": "array", "items": { "type": "string" } }, "occurred_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolution_notes": { "type": [ "string", "null" ] }, "owner_person_id": { "type": "string", "nullable": true }, "required_action": { "type": "string", "nullable": true }, "cost_implication_ngn": { "type": "number", "nullable": true } } }, "IncidentCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ResolveIncidentRequest": { "type": "object", "required": [ "resolution_notes" ], "properties": { "resolution_notes": { "type": "string" }, "cost_implication_ngn": { "type": "number", "nullable": true } } }, "CreateInspectionRequest": { "type": "object", "required": [ "vehicle_id", "condition" ], "properties": { "vehicle_id": { "type": "string" }, "odometer_km": { "type": [ "number", "null" ] }, "fuel_level_pct": { "type": [ "number", "null" ] }, "condition": { "type": "string", "enum": [ "ok", "minor_issues", "needs_repair" ] }, "issue_categories": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string", "maxLength": 500 }, "media_ids": { "type": "array", "items": { "type": "string" } } } }, "Inspection": { "type": "object", "properties": { "inspection_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "amoeba_id": { "type": "string" }, "inspected_by_person_id": { "type": "string" }, "odometer_km": { "type": [ "number", "null" ] }, "fuel_level_pct": { "type": [ "number", "null" ] }, "condition": { "type": "string" }, "issue_categories": { "type": "array", "items": { "type": "string" } }, "review_status": { "type": "string", "enum": [ "not_required", "pending", "approved", "follow_up" ] }, "inspected_at": { "type": "string", "format": "date-time" } } }, "InspectionCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inspection" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ReviewInspectionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approved", "follow_up" ] }, "note": { "type": "string" } } }, "InspectionCompliance": { "type": "object", "properties": { "total_active_vehicles": { "type": "integer" }, "current": { "type": "integer" }, "overdue": { "type": "integer" }, "compliance_pct": { "type": [ "number", "null" ] }, "vehicles": { "type": "array", "items": { "type": "object" } } } }, "CreateMaintenanceReportRequest": { "type": "object", "required": [ "vehicle_id", "category" ], "properties": { "vehicle_id": { "type": "string" }, "operator_id": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "tyres", "brakes", "engine", "electrical", "body_damage", "other" ] }, "description": { "type": "string", "maxLength": 200 }, "media_ids": { "type": "array", "items": { "type": "string" } } } }, "MaintenanceReport": { "type": "object", "properties": { "maintenance_id": { "type": "string" }, "operator_id": { "type": [ "string", "null" ] }, "vehicle_id": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] }, "cost_ngn": { "type": [ "number", "string", "null" ] }, "resolution_notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "MaintenanceReportCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceReport" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "UpdateMaintenanceStatusRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "in_repair", "resolved" ] }, "cost_ngn": { "type": [ "number", "null" ] }, "resolution_notes": { "type": "string" } } }, "CreateExpenseRequest": { "type": "object", "required": [ "expense_date", "category", "amount_ngn" ], "properties": { "expense_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": [ "string", "null" ], "description": "Required for direct expenses; omit for central costs" }, "category": { "type": "string", "enum": [ "fuel", "maintenance", "rent", "salaries", "utilities", "overhead", "other" ] }, "description": { "type": "string", "maxLength": 300 }, "amount_ngn": { "type": "number" }, "allocation": { "type": "string", "enum": [ "direct", "central" ] }, "evidence_reference": { "type": [ "string", "null" ] } } }, "Expense": { "type": "object", "properties": { "expense_id": { "type": "string" }, "expense_date": { "type": "string", "format": "date" }, "amoeba_id": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "amount_ngn": { "type": [ "number", "string" ] }, "allocation": { "type": "string" }, "evidence_reference": { "type": [ "string", "null" ] } } }, "ExpenseCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Expense" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "ProfitAndLoss": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "central_expenses_ngn": { "type": "number" }, "allocation_basis": { "type": "string" }, "totals": { "type": "object" }, "amoebas": { "type": "array", "items": { "type": "object", "properties": { "amoeba_id": { "type": "string" }, "net_earnings_ngn": { "type": "number" }, "direct_expenses_ngn": { "type": "number" }, "maintenance_costs_ngn": { "type": "number" }, "incident_costs_ngn": { "type": "number" }, "central_allocation_ngn": { "type": "number" }, "transfer_price_credits_ngn": { "type": "number" }, "transfer_price_charges_ngn": { "type": "number" }, "gross_pnl_ngn": { "type": "number" }, "hourly_pnl_ngn": { "type": [ "number", "null" ] }, "target_attainment_pct": { "type": [ "number", "null" ] } } } } } }, "Leaderboard": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "sort": { "type": "string" }, "weights": { "type": "object" }, "company_wide_visible": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "badge": { "type": [ "string", "null" ], "enum": [ "gold", "silver", "bronze", null ] }, "operator_id": { "type": "string" }, "performance_score": { "type": "number" }, "components": { "type": "object" } } } } } }, "LeaderboardConfig": { "type": "object", "properties": { "acceptance_weight": { "type": [ "number", "string" ] }, "online_weight": { "type": [ "number", "string" ] }, "cash_weight": { "type": [ "number", "string" ] }, "revenue_weight": { "type": [ "number", "string" ] }, "default_timeline": { "type": "string" }, "company_wide_visible": { "type": "boolean" } } }, "EscalationQueue": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "escalated_alerts": { "type": "array", "items": { "type": "object" } }, "high_severity_incidents_unacknowledged": { "type": "array", "items": { "type": "object" } }, "open_incidents": { "type": "array", "items": { "type": "object" } }, "overdue_inspections": { "type": "array", "items": { "type": "object" } }, "missing_closeouts_today": { "type": "array", "items": { "type": "object" } }, "open_maintenance_reports": { "type": "array", "items": { "type": "object" } }, "counts": { "type": "object" } } }, "UpdateIncidentDetailsRequest": { "type": "object", "description": "Any field omitted is left unchanged; pass null to clear.", "properties": { "owner_person_id": { "type": "string", "nullable": true, "description": "Responsible person; defaults to whoever acknowledges the incident." }, "required_action": { "type": "string", "nullable": true, "maxLength": 300 }, "cost_implication_ngn": { "type": "number", "nullable": true } } }, "TrackerDevice": { "type": "object", "properties": { "device_id": { "type": "string" }, "name": { "type": "string" }, "online": { "type": "string", "nullable": true }, "group": { "type": "string", "nullable": true }, "last_seen_at": { "type": "string", "nullable": true }, "vehicle_id": { "type": "string", "nullable": true }, "vehicle_plate": { "type": "string", "nullable": true }, "matched_by": { "type": "string", "nullable": true, "enum": [ "device_id", "plate", null ] } } }, "TrackerDeviceInventory": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "nullable": true }, "device_count": { "type": "integer" }, "mapped_count": { "type": "integer" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/TrackerDevice" } } } }, "TrackerDailyRecord": { "type": "object", "properties": { "tracker_record_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "tracker_account_id": { "type": "string", "nullable": true }, "record_date": { "type": "string", "format": "date" }, "actual_distance_km": { "type": "number" }, "data_quality": { "type": "string" }, "source": { "type": "string", "description": "live:, backfill:, or manual" }, "ingested_at": { "type": "string", "format": "date-time" }, "plate": { "type": "string" }, "vehicle_type": { "type": "string" } } }, "CreateTrackerDailyRecordRequest": { "type": "object", "required": [ "vehicle_id", "record_date", "actual_distance_km" ], "properties": { "vehicle_id": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "actual_distance_km": { "type": "number", "minimum": 0 }, "tracker_account_id": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } }, "VehiclePosition": { "type": "object", "properties": { "vehicle_id": { "type": "string" }, "plate": { "type": "string" }, "vehicle_type": { "type": "string" }, "amoeba_id": { "type": "string" }, "operator_id": { "type": "string", "nullable": true }, "person_id": { "type": "string", "nullable": true }, "provider": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "speed_kmh": { "type": "number", "nullable": true }, "heading": { "type": "number", "nullable": true }, "position_at": { "type": "string", "nullable": true }, "position_age_minutes": { "type": "integer", "nullable": true }, "battery_sn": { "type": "string", "nullable": true }, "battery_state": { "type": "string", "nullable": true }, "movement": { "type": "string", "enum": [ "moving", "idle", "stale" ] }, "controllable": { "type": "boolean" } } }, "VehicleControlAction": { "type": "object", "properties": { "control_action_id": { "type": "string" }, "vehicle_id": { "type": "string" }, "plate": { "type": "string" }, "provider": { "type": "string" }, "command": { "type": "string", "enum": [ "power_off", "power_on" ] }, "reason": { "type": "string" }, "stolen_override": { "type": "boolean" }, "requested_by_person_id": { "type": "string" }, "result_code": { "type": "integer", "nullable": true }, "result_detail": { "type": "string", "nullable": true }, "command_results": { "nullable": true }, "succeeded": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "IntegrationStatus": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "category": { "type": "string", "enum": [ "tracker", "platform", "payments", "core" ] }, "configured": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ok", "degraded", "down", "not_configured" ] }, "detail": { "type": "string" }, "latency_ms": { "type": "integer", "nullable": true }, "last_ok_at": { "type": "string", "nullable": true }, "status_since": { "type": "string", "nullable": true }, "last_checked_at": { "type": "string" } } }, "DailyRecordOverride": { "type": "object", "properties": { "override_id": { "type": "string" }, "daily_record_id": { "type": "string" }, "operator_id": { "type": "string" }, "person_id": { "type": "string" }, "platform_account_id": { "type": "string" }, "platform": { "type": "string" }, "record_date": { "type": "string", "format": "date" }, "prior_row": { "type": "object", "additionalProperties": true, "description": "Full before-image of the overwritten daily record." }, "prior_data_quality": { "type": [ "string", "null" ] }, "new_source": { "type": "string" }, "new_data_quality": { "type": "string" }, "forced": { "type": "boolean", "description": "True when this bypassed the authoritative-overwrite guard." }, "override_reason": { "type": [ "string", "null" ] }, "overridden_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "DailyRecordOverridePage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DailyRecordOverride" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "AmoebaDailyRollup": { "type": "object", "properties": { "amoeba_id": { "type": [ "string", "null" ] }, "record_date": { "type": "string", "format": "date" }, "ride_revenue_ngn": { "type": "number" }, "net_earnings_ngn": { "type": "number" }, "trips_completed": { "type": "number" }, "hours_online": { "type": "number" } } }, "AmoebaDailyRollupPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AmoebaDailyRollup" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }