{ "openapi": "3.0.3", "info": { "title": "Destination Transport API", "version": "1.0.0", "description": "Public, versioned REST API for the **Destination** chauffeur & ground-transport platform. It powers native operator, dispatcher, driver and passenger apps as well as server-to-server integrations: trips, fleet cars, drivers, dispatch & live driver tracking, product bookings, customers, quotes, invoices & payments, business settings and webhooks.\n\n## Authentication\nThree credential types (all sent as `Authorization: Bearer `, except the driver token):\n\n- **businessApiKey** \u2014 a per-business API key (issued in-app under Settings). Scopes every request to that one business; you never pass a business_id.\n- **bearerUserToken** \u2014 a short-lived user access JWT (15 min) obtained from `POST /auth/login` (or `/auth/refresh`). A person may act on any business they can access; select which one with the `X-Business-Id` header (omit it when the account has exactly one business).\n- **driverToken** \u2014 an opaque per-assignment token for the native driver app, sent as the `?token=` query parameter on `/driver/*` routes. It identifies the trip, driver and business in one lookup \u2014 no Authorization header is used.\n\nMost business-scoped endpoints accept **either** a businessApiKey **or** a bearerUserToken.\n\n## Response envelope\nSuccess: `{ \"data\": , \"meta\": { \"request_id\": \"...\", \"pagination\": {...} } }`\n\nError: `{ \"error\": { \"type\": \"...\", \"message\": \"...\", \"details\": [...] }, \"meta\": { \"request_id\": \"...\" } }`\n\n## Pagination\nList endpoints accept `?page` and `?per_page` (max 100) and return a `meta.pagination` block. The trips list uses a fixed server page size of 20.\n\n## Rate limiting\nFixed one-minute window per business (per-IP for the public auth routes). Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; a 429 is returned when exceeded." }, "servers": [ { "url": "https://app.destination.dev/api/v1", "description": "API base. All paths in this document are relative to this URL." }, { "url": "https://app.destination.tools/api/v1", "description": "Production (placeholder host)." } ], "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "tags": [ { "name": "Auth", "description": "Public authentication (login, refresh, register, verify, Google)." }, { "name": "Me", "description": "The authenticated user's own profile, businesses and API keys (user token only)." }, { "name": "Meta", "description": "Auth check and the acting business profile." }, { "name": "Trips", "description": "Chauffeur trips \u2014 the core transport resource (full CRUD)." }, { "name": "Cars", "description": "Fleet vehicles (full CRUD)." }, { "name": "Drivers", "description": "Drivers (full CRUD)." }, { "name": "Bookings", "description": "Product/service bookings and their transitions, notes and participants." }, { "name": "Products", "description": "Booking products / services offered (full CRUD + cover image)." }, { "name": "Customers", "description": "Customer directory (CRUD + trip/booking history)." }, { "name": "Quotes", "description": "Quotes and their lifecycle (trips, pricing, send/accept/reject/convert)." }, { "name": "Invoices", "description": "Invoices (list, create, status, delete, stats, PDF)." }, { "name": "Payments", "description": "Invoice payments and booking payment actions (links, cash, refunds)." }, { "name": "Dispatch", "description": "Dispatch board, fare quoting, driver assignment and live locations." }, { "name": "Driver App", "description": "Native driver-app routes authenticated by an opaque per-assignment driver token." }, { "name": "Settings", "description": "Business profile, integration status and subscription." }, { "name": "Uploads", "description": "Multipart image upload to object storage." }, { "name": "Webhooks", "description": "Per-business webhook subscriptions and delivery log." }, { "name": "Admin", "description": "Platform-wide administration under /admin/* (super-admin user token only, account_type = 'S')." }, { "name": "Public", "description": "Unauthenticated consumer-pay routes under /public/* \u2014 possession of the invoice payment_hash is the capability." }, { "name": "Devices", "description": "Register/list/unregister push-notification devices for the signed-in user (user token only)." } ], "paths": { "/auth/login": { "post": { "tags": [ "Auth" ], "operationId": "authLogin", "security": [], "summary": "Log in with email + password", "description": "Returns an access token (JWT, 15-min TTL), a rotating refresh token (30-day TTL), the user profile and the businesses the account can act on. IP rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "device_name": { "type": "string", "description": "Optional label stored with the session." } }, "required": [ "email", "password" ] }, "example": { "email": "owner@fleet.co", "password": "hunter2xyz", "device_name": "iPhone 15" } } } }, "responses": { "200": { "description": "Authenticated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthLoginResult" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/auth/refresh": { "post": { "tags": [ "Auth" ], "operationId": "authRefresh", "security": [], "summary": "Exchange a refresh token for a new token pair", "description": "Rotates the refresh token. Presenting an already-rotated token is treated as theft and revokes the whole session family.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } }, "required": [ "refresh_token" ] }, "example": { "refresh_token": "rt_ab12..." } } } }, "responses": { "200": { "description": "New token pair.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthTokens" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "authLogout", "security": [], "summary": "Log out (revoke the session family)", "description": "Send a refresh_token in the body, OR a valid user access token as `Authorization: Bearer`. Revokes the whole family.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } } }, "example": { "refresh_token": "rt_ab12..." } } } }, "responses": { "200": { "description": "Logged out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "logged_out": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." } } } }, "/auth/google": { "post": { "tags": [ "Auth" ], "operationId": "authGoogle", "security": [], "summary": "Native Google Sign-In", "description": "Exchange a Google ID token (from native Sign-In) for API tokens. Accepts the web client id and any ids in env `google_mobile_client_ids`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_token": { "type": "string" }, "device_name": { "type": "string" } }, "required": [ "id_token" ] }, "example": { "id_token": "eyJhbGci...", "device_name": "Pixel 8" } } } }, "responses": { "200": { "description": "Authenticated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthGoogleResult" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/auth/register": { "post": { "tags": [ "Auth" ], "operationId": "authRegister", "security": [], "summary": "Register a user + free-tier business", "description": "Creates a user, a free-tier business and links them. Email verification is required before login. IP rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password", "minLength": 8 }, "business_name": { "type": "string" }, "mobile_phone": { "type": "string" }, "website_url": { "type": "string" } }, "required": [ "name", "email", "password", "business_name" ] }, "example": { "name": "Ada Lovelace", "email": "ada@fleet.co", "password": "hunter2xyz", "business_name": "Fleet Co", "mobile_phone": "+15551234567" } } } }, "responses": { "201": { "description": "Account created; verification required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "integer" }, "business_id": { "type": "integer" }, "verification_required": { "type": "boolean", "example": true }, "message": { "type": "string" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict (duplicate resource)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Server error." } } } }, "/auth/password-reset": { "post": { "tags": [ "Auth" ], "operationId": "authPasswordReset", "security": [], "summary": "Request a password-reset email", "description": "Always returns 200 (no account enumeration).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "example": { "email": "ada@fleet.co" } } } }, "responses": { "200": { "description": "Reset email queued (if the account exists).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/auth/verify-email": { "post": { "tags": [ "Auth" ], "operationId": "authVerifyEmail", "security": [], "summary": "Verify an email address", "description": "Consumes the activation code from the emailed link.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": [ "code" ] }, "example": { "code": "a1b2c3..." } } } }, "responses": { "200": { "description": "Email verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verified": { "type": "boolean", "example": true }, "email": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/auth/verify-email/resend": { "post": { "tags": [ "Auth" ], "operationId": "authVerifyEmailResend", "security": [], "summary": "Resend the verification email", "description": "Always returns 200 (no account enumeration).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "example": { "email": "ada@fleet.co" } } } }, "responses": { "200": { "description": "Verification email queued (if unverified).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Rate limit exceeded." } } } }, "/me": { "get": { "tags": [ "Me" ], "operationId": "getMe", "security": [ { "bearerUserToken": [] } ], "summary": "Current user profile", "responses": { "200": { "description": "The authenticated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "patch": { "tags": [ "Me" ], "operationId": "updateMe", "security": [ { "bearerUserToken": [] } ], "summary": "Update the current user's profile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "mobile_phone": { "type": "string" } } }, "example": { "name": "Ada L.", "mobile_phone": "+15550000000" } } } }, "responses": { "200": { "description": "Updated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/me/password": { "post": { "tags": [ "Me" ], "operationId": "changePassword", "security": [ { "bearerUserToken": [] } ], "summary": "Change password", "description": "Revokes every other session on success.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "format": "password" }, "new_password": { "type": "string", "format": "password", "minLength": 8 } }, "required": [ "current_password", "new_password" ] }, "example": { "current_password": "hunter2xyz", "new_password": "newpass9876" } } } }, "responses": { "200": { "description": "Password changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "boolean", "example": true }, "other_sessions_revoked": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/me/businesses": { "get": { "tags": [ "Me" ], "operationId": "listMyBusinesses", "security": [ { "bearerUserToken": [] } ], "summary": "Businesses the user can act on", "description": "Powers the app's business switcher. Use a returned business_id as the `X-Business-Id` header on business-scoped calls.", "responses": { "200": { "description": "Businesses.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSummary" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } } }, "/me/api-keys": { "get": { "tags": [ "Me" ], "operationId": "listApiKeys", "security": [ { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "List the selected business's API keys", "description": "Business scope comes from the `X-Business-Id` header.", "responses": { "200": { "description": "API keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "api_key": { "type": "string" }, "created_date": { "type": "string", "nullable": true }, "last_used_at": { "type": "string", "nullable": true } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Me" ], "operationId": "createApiKey", "security": [ { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create an API key for the selected business", "description": "Returns the new key once.", "responses": { "201": { "description": "Key created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "api_key": { "type": "string" }, "created_date": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Server error." } } }, "delete": { "tags": [ "Me" ], "operationId": "deleteApiKey", "security": [ { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Delete an API key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } }, "required": [ "api_key" ] }, "example": { "api_key": "dk_live_..." } } } }, "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/ping": { "get": { "tags": [ "Meta" ], "operationId": "ping", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Authenticated ping", "description": "Validates the credential and echoes the resolved business.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "business_id": { "type": "integer" }, "api_version": { "type": "string", "example": "v1" }, "time": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } } }, "/business": { "get": { "tags": [ "Meta" ], "operationId": "getBusiness", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "The acting business profile", "responses": { "200": { "description": "Business profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Business" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/trips": { "get": { "tags": [ "Trips" ], "operationId": "listTrips", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "summary": "List trips", "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "upcoming", "previous" ] } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "description": "Fixed server page size of 20.", "responses": { "200": { "description": "Trips.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "post": { "tags": [ "Trips" ], "operationId": "createTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a trip", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trip_date": { "type": "string", "format": "date-time" }, "pickup_address": { "type": "string" }, "dropoff_address": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "trip_type": { "type": "string" }, "car_id": { "type": "integer" }, "pickup_postal_code": { "type": "string" }, "dropoff_postal_code": { "type": "string" }, "pickup_lat": { "type": "number", "format": "float" }, "pickup_lng": { "type": "number", "format": "float" }, "dropoff_lat": { "type": "number", "format": "float" }, "dropoff_lng": { "type": "number", "format": "float" }, "total_amount": { "type": "number", "format": "float" }, "currency": { "type": "string" }, "flight_number": { "type": "string" }, "terminal": { "type": "string" }, "participants_count": { "type": "integer" }, "notes": { "type": "string" }, "special_requirements": { "type": "string" } }, "required": [ "trip_date", "pickup_address", "dropoff_address", "customer_name" ] }, "example": { "trip_date": "2026-08-05 14:30:00", "pickup_address": "Dublin Airport T2", "dropoff_address": "Grafton St, Dublin", "customer_name": "John Doe", "customer_email": "john@x.com", "car_id": 3, "total_amount": 65.0 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/trips/{id}": { "get": { "tags": [ "Trips" ], "operationId": "getTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Get a trip", "responses": { "200": { "description": "Trip.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Trips" ], "operationId": "updateTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Update a trip (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trip" }, "example": { "status": "confirmed", "total_amount": 70.0 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Trip" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Trips" ], "operationId": "deleteTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Delete a trip", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/cars": { "get": { "tags": [ "Cars" ], "operationId": "listCars", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "active_only", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" }, "description": "Set false to include inactive cars." }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List cars", "responses": { "200": { "description": "Cars.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Car" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Cars" ], "operationId": "createCar", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a car", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "max_people": { "type": "integer" }, "manufacturer": { "type": "string" }, "large_bags": { "type": "integer" }, "small_bags": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "initial_cost": { "type": "number", "format": "float" }, "price_per_km": { "type": "number", "format": "float" }, "initial_km_included": { "type": "number", "format": "float" }, "pricing_mode": { "type": "string" }, "weight_order": { "type": "integer" } }, "required": [ "name", "max_people" ] }, "example": { "name": "Mercedes E-Class", "manufacturer": "Mercedes", "max_people": 4, "large_bags": 2, "small_bags": 2, "initial_cost": 15.0, "price_per_km": 1.8 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Car" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/cars/{id}": { "get": { "tags": [ "Cars" ], "operationId": "getCar", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Car id" } ], "summary": "Get a car", "responses": { "200": { "description": "Car.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Car" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Cars" ], "operationId": "updateCar", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Car id" } ], "summary": "Update a car (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Car" }, "example": { "price_per_km": 2.1, "status": "active" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Car" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Cars" ], "operationId": "deleteCar", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Car id" } ], "summary": "Delete a car", "description": "Deactivates instead of deleting when the car is referenced by trips.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/drivers": { "get": { "tags": [ "Drivers" ], "operationId": "listDrivers", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "active_only", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List drivers", "responses": { "200": { "description": "Drivers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Driver" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Drivers" ], "operationId": "createDriver", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a driver", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "format": "email" }, "photo": { "type": "string" }, "status": { "type": "string" }, "hire_date": { "type": "string", "format": "date" }, "weight_order": { "type": "integer" } }, "required": [ "name" ] }, "example": { "name": "Paddy Byrne", "phone": "+353870000000", "email": "paddy@fleet.co" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/drivers/{id}": { "get": { "tags": [ "Drivers" ], "operationId": "getDriver", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Driver id" } ], "summary": "Get a driver", "responses": { "200": { "description": "Driver.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Drivers" ], "operationId": "updateDriver", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Driver id" } ], "summary": "Update a driver (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Driver" }, "example": { "phone": "+353871111111", "status": "active" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Driver" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Drivers" ], "operationId": "deleteDriver", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Driver id" } ], "summary": "Delete a driver", "description": "Deactivates instead of deleting when the driver is referenced by trips.", "responses": { "200": { "description": "Deleted or deactivated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" }, "deactivated": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings": { "get": { "tags": [ "Bookings" ], "operationId": "listBookings", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string", "description": "Customer name/email search." } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List bookings", "responses": { "200": { "description": "Bookings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Bookings" ], "operationId": "createBooking", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a booking", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "booking_date": { "type": "string", "format": "date-time" }, "customer_phone": { "type": "string" }, "duration_minutes": { "type": "integer" }, "participants_count": { "type": "integer" } }, "required": [ "product_id", "customer_name", "customer_email", "booking_date" ] }, "example": { "product_id": 12, "customer_name": "Jane Roe", "customer_email": "jane@x.com", "booking_date": "2026-08-06 10:00:00", "participants_count": 2 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}": { "get": { "tags": [ "Bookings" ], "operationId": "getBooking", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Get a booking", "responses": { "200": { "description": "Booking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Bookings" ], "operationId": "updateBooking", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Update a booking (partial)", "description": "Whitelisted scalar fields; `status` routes through the validated transition.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "booking_date": { "type": "string", "format": "date-time" }, "duration_minutes": { "type": "integer" }, "participants_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "completed", "cancelled", "no_show" ] } } }, "example": { "customer_phone": "+353870000000", "status": "confirmed" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/status": { "post": { "tags": [ "Bookings" ], "operationId": "setBookingStatus", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Change booking status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "confirmed", "completed", "cancelled", "no_show" ] } }, "required": [ "status" ] }, "example": { "status": "completed" } } } }, "responses": { "200": { "description": "Status changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "status": { "type": "string" }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/cancel": { "post": { "tags": [ "Bookings" ], "operationId": "cancelBooking", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Cancel a booking", "description": "Honours the business's cancellation policy window. Fires calendar-delete + notification side-effects.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Customer request" } } } }, "responses": { "200": { "description": "Cancelled booking.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/notes": { "post": { "tags": [ "Bookings" ], "operationId": "setBookingNotes", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Set internal notes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string" } }, "required": [ "notes" ] }, "example": { "notes": "VIP \u2014 greet at kerb." } } } }, "responses": { "200": { "description": "Notes saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "notes": { "type": "string" }, "updated_by": { "type": "integer", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/participants": { "get": { "tags": [ "Bookings" ], "operationId": "listBookingParticipants", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "List participants", "responses": { "200": { "description": "Participants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "post": { "tags": [ "Bookings" ], "operationId": "setBookingParticipants", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Replace the participant list", "description": "The first entry becomes the primary booker.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } }, "required": [ "name" ] } } }, "required": [ "participants" ] }, "example": { "participants": [ { "name": "Jane Roe", "email": "jane@x.com", "phone": "+353870000000" }, { "name": "Guest Two", "email": "", "phone": "" } ] } } } }, "responses": { "201": { "description": "Saved participants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/payment-summary": { "get": { "tags": [ "Payments" ], "operationId": "bookingPaymentSummary", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Booking payment summary", "description": "Invoices, totals and outstanding balance for a booking.", "responses": { "200": { "description": "Summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outstanding": { "type": "number", "format": "float" } }, "additionalProperties": true }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/bookings/{id}/balance-link": { "post": { "tags": [ "Payments" ], "operationId": "bookingBalanceLink", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Create a Stripe payment link for the outstanding balance", "responses": { "201": { "description": "Payment link created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "payment_link_url": { "type": "string", "nullable": true }, "payment_link_id": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream/storage/payment provider failure." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A required service (email, storage, PDF, payments) is unavailable." } } } }, "/bookings/{id}/cash-payment": { "post": { "tags": [ "Payments" ], "operationId": "bookingCashPayment", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Record a cash payment against the balance", "description": "Creates a balance invoice and records the cash payment on it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" } }, "required": [ "amount" ] }, "example": { "amount": 40.0 } } } }, "responses": { "201": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean", "example": true }, "amount": { "type": "number", "format": "float" }, "payment_method": { "type": "string", "example": "cash" }, "invoice_id": { "type": "integer", "nullable": true }, "invoice_number": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/bookings/{id}/refund": { "post": { "tags": [ "Payments" ], "operationId": "bookingRefund", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Booking id" } ], "summary": "Record / process a refund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refund_amount": { "type": "number", "format": "float" }, "refund_status": { "type": "string", "default": "completed" }, "refund_reason": { "type": "string" }, "refund_notes": { "type": "string" }, "refund_stripe_id": { "type": "string" } }, "required": [ "refund_amount" ] }, "example": { "refund_amount": 25.0, "refund_reason": "Late cancellation" } } } }, "responses": { "200": { "description": "Refunded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "refunded": { "type": "boolean", "example": true }, "refund_amount": { "type": "number", "format": "float" }, "refund_status": { "type": "string" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/products": { "get": { "tags": [ "Products" ], "operationId": "listProducts", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List booking products", "responses": { "200": { "description": "Products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Products" ], "operationId": "createProduct", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a booking product", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_name": { "type": "string" }, "description": { "type": "string" }, "price": { "type": "number", "format": "float" }, "deposit_amount": { "type": "number", "format": "float" }, "duration_minutes": { "type": "integer" }, "car_ids": { "type": "array", "items": { "type": "integer" } }, "is_active": { "type": "boolean" } }, "required": [ "product_name" ] }, "example": { "product_name": "Airport Transfer", "price": 55.0, "duration_minutes": 60, "car_ids": [ 3, 4 ], "is_active": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/products/{id}": { "get": { "tags": [ "Products" ], "operationId": "getProduct", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Product id" } ], "summary": "Get a product", "responses": { "200": { "description": "Product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Products" ], "operationId": "updateProduct", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Product id" } ], "summary": "Update a product (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "price": 60.0, "is_active": false } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Products" ], "operationId": "deleteProduct", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Product id" } ], "summary": "Delete a product", "description": "Deactivates instead when the product has bookings.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/products/{id}/image": { "post": { "tags": [ "Products" ], "operationId": "uploadProductImage", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Product id" } ], "summary": "Upload a product cover image", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "integer" }, "cover_photo_url": { "type": "string", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Upstream/storage/payment provider failure." } } } }, "/products/{id}/availability": { "get": { "tags": [ "Dispatch" ], "operationId": "productAvailability", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Product id" }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD; defaults to today." } ], "summary": "Available booking slots for a product on a date", "responses": { "200": { "description": "Slots.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "integer" }, "date": { "type": "string" }, "source": { "type": "string", "enum": [ "product", "business" ] }, "slots": { "type": "array", "items": {} } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List customers", "responses": { "200": { "description": "Customers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Customers" ], "operationId": "createCustomer", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" } }, "required": [ "email" ] }, "example": { "email": "customer@x.com", "name": "Sam Lee", "country": "IE", "city": "Dublin" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict (duplicate resource)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "operationId": "getCustomer", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Customer id" } ], "summary": "Get a customer", "responses": { "200": { "description": "Customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Customers" ], "operationId": "updateCustomer", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Customer id" } ], "summary": "Update a customer (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" } } }, "example": { "phone": "+353870000000", "city": "Cork" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/customers/{id}/trips": { "get": { "tags": [ "Customers" ], "operationId": "customerTrips", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Customer id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "summary": "A customer's trips", "responses": { "200": { "description": "Trips.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/customers/{id}/bookings": { "get": { "tags": [ "Customers" ], "operationId": "customerBookings", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Customer id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "summary": "A customer's bookings", "responses": { "200": { "description": "Bookings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "operationId": "listInvoices", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List invoices", "responses": { "200": { "description": "Invoices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Invoices" ], "operationId": "createInvoice", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a manual invoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "total_amount": { "type": "number", "format": "float" }, "subtotal": { "type": "number", "format": "float" }, "vat_rate": { "type": "number", "format": "float" }, "vat_amount": { "type": "number", "format": "float" }, "amount_paid": { "type": "number", "format": "float" }, "currency": { "type": "string", "default": "USD" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ], "default": "draft" }, "invoice_date": { "type": "string", "format": "date-time" }, "due_date": { "type": "string", "format": "date" }, "customer_vat_number": { "type": "string" }, "customer_country": { "type": "string", "default": "US" }, "vat_reverse_charge": { "type": "boolean" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "format": "float" }, "unit_price": { "type": "number", "format": "float" }, "line_total": { "type": "number", "format": "float" } }, "additionalProperties": true } } }, "required": [ "total_amount" ] }, "example": { "total_amount": 120.0, "currency": "EUR", "status": "open", "line_items": [ { "description": "Airport transfer", "quantity": 1, "unit_price": 120.0, "line_total": 120.0 } ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Plan limit exceeded." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/invoices/stats": { "get": { "tags": [ "Invoices" ], "operationId": "invoiceStats", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "7_days", "30_days", "90_days", "this_year" ], "default": "30_days" } } ], "summary": "Invoice statistics", "responses": { "200": { "description": "Stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": true }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "period": { "type": "string", "example": "30_days" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "operationId": "getInvoice", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Get an invoice (full: header + line items + payments)", "responses": { "200": { "description": "Invoice.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Invoices" ], "operationId": "updateInvoiceStatus", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Update invoice status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] } }, "required": [ "status" ] }, "example": { "status": "paid" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Invoices" ], "operationId": "deleteInvoice", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Delete an invoice", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "invoice_id": { "type": "integer" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/invoices/{id}/payments": { "post": { "tags": [ "Payments" ], "operationId": "recordInvoicePayment", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Record a payment against an invoice", "description": "Rolls the amount into amount_paid and flips the invoice to 'paid' once settled.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "format": "float" }, "payment_method": { "type": "string", "default": "manual" }, "payment_date": { "type": "string", "format": "date-time" }, "stripe_payment_intent_id": { "type": "string" }, "revolut_payment_id": { "type": "string" } }, "required": [ "amount" ] }, "example": { "amount": 120.0, "payment_method": "card" } } } }, "responses": { "200": { "description": "Recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "recorded": { "type": "boolean", "example": true }, "amount": { "type": "number", "format": "float" }, "payment_method": { "type": "string" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Server error." } } } }, "/invoices/{id}/send": { "post": { "tags": [ "Payments" ], "operationId": "sendInvoice", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Email an invoice", "description": "Degrades to `{sent:false}` (200) when email is not configured.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_email": { "type": "string", "format": "email" } } }, "example": { "recipient_email": "customer@x.com" } } } }, "responses": { "200": { "description": "Send result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sent": { "type": "boolean" }, "recipient": { "type": "string", "nullable": true }, "message_id": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/invoices/{id}/pdf": { "get": { "tags": [ "Payments" ], "operationId": "invoicePdf", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "summary": "Generate the invoice PDF (base64)", "responses": { "200": { "description": "PDF payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "invoice_id": { "type": "integer" }, "filename": { "type": "string" }, "content_type": { "type": "string", "example": "application/pdf" }, "encoding": { "type": "string", "example": "base64" }, "data": { "type": "string", "description": "Base64-encoded PDF bytes." } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A required service (email, storage, PDF, payments) is unavailable." } } } }, "/quotes": { "get": { "tags": [ "Quotes" ], "operationId": "listQuotes", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List quotes", "responses": { "200": { "description": "Quotes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Quotes" ], "operationId": "createQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_email": { "type": "string", "format": "email" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "currency": { "type": "string" }, "internal_notes": { "type": "string" }, "customer_notes": { "type": "string" }, "valid_until": { "type": "string", "format": "date" }, "status": { "type": "string" } }, "required": [ "customer_email" ] }, "example": { "customer_email": "customer@x.com", "customer_name": "Sam Lee", "currency": "EUR" } } } }, "responses": { "201": { "description": "Created (incl. trips[]).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}": { "get": { "tags": [ "Quotes" ], "operationId": "getQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Get a quote (full, incl. trips)", "responses": { "200": { "description": "Quote.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Quotes" ], "operationId": "updateQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Update a quote (partial)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string" }, "currency": { "type": "string" }, "internal_notes": { "type": "string" }, "customer_notes": { "type": "string" }, "valid_until": { "type": "string", "format": "date" } } }, "example": { "customer_notes": "Please confirm by Friday." } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Quotes" ], "operationId": "deleteQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Delete a quote", "description": "Only draft/pending_pricing quotes may be deleted.", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}/trips": { "post": { "tags": [ "Quotes" ], "operationId": "addQuoteTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Add a trip (leg) to a quote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickup_address": { "type": "string" }, "dropoff_address": { "type": "string" }, "trip_date": { "type": "string", "format": "date-time" }, "trip_type": { "type": "string" }, "pickup_lat": { "type": "number", "format": "float" }, "pickup_lng": { "type": "number", "format": "float" }, "dropoff_lat": { "type": "number", "format": "float" }, "dropoff_lng": { "type": "number", "format": "float" }, "passenger_count": { "type": "integer" }, "vehicle": { "type": "string" }, "car_id": { "type": "integer" }, "flight_number": { "type": "string" }, "terminal": { "type": "string" }, "special_requirements": { "type": "string" }, "description": { "type": "string" }, "is_return_leg": { "type": "integer" }, "parent_quote_trip_id": { "type": "integer" } }, "required": [ "pickup_address", "dropoff_address" ] }, "example": { "pickup_address": "Dublin Airport T2", "dropoff_address": "Cork City", "trip_date": "2026-08-10 09:00:00", "passenger_count": 3, "car_id": 4 } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteTrip" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}/trips/{trip_id}": { "patch": { "tags": [ "Quotes" ], "operationId": "updateQuoteTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" }, { "name": "trip_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote trip id" } ], "summary": "Update a quote trip", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteTrip" }, "example": { "passenger_count": 4, "terminal": "T1" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QuoteTrip" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Quotes" ], "operationId": "deleteQuoteTrip", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" }, { "name": "trip_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote trip id" } ], "summary": "Remove a trip from a quote", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "quote_id": { "type": "integer" }, "quote_trip_id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}/price": { "post": { "tags": [ "Quotes" ], "operationId": "priceQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Price a quote trip (or recompute totals)", "description": "With `quote_trip_id` + `price`, prices that leg. Without, just recomputes quote totals.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "quote_trip_id": { "type": "integer" }, "price": { "type": "number", "format": "float" } } }, "example": { "quote_trip_id": 88, "price": 140.0 } } } }, "responses": { "200": { "description": "Priced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/Quote" }, "trip": { "$ref": "#/components/schemas/QuoteTrip" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}/send": { "post": { "tags": [ "Quotes" ], "operationId": "sendQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Send a quote", "responses": { "200": { "description": "Done.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "sent" }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } }, "description": "Requires all trips priced." } }, "/quotes/{id}/accept": { "post": { "tags": [ "Quotes" ], "operationId": "acceptQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Accept a quote", "responses": { "200": { "description": "Done.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "accepted" }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/quotes/{id}/reject": { "post": { "tags": [ "Quotes" ], "operationId": "rejectQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Reject a quote", "responses": { "200": { "description": "Done.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "rejected" }, "detail": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Too expensive" } } } } } }, "/quotes/{id}/convert": { "post": { "tags": [ "Quotes" ], "operationId": "convertQuote", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Quote id" } ], "summary": "Convert an accepted quote into trips + an invoice", "responses": { "200": { "description": "Converted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "example": "converted" }, "invoice_id": { "type": "integer" }, "invoice_number": { "type": "string", "nullable": true }, "trip_ids": { "type": "array", "items": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/dispatch/trips": { "get": { "tags": [ "Dispatch" ], "operationId": "dispatchTrips", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "trip_status", "in": "query", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "schema": { "type": "string" } }, { "name": "assignment_status", "in": "query", "schema": { "type": "string", "enum": [ "unassigned", "assigned" ] } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "summary": "The dispatch board", "responses": { "200": { "description": "Dispatch trips.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DispatchTrip" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } } }, "/pricing/fare": { "post": { "tags": [ "Dispatch" ], "operationId": "quoteFare", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Quote a trip fare", "description": "Provide distance_km (+ optional duration_minutes), or pickup/dropoff lat+lng to derive it. Optional car_id switches on per-vehicle pricing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "distance_km": { "type": "number", "format": "float" }, "duration_minutes": { "type": "integer" }, "car_id": { "type": "integer" }, "pickup_lat": { "type": "number", "format": "float" }, "pickup_lng": { "type": "number", "format": "float" }, "dropoff_lat": { "type": "number", "format": "float" }, "dropoff_lng": { "type": "number", "format": "float" } } }, "example": { "distance_km": 12.4, "duration_minutes": 20, "car_id": 5 } } } }, "responses": { "200": { "description": "Fare breakdown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Fare" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/trips/{id}/drivers": { "get": { "tags": [ "Dispatch" ], "operationId": "listTripDrivers", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "List drivers assigned to a trip", "responses": { "200": { "description": "Assigned drivers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TripDriver" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "post": { "tags": [ "Dispatch" ], "operationId": "assignTripDrivers", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Assign drivers to a trip (replaces existing)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driver_ids": { "type": "array", "items": { "type": "integer" } }, "status": { "type": "string", "default": "assigned" } }, "required": [ "driver_ids" ] }, "example": { "driver_ids": [ 7, 9 ], "status": "assigned" } } } }, "responses": { "201": { "description": "Assigned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/TripDriver" } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/trips/{id}/driver-status": { "patch": { "tags": [ "Dispatch" ], "operationId": "updateTripDriverStatus", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Update an assigned driver's status (operator override)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "assigned", "en_route", "completed", "cancelled" ] }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "accuracy": { "type": "number", "format": "float" } }, "required": [ "driver_id", "status" ] }, "example": { "driver_id": 7, "status": "en_route", "lat": 53.35, "lng": -6.26 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "driver_id": { "type": "integer" }, "status": { "type": "string" }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/TripDriver" } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/trips/{id}/location": { "get": { "tags": [ "Dispatch" ], "operationId": "tripLocation", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Trip id" } ], "summary": "Current driver location for a trip", "responses": { "200": { "description": "Location.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DriverLocation" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/drivers/{id}/location": { "post": { "tags": [ "Dispatch" ], "operationId": "pushDriverLocation", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Driver id" } ], "summary": "Operator push of a driver's location for a trip", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "accuracy": { "type": "number", "format": "float" } }, "required": [ "trip_id", "lat", "lng" ] }, "example": { "trip_id": 42, "lat": 53.35, "lng": -6.26, "accuracy": 8.0 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "trip_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/drivers/locations": { "get": { "tags": [ "Dispatch" ], "operationId": "allDriverLocations", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "include_completed", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Include completed trips." } ], "summary": "All live driver locations (map)", "responses": { "200": { "description": "Locations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverLocation" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } } }, "/driver/trip": { "get": { "tags": [ "Driver App" ], "operationId": "driverTrip", "security": [ { "driverToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The opaque per-assignment driver token." } ], "summary": "The driver's current assignment", "responses": { "200": { "description": "Assignment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DriverTask" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." } } } }, "/driver/location": { "post": { "tags": [ "Driver App" ], "operationId": "driverPushLocation", "security": [ { "driverToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Driver token (may instead be sent in the body)." } ], "summary": "Driver pushes live location", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "accuracy": { "type": "number", "format": "float" } }, "required": [ "lat", "lng" ] }, "example": { "token": "9f3c...", "lat": 53.35, "lng": -6.26, "accuracy": 8.0 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "driver_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/driver/status": { "post": { "tags": [ "Driver App" ], "operationId": "driverSetStatus", "security": [ { "driverToken": [] } ], "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "summary": "Driver advances trip status", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "status": { "type": "string", "enum": [ "en_route", "completed", "cancelled" ] }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "accuracy": { "type": "number", "format": "float" } }, "required": [ "status" ] }, "example": { "token": "9f3c...", "status": "en_route", "lat": 53.35, "lng": -6.26 } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "driver_id": { "type": "integer" }, "status": { "type": "string" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/settings/business": { "get": { "tags": [ "Settings" ], "operationId": "getSettingsBusiness", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Read the business profile", "responses": { "200": { "description": "Business settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessSettings" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Settings" ], "operationId": "updateSettingsBusiness", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Update self-serviceable profile fields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_name": { "type": "string" }, "website_url": { "type": "string" }, "business_email": { "type": "string", "format": "email" }, "business_phone": { "type": "string" }, "business_address": { "type": "string" }, "about_me": { "type": "string" }, "currency": { "type": "string" }, "timezone": { "type": "string" }, "date_format": { "type": "string" }, "default_country": { "type": "string" }, "facebook_url": { "type": "string" }, "twitter_url": { "type": "string" }, "instagram_url": { "type": "string" }, "linkedin_url": { "type": "string" }, "youtube_url": { "type": "string" } } }, "example": { "business_phone": "+35316000000", "currency": "EUR", "timezone": "Europe/Dublin" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BusinessSettings" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } } }, "/settings/integrations": { "get": { "tags": [ "Settings" ], "operationId": "getSettingsIntegrations", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Integration connection status", "description": "Derived from the business record's flags. No secrets are returned.", "responses": { "200": { "description": "Integrations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "google_calendar": { "type": "object", "properties": { "connected": { "type": "boolean" }, "calendar_id": { "type": "string", "nullable": true } } }, "stripe": { "type": "object", "properties": { "connected": { "type": "boolean" }, "accept_online_payments": { "type": "boolean" } } }, "revolut": { "type": "object", "properties": { "connected": { "type": "boolean" }, "sandbox_mode": { "type": "boolean" } } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/subscription": { "get": { "tags": [ "Settings" ], "operationId": "getSubscription", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Current subscription plan + usage", "responses": { "200": { "description": "Subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "plan_id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "price": { "type": "number", "format": "float", "nullable": true }, "billing_cycle": { "type": "string", "nullable": true }, "subscription_status": { "type": "string", "nullable": true }, "trial_ends_at": { "type": "string", "nullable": true }, "next_billing_date": { "type": "string", "nullable": true } }, "nullable": true }, "usage": { "type": "object", "properties": {}, "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } } }, "/uploads": { "post": { "tags": [ "Uploads" ], "operationId": "uploadFile", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Upload an image to object storage", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "image": { "type": "string", "format": "binary" }, "folder": { "type": "string", "description": "Optional target folder (alphanumerics/_-)." } } } } } }, "responses": { "201": { "description": "Uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "A required service (email, storage, PDF, payments) is unavailable." } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "summary": "List webhooks", "responses": { "200": { "description": "Webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" } ], "summary": "Create a webhook (returns the signing secret once)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Must be https://" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types (or \"*\" for all)." }, "is_active": { "type": "boolean", "default": true } }, "required": [ "url", "events" ] }, "example": { "url": "https://hooks.fleet.co/destination", "events": [ "trip.completed", "invoice.paid" ], "is_active": true } } } }, "responses": { "201": { "description": "Created (with secret).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Server error." } } } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "webhookDeliveries", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "summary": "Recent delivery attempts", "responses": { "200": { "description": "Deliveries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhook", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "summary": "Get a webhook", "responses": { "200": { "description": "Webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "summary": "Update a webhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Validation failed \u2014 see error.details[]." } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "security": [ { "businessApiKey": [] }, { "bearerUserToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/XBusinessId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook id" } ], "summary": "Delete a webhook", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Missing or invalid credentials." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Authenticated but not permitted (wrong principal type, no business access, or suspended)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Resource not found (or not owned by the acting business)." } } } }, "/admin/businesses": { "get": { "tags": [ "Admin" ], "operationId": "listAdminBusinesses", "security": [ { "bearerUserToken": [] } ], "summary": "List businesses (platform-wide)", "description": "Super-admin only (a user token whose account_type is 'S'). Lists every business on the platform with optional search and pagination. Sensitive columns are stripped. The X-Business-Id header is ignored for admin routes.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match on business_name, business_email or vendor_slug." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminBusiness" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/businesses/{id}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminBusiness", "security": [ { "bearerUserToken": [] } ], "summary": "Get one business", "description": "Super-admin only. Returns the full business row with sensitive columns (payment secrets, integration tokens, md5) stripped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Business id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminBusiness" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "Admin" ], "operationId": "updateAdminBusiness", "security": [ { "bearerUserToken": [] } ], "summary": "Update core business fields", "description": "Super-admin only. Patches a whitelisted set of core fields on any business. Provide at least one editable field. Returns the updated (sanitised) row.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Business id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Any subset of the editable fields.", "properties": { "business_name": { "type": "string" }, "website_url": { "type": "string" }, "business_email": { "type": "string", "format": "email" }, "business_phone": { "type": "string" }, "feedback_email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": [ "A", "D", "P" ] }, "email_credits": { "type": "integer" }, "subscription_plan_id": { "type": "integer" }, "subscription_status": { "type": "string", "enum": [ "active", "inactive", "cancelled", "past_due" ] }, "currency": { "type": "string" }, "timezone": { "type": "string" } } }, "example": { "business_name": "Executive Transfers Ltd", "subscription_status": "active", "email_credits": 1000 } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminBusiness" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/businesses/{id}/usage": { "get": { "tags": [ "Admin" ], "operationId": "getAdminBusinessUsage", "security": [ { "bearerUserToken": [] } ], "summary": "Business plan & usage stats", "description": "Super-admin only. Returns the business's current plan, subscription stats and activity/usage counters.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Business id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "business_id": { "type": "integer", "example": 7 }, "plan": { "type": "object", "nullable": true, "additionalProperties": true }, "subscription": { "type": "object", "additionalProperties": true }, "activity": { "type": "object", "additionalProperties": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/businesses/{id}/credits": { "post": { "tags": [ "Admin" ], "operationId": "addAdminBusinessCredits", "security": [ { "bearerUserToken": [] } ], "summary": "Adjust business credits", "description": "Super-admin only. Adds (or, with a negative value, removes) email/booking credits for a business. Returns the new balance.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Business id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "integer", "description": "Credits to add (negative to deduct)." }, "reason": { "type": "string", "description": "Audit note.", "default": "API admin credit adjustment" } }, "required": [ "credits" ] }, "example": { "credits": 500, "reason": "Goodwill top-up" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "business_id": { "type": "integer", "example": 7 }, "new_balance": { "type": "integer", "example": 1000 }, "credits_added": { "type": "integer", "example": 500 } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/businesses/{id}/suspend": { "post": { "tags": [ "Admin" ], "operationId": "suspendAdminBusiness", "security": [ { "bearerUserToken": [] } ], "summary": "Suspend or reactivate a business", "description": "Super-admin only. Sets a business's status to disabled ('D', action=suspend) or active ('A', action=activate).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Business id" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "suspend", "activate" ], "default": "suspend" } } }, "example": { "action": "suspend" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "business_id": { "type": "integer", "example": 7 }, "status": { "type": "string", "example": "D" }, "action": { "type": "string", "example": "suspend" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/users": { "get": { "tags": [ "Admin" ], "operationId": "listAdminUsers", "security": [ { "bearerUserToken": [] } ], "summary": "List users", "description": "Super-admin only. Lists platform users with optional search and account_type filter. Password hashes are never returned.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match on name or email." }, { "name": "account_type", "in": "query", "schema": { "type": "string", "enum": [ "S", "A" ] }, "description": "Filter by role." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUser" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Admin" ], "operationId": "createAdminUser", "security": [ { "bearerUserToken": [] } ], "summary": "Create a user", "description": "Super-admin only. Creates an admin ('A') or super-admin ('S') user with a pre-verified email. The email must be unique.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "account_type": { "type": "string", "enum": [ "S", "A" ], "default": "A" }, "mobile_phone": { "type": "string" } }, "required": [ "name", "email", "password" ] }, "example": { "name": "New Operator", "email": "operator@example.com", "password": "s3cret-passphrase", "account_type": "A" } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminUser" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "A user with that email already exists (error.type = email_exists).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/users/{id}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminUser", "security": [ { "bearerUserToken": [] } ], "summary": "Get one user", "description": "Super-admin only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminUser" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/users/{id}/password-reset": { "post": { "tags": [ "Admin" ], "operationId": "resetAdminUserPassword", "security": [ { "bearerUserToken": [] } ], "summary": "Set a user's password", "description": "Super-admin only. Directly sets a new password (min 8 chars) for any user.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "format": "password", "minLength": 8 } }, "required": [ "password" ] }, "example": { "password": "a-new-strong-password" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 512 }, "password_updated": { "type": "boolean", "example": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "User not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/users/{id}/business-assignment": { "post": { "tags": [ "Admin" ], "operationId": "assignAdminUserBusiness", "security": [ { "bearerUserToken": [] } ], "summary": "Assign or unassign a user to a business", "description": "Super-admin only. Adds or removes a business_users membership. Idempotent. Returns the user's full current list of business ids.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": "integer" }, "action": { "type": "string", "enum": [ "assign", "unassign" ], "default": "assign" } }, "required": [ "business_id" ] }, "example": { "business_id": 7, "action": "assign" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "integer", "example": 512 }, "action": { "type": "string", "example": "assign" }, "business_id": { "type": "integer", "example": 7 }, "business_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 7, 9 ] } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "User or business not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/plans": { "get": { "tags": [ "Admin" ], "operationId": "listAdminPlans", "security": [ { "bearerUserToken": [] } ], "summary": "List subscription plans", "description": "Super-admin only. Read-only. JSON feature/limit blobs are decoded.", "parameters": [ { "name": "include_inactive", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Set true to include inactive plans." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/plans/{id}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminPlan", "security": [ { "bearerUserToken": [] } ], "summary": "Get one subscription plan", "description": "Super-admin only. Read-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Plan id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Plan not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/settings": { "get": { "tags": [ "Admin" ], "operationId": "getAdminSettings", "security": [ { "bearerUserToken": [] } ], "summary": "Read platform settings", "description": "Super-admin only. Returns all SaaS settings grouped by category, each with its typed value, type and description.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "categories": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": {}, "type": { "type": "string" }, "description": { "type": "string", "nullable": true } } } } } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/settings/{key}": { "patch": { "tags": [ "Admin" ], "operationId": "updateAdminSetting", "security": [ { "bearerUserToken": [] } ], "summary": "Update one platform setting", "description": "Super-admin only. Updates a single setting by key, preserving its existing category and type. Returns the fresh typed value.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Setting key (e.g. platform_name)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "description": "The new value; coerced to the setting's stored type." } }, "required": [ "value" ] }, "example": { "value": "Destination Tools" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string", "example": "platform_name" }, "value": { "description": "Typed value.", "example": "Destination Tools" }, "type": { "type": "string", "example": "string" }, "category": { "type": "string", "example": "general" }, "description": { "type": "string", "nullable": true } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Setting not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/saas-coupons": { "get": { "tags": [ "Admin" ], "operationId": "listAdminSaasCoupons", "security": [ { "bearerUserToken": [] } ], "summary": "List platform discount coupons", "description": "Super-admin only. Read-only.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/saas-coupons/{id}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminSaasCoupon", "security": [ { "bearerUserToken": [] } ], "summary": "Get one platform coupon", "description": "Super-admin only. Read-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Coupon id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Coupon not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/saas-invoices": { "get": { "tags": [ "Admin" ], "operationId": "listAdminSaasInvoices", "security": [ { "bearerUserToken": [] } ], "summary": "List platform subscription invoices", "description": "Super-admin only. Read-only. Backed by the invoices table (business subscription billing). Filter by status and/or business_id.", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "description": "Filter by invoice status." }, { "name": "business_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by business." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/admin/saas-invoices/{id}": { "get": { "tags": [ "Admin" ], "operationId": "getAdminSaasInvoice", "security": [ { "bearerUserToken": [] } ], "summary": "Get one platform invoice", "description": "Super-admin only. Read-only. Includes line_items and payments when those tables are present.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Invoice id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Invoice not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/public/invoices/{hash}": { "get": { "tags": [ "Public" ], "operationId": "getPublicInvoice", "security": [], "summary": "View a public invoice by hash", "description": "UNAUTHENTICATED. Possession of the invoice payment_hash is the capability \u2014 no token, session or CSRF. Returns a sanitised, payer-safe view. Every unknown/settled hash returns a generic 404 (never reveals existence elsewhere). IP rate-limited.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The invoice's payment_hash (a 32-char token)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicInvoice" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Invoice not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded for this IP (see X-RateLimit-* headers).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/public/invoices/{hash}/pay": { "post": { "tags": [ "Public" ], "operationId": "payPublicInvoice", "security": [], "summary": "Create a payment intent for a public invoice", "description": "UNAUTHENTICATED. Creates a Stripe PaymentIntent for the invoice's OUTSTANDING balance against the business's own Stripe key and returns a client_secret for the app to confirm client-side. Does NOT mark the invoice paid \u2014 that happens on the Stripe webhook. Re-GET the invoice to observe the new status. IP rate-limited.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The invoice's payment_hash (a 32-char token)." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicPaymentIntent" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "Invoice not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Already paid (error.type = already_paid) or not in a payable state (invoice_not_payable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded for this IP (see X-RateLimit-* headers).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Upstream payment provider error \u2014 the PaymentIntent could not be created (error.type = payment_provider_error).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Card payment is unavailable for this invoice (Stripe not configured / SDK unavailable; error.type = payment_provider_unavailable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/me/devices": { "get": { "tags": [ "Devices" ], "operationId": "listMyDevices", "security": [ { "bearerUserToken": [] } ], "summary": "List my registered push devices", "description": "User token only. Lists the signed-in user's push-notification devices, most-recently-seen first. Not business-scoped.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Devices" ], "operationId": "registerMyDevice", "security": [ { "bearerUserToken": [] } ], "summary": "Register (or refresh) a push device", "description": "User token only. Idempotent upsert keyed on device_token: re-posting the same token updates its owner/platform/name and bumps last_seen_at. Returns 201 with the stored device.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "ios", "android", "web" ] }, "device_token": { "type": "string", "maxLength": 512, "description": "The opaque push token (APNs/FCM/web-push)." }, "device_name": { "type": "string", "maxLength": 120 } }, "required": [ "platform", "device_token" ] }, "example": { "platform": "ios", "device_token": "fMEp...token", "device_name": "iPhone 16" } } } }, "responses": { "201": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Device" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Devices" ], "operationId": "unregisterMyDevice", "security": [ { "bearerUserToken": [] } ], "summary": "Unregister a push device", "description": "User token only. Removes one of the user's device tokens (stops push to it). Only the owner can remove their token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_token": { "type": "string" } }, "required": [ "device_token" ] }, "example": { "device_token": "fMEp...token" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "removed": { "type": "integer", "example": 1 } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Authenticated but not a super-admin (account_type is not 'S'), or a business API key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation failed \u2014 see error.details[].", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerUserToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A per-user access token (JWT, 15-min TTL) from POST /auth/login or /auth/refresh. Sent as `Authorization: Bearer `. Pair with the X-Business-Id header to select which business to act on." }, "businessApiKey": { "type": "http", "scheme": "bearer", "description": "A per-business API key issued in-app (Settings). Sent as `Authorization: Bearer `. Implicitly scoped to one business \u2014 no X-Business-Id needed. Distinguished from a user token by being a DB-backed opaque key, not a JWT." }, "driverToken": { "type": "apiKey", "in": "query", "name": "token", "description": "An opaque per-assignment token for the native driver app, used only on /driver/* routes. Sent as the `?token=` query parameter (or a `token` body field on POST). Resolves the trip + driver + business in one lookup." } }, "parameters": { "XBusinessId": { "name": "X-Business-Id", "in": "header", "required": false, "schema": { "type": "integer" }, "description": "Selects the acting business for a user access token when the account can access more than one. Ignored for businessApiKey requests (the key already fixes the business). Omit when the account has exactly one business." }, "PageParam": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "1-based page number." }, "PerPageParam": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page (max 100)." } }, "schemas": { "Error": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type (e.g. not_found, invalid_request, unauthorized, forbidden, rate_limited, business_required, plan_limit_exceeded).", "example": "invalid_request" }, "message": { "type": "string", "example": "Missing required field(s): email." }, "details": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Optional per-field validation issues." } }, "required": [ "type", "message" ] }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" }, "meta": { "type": "object", "properties": { "request_id": { "type": "string", "example": "req_9f2c1a" } } } }, "required": [ "error", "meta" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 25 }, "count": { "type": "integer", "example": 25 }, "total": { "type": "integer", "nullable": true, "example": 137 }, "total_pages": { "type": "integer", "nullable": true, "example": 6 }, "has_more": { "type": "boolean", "example": true } } }, "SuccessEnvelope": { "type": "object", "description": "Generic success wrapper. `data` is the resource or array of resources; `meta.pagination` is present on list endpoints.", "properties": { "data": {}, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "data", "meta" ] }, "User": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "mobile_phone": { "type": "string", "nullable": true }, "account_type": { "type": "string", "enum": [ "S", "A", "" ], "description": "S = super admin (all businesses), A = business admin." }, "email_verified": { "type": "boolean" }, "oauth_provider": { "type": "string", "nullable": true } } }, "BusinessSummary": { "type": "object", "properties": { "business_id": { "type": "integer" }, "business_name": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } }, "Business": { "type": "object", "properties": { "business_id": { "type": "integer" }, "business_name": { "type": "string", "nullable": true }, "business_email": { "type": "string", "nullable": true }, "business_phone": { "type": "string", "nullable": true }, "vendor_slug": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "created_date": { "type": "string", "nullable": true } } }, "BusinessSettings": { "type": "object", "properties": { "business_id": { "type": "integer" }, "business_name": { "type": "string", "nullable": true }, "website_url": { "type": "string", "nullable": true }, "business_email": { "type": "string", "nullable": true }, "business_phone": { "type": "string", "nullable": true }, "business_address": { "type": "string", "nullable": true }, "about_me": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "date_format": { "type": "string", "nullable": true }, "default_country": { "type": "string", "nullable": true }, "vendor_slug": { "type": "string", "nullable": true }, "custom_domain": { "type": "string", "nullable": true }, "facebook_url": { "type": "string", "nullable": true }, "twitter_url": { "type": "string", "nullable": true }, "instagram_url": { "type": "string", "nullable": true }, "linkedin_url": { "type": "string", "nullable": true }, "youtube_url": { "type": "string", "nullable": true } } }, "AuthTokens": { "type": "object", "properties": { "token_type": { "type": "string", "example": "Bearer" }, "access_token": { "type": "string", "description": "Short-lived JWT (15 min)." }, "expires_in": { "type": "integer", "example": 900 }, "refresh_token": { "type": "string", "description": "Rotating opaque token (30 days)." } }, "required": [ "token_type", "access_token", "expires_in", "refresh_token" ] }, "AuthLoginResult": { "allOf": [ { "$ref": "#/components/schemas/AuthTokens" }, { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "businesses": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSummary" } } } } ] }, "AuthGoogleResult": { "allOf": [ { "$ref": "#/components/schemas/AuthTokens" }, { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "businesses": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessSummary" } }, "needs_business_setup": { "type": "boolean" } } } ] }, "Trip": { "type": "object", "properties": { "trip_id": { "type": "integer" }, "business_id": { "type": "integer" }, "trip_type": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "payment_status": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "customer_phone": { "type": "string", "nullable": true }, "trip_date": { "type": "string", "description": "Unix timestamp on read; MySQL datetime on write.", "nullable": true }, "duration_minutes": { "type": "integer", "nullable": true }, "pickup_address": { "type": "string", "nullable": true }, "pickup_postal_code": { "type": "string", "nullable": true }, "pickup_lat": { "type": "number", "format": "float", "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "nullable": true }, "dropoff_address": { "type": "string", "nullable": true }, "dropoff_postal_code": { "type": "string", "nullable": true }, "dropoff_lat": { "type": "number", "format": "float", "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "nullable": true }, "trip_distance": { "type": "number", "format": "float", "nullable": true }, "trip_duration": { "type": "integer", "nullable": true }, "vehicle": { "type": "string", "nullable": true }, "car_id": { "type": "integer", "nullable": true }, "participants_count": { "type": "integer", "nullable": true }, "total_amount": { "type": "number", "format": "float", "nullable": true }, "cost": { "type": "number", "format": "float", "nullable": true }, "fees": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true }, "flight_number": { "type": "string", "nullable": true }, "terminal": { "type": "string", "nullable": true }, "is_return_trip": { "type": "integer", "nullable": true }, "parent_trip_id": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true }, "special_requirements": { "type": "string", "nullable": true }, "attendance_code": { "type": "string", "nullable": true }, "created_date": { "type": "string", "nullable": true } } }, "DispatchTrip": { "allOf": [ { "$ref": "#/components/schemas/Trip" }, { "type": "object", "properties": { "assigned_driver_id": { "type": "integer", "nullable": true }, "driver_status": { "type": "string", "nullable": true }, "car_name": { "type": "string", "nullable": true }, "car_manufacturer": { "type": "string", "nullable": true } } } ] }, "Car": { "type": "object", "properties": { "car_id": { "type": "integer" }, "business_id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "manufacturer": { "type": "string", "nullable": true }, "max_people": { "type": "integer", "nullable": true }, "large_bags": { "type": "integer", "nullable": true }, "small_bags": { "type": "integer", "nullable": true }, "image": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ], "nullable": true }, "weight_order": { "type": "integer", "nullable": true }, "initial_cost": { "type": "number", "format": "float", "nullable": true }, "price_per_km": { "type": "number", "format": "float", "nullable": true }, "initial_km_included": { "type": "number", "format": "float", "nullable": true }, "pricing_mode": { "type": "string", "nullable": true }, "tier1_max_km": { "type": "number", "format": "float", "nullable": true }, "tier1_price_per_km": { "type": "number", "format": "float", "nullable": true }, "tier2_max_km": { "type": "number", "format": "float", "nullable": true }, "tier2_price_per_km": { "type": "number", "format": "float", "nullable": true }, "tier3_price_per_km": { "type": "number", "format": "float", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true } } }, "Driver": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "business_id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "photo": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "hire_date": { "type": "string", "nullable": true }, "weight_order": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true } } }, "TripDriver": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "business_id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "photo": { "type": "string", "nullable": true }, "driver_status": { "type": "string", "nullable": true }, "driver_assigned_date": { "type": "string", "nullable": true }, "started_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "actual_duration_minutes": { "type": "integer", "nullable": true }, "driver_token": { "type": "string", "nullable": true }, "location_lat": { "type": "number", "format": "float", "nullable": true }, "location_lng": { "type": "number", "format": "float", "nullable": true }, "location_timestamp": { "type": "string", "nullable": true }, "location_accuracy": { "type": "number", "format": "float", "nullable": true } } }, "DriverLocation": { "type": "object", "properties": { "driver_id": { "type": "integer" }, "driver_name": { "type": "string", "nullable": true }, "driver_phone": { "type": "string", "nullable": true }, "driver_photo": { "type": "string", "nullable": true }, "trip_id": { "type": "integer", "nullable": true }, "trip_status": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "location_lat": { "type": "number", "format": "float", "nullable": true }, "location_lng": { "type": "number", "format": "float", "nullable": true }, "location_timestamp": { "type": "string", "nullable": true }, "location_accuracy": { "type": "number", "format": "float", "nullable": true }, "start_location_lat": { "type": "number", "format": "float", "nullable": true }, "start_location_lng": { "type": "number", "format": "float", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "pickup_address": { "type": "string", "nullable": true }, "pickup_lat": { "type": "number", "format": "float", "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "nullable": true }, "dropoff_address": { "type": "string", "nullable": true }, "dropoff_lat": { "type": "number", "format": "float", "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "nullable": true }, "trip_date": { "type": "string", "nullable": true }, "car_name": { "type": "string", "nullable": true }, "car_manufacturer": { "type": "string", "nullable": true } } }, "DriverTask": { "type": "object", "properties": { "trip_driver_id": { "type": "integer" }, "trip_id": { "type": "integer" }, "driver_id": { "type": "integer" }, "business_id": { "type": "integer" }, "driver_status": { "type": "string", "nullable": true }, "assigned_date": { "type": "string", "nullable": true }, "started_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true }, "driver_name": { "type": "string", "nullable": true }, "driver_phone": { "type": "string", "nullable": true }, "driver_email": { "type": "string", "nullable": true }, "driver_photo": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "customer_phone": { "type": "string", "nullable": true }, "pickup_address": { "type": "string", "nullable": true }, "pickup_lat": { "type": "number", "format": "float", "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "nullable": true }, "dropoff_address": { "type": "string", "nullable": true }, "dropoff_lat": { "type": "number", "format": "float", "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "nullable": true }, "trip_date": { "type": "string", "nullable": true }, "trip_duration": { "type": "integer", "nullable": true }, "trip_distance": { "type": "number", "format": "float", "nullable": true }, "trip_notes": { "type": "string", "nullable": true }, "trip_status": { "type": "string", "nullable": true }, "car_name": { "type": "string", "nullable": true }, "car_manufacturer": { "type": "string", "nullable": true }, "business_name": { "type": "string", "nullable": true }, "logo_url": { "type": "string", "nullable": true }, "location_lat": { "type": "number", "format": "float", "nullable": true }, "location_lng": { "type": "number", "format": "float", "nullable": true }, "location_timestamp": { "type": "string", "nullable": true }, "driver_token": { "type": "string", "nullable": true } } }, "Fare": { "type": "object", "properties": { "currency": { "type": "string" }, "distance_km": { "type": "number", "format": "float", "nullable": true }, "duration_minutes": { "type": "integer", "nullable": true }, "car_id": { "type": "integer", "nullable": true }, "base_fare": { "type": "number", "format": "float", "nullable": true }, "distance_fare": { "type": "number", "format": "float", "nullable": true }, "time_fare": { "type": "number", "format": "float", "nullable": true }, "total_fare": { "type": "number", "format": "float", "nullable": true }, "rounded_total": { "type": "number", "format": "float", "nullable": true }, "using_vehicle_pricing": { "type": "boolean" }, "using_tiered_pricing": { "type": "boolean" } } }, "Booking": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "business_id": { "type": "integer" }, "product_id": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "confirmed", "completed", "cancelled", "no_show" ], "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "customer_phone": { "type": "string", "nullable": true }, "booking_date": { "type": "string", "nullable": true }, "duration_minutes": { "type": "integer", "nullable": true }, "participants_count": { "type": "integer", "nullable": true }, "total_amount": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true } }, "additionalProperties": true, "description": "The raw booking record (fields beyond those listed may be present)." }, "Participant": { "type": "object", "properties": { "participant_id": { "type": "integer" }, "booking_id": { "type": "integer" }, "participant_name": { "type": "string", "nullable": true }, "participant_email": { "type": "string", "nullable": true }, "participant_phone": { "type": "string", "nullable": true }, "is_primary": { "type": "boolean" } } }, "Product": { "type": "object", "properties": { "product_id": { "type": "integer" }, "business_id": { "type": "integer" }, "product_name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "price": { "type": "number", "format": "float", "nullable": true }, "deposit_amount": { "type": "number", "format": "float", "nullable": true }, "duration_minutes": { "type": "integer", "nullable": true }, "car_ids": { "type": "string", "description": "Comma-separated car ids.", "nullable": true }, "car_id": { "type": "integer", "nullable": true }, "car_name": { "type": "string", "nullable": true }, "car_image": { "type": "string", "nullable": true }, "is_active": { "type": "integer", "nullable": true }, "form_slug": { "type": "string", "nullable": true }, "cover_photo_url": { "type": "string", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true } } }, "Customer": { "type": "object", "properties": { "customer_id": { "type": "integer" }, "business_id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "total_bookings": { "type": "integer", "nullable": true }, "total_spent": { "type": "number", "format": "float", "nullable": true }, "first_booking_date": { "type": "string", "nullable": true }, "last_booking_date": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true } } }, "Invoice": { "type": "object", "properties": { "invoice_id": { "type": "integer" }, "business_id": { "type": "integer" }, "invoice_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ], "nullable": true }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "vat_rate": { "type": "number", "format": "float", "nullable": true }, "vat_amount": { "type": "number", "format": "float", "nullable": true }, "total_amount": { "type": "number", "format": "float", "nullable": true }, "amount_paid": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "invoice_date": { "type": "string", "nullable": true }, "due_date": { "type": "string", "nullable": true }, "booking_id": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "line_items": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Present on the full (single-invoice) representation." }, "payments": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true }, "description": "Present on the full (single-invoice) representation." } }, "additionalProperties": true }, "QuoteTrip": { "type": "object", "properties": { "quote_trip_id": { "type": "integer" }, "quote_id": { "type": "integer" }, "trip_date": { "type": "string", "nullable": true }, "trip_type": { "type": "string", "nullable": true }, "pickup_address": { "type": "string", "nullable": true }, "pickup_lat": { "type": "number", "format": "float", "nullable": true }, "pickup_lng": { "type": "number", "format": "float", "nullable": true }, "dropoff_address": { "type": "string", "nullable": true }, "dropoff_lat": { "type": "number", "format": "float", "nullable": true }, "dropoff_lng": { "type": "number", "format": "float", "nullable": true }, "is_return_leg": { "type": "integer", "nullable": true }, "parent_quote_trip_id": { "type": "integer", "nullable": true }, "passenger_count": { "type": "integer", "nullable": true }, "vehicle": { "type": "string", "nullable": true }, "car_id": { "type": "integer", "nullable": true }, "car_name": { "type": "string", "nullable": true }, "flight_number": { "type": "string", "nullable": true }, "terminal": { "type": "string", "nullable": true }, "special_requirements": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "unit_price": { "type": "number", "format": "float", "nullable": true }, "is_priced": { "type": "integer", "nullable": true }, "priced_at": { "type": "string", "nullable": true }, "trip_id": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true } } }, "Quote": { "type": "object", "properties": { "quote_id": { "type": "integer" }, "business_id": { "type": "integer" }, "quote_number": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "customer_phone": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "subtotal": { "type": "number", "format": "float", "nullable": true }, "vat_rate": { "type": "number", "format": "float", "nullable": true }, "vat_amount": { "type": "number", "format": "float", "nullable": true }, "total_amount": { "type": "number", "format": "float", "nullable": true }, "internal_notes": { "type": "string", "nullable": true }, "customer_notes": { "type": "string", "nullable": true }, "valid_until": { "type": "string", "nullable": true }, "payment_hash": { "type": "string", "nullable": true }, "invoice_id": { "type": "integer", "nullable": true }, "accepted_at": { "type": "string", "nullable": true }, "rejected_at": { "type": "string", "nullable": true }, "converted_at": { "type": "string", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "updated_date": { "type": "string", "nullable": true }, "is_fully_priced": { "type": "boolean" }, "trips": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteTrip" } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "nullable": true } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The HMAC signing secret \u2014 shown only once on creation.", "nullable": true } } } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "webhook_id": { "type": "integer" }, "event": { "type": "string", "nullable": true }, "response_code": { "type": "integer", "nullable": true }, "success": { "type": "boolean" }, "delivered_at": { "type": "string", "nullable": true } } }, "AdminBusiness": { "type": "object", "description": "A business as seen by a super-admin. Sensitive columns (payment secrets, integration tokens, the md5 hash) are always stripped. The list view returns the summary columns below; GET /admin/businesses/{id} returns the full sanitised row.", "properties": { "business_id": { "type": "integer", "example": 7 }, "business_name": { "type": "string", "nullable": true, "example": "Executive Transfers" }, "business_email": { "type": "string", "nullable": true, "example": "ops@executive.example" }, "website_url": { "type": "string", "nullable": true }, "vendor_slug": { "type": "string", "nullable": true, "example": "executive-transfers" }, "status": { "type": "string", "nullable": true, "enum": [ "A", "D", "P" ], "description": "A = active, D = disabled/suspended, P = pending.", "example": "A" }, "subscription_plan_id": { "type": "integer", "nullable": true, "example": 3 }, "subscription_status": { "type": "string", "nullable": true, "enum": [ "active", "inactive", "cancelled", "past_due" ], "example": "active" }, "email_credits": { "type": "integer", "nullable": true, "example": 500 }, "currency": { "type": "string", "nullable": true, "example": "EUR" }, "created": { "type": "string", "format": "date-time", "nullable": true }, "last_updated": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": true }, "AdminUser": { "type": "object", "description": "A platform user in the super-admin view. Password hashes and activation columns are never returned.", "properties": { "id": { "type": "integer", "example": 512 }, "name": { "type": "string", "nullable": true, "example": "New Operator" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "operator@example.com" }, "mobile_phone": { "type": "string", "nullable": true }, "account_type": { "type": "string", "enum": [ "S", "A" ], "description": "S = super-admin, A = admin.", "example": "A" }, "status": { "type": "string", "nullable": true }, "email_verified": { "type": "boolean", "nullable": true, "example": true }, "oauth_provider": { "type": "string", "nullable": true, "example": "manual" }, "last_activity": { "type": "string", "format": "date-time", "nullable": true }, "create_datetime": { "type": "string", "format": "date-time", "nullable": true } } }, "PublicInvoice": { "type": "object", "description": "Sanitised, unauthenticated view of one invoice, keyed by its payment_hash. Carries only what a payer needs \u2014 no internal ids, customer contact details, VAT number, trip/booking ids or addresses.", "properties": { "invoice_number": { "type": "string", "nullable": true, "example": "INV-2026-0042" }, "status": { "type": "string", "nullable": true, "enum": [ "draft", "open", "paid", "void", "uncollectible" ], "example": "open" }, "currency": { "type": "string", "example": "EUR" }, "business_name": { "type": "string", "nullable": true, "example": "Executive Transfers" }, "billed_to": { "type": "string", "nullable": true, "description": "Customer display name the invoice is addressed to.", "example": "Sam Lee" }, "invoice_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "amounts": { "type": "object", "properties": { "subtotal": { "type": "number", "format": "float", "example": 120.0 }, "vat_amount": { "type": "number", "format": "float", "example": 27.6 }, "total_amount": { "type": "number", "format": "float", "example": 147.6 }, "amount_paid": { "type": "number", "format": "float", "example": 0.0 }, "amount_due": { "type": "number", "format": "float", "example": 147.6 } } }, "is_paid": { "type": "boolean", "example": false }, "is_payable": { "type": "boolean", "description": "True when the invoice is in a payable state (draft/open) with a positive balance.", "example": true }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "example": "Airport transfer \u2014 DUB to city" }, "quantity": { "type": "number", "nullable": true, "example": 1 }, "unit_price": { "type": "number", "nullable": true, "example": 120.0 }, "line_total": { "type": "number", "nullable": true, "example": 120.0 } } } } } }, "PublicPaymentIntent": { "type": "object", "description": "The Stripe PaymentIntent handles the app needs to confirm the card payment client-side. The invoice is NOT marked paid here \u2014 that happens on the Stripe webhook; re-GET the invoice to observe the new status.", "properties": { "client_secret": { "type": "string", "example": "pi_3P...secret_9f2c" }, "payment_intent_id": { "type": "string", "example": "pi_3P4x2yABCD.." }, "amount": { "type": "integer", "description": "Outstanding amount in the smallest currency unit (e.g. cents).", "example": 14760 }, "currency": { "type": "string", "example": "eur" }, "invoice_number": { "type": "string", "nullable": true, "example": "INV-2026-0042" }, "publishable_key": { "type": "string", "nullable": true, "description": "Present only when the business/platform exposes one; the app needs it to initialise Stripe.js.", "example": "pk_live_..." } } }, "Device": { "type": "object", "description": "A registered push-notification device. User-scoped (belongs to a person, not a business) \u2014 it follows the user across every business they can act on.", "properties": { "id": { "type": "integer", "example": 88 }, "platform": { "type": "string", "enum": [ "ios", "android", "web" ], "example": "ios" }, "device_token": { "type": "string", "description": "The opaque push token (APNs/FCM/web-push). Unique across the platform.", "example": "fMEp...token" }, "device_name": { "type": "string", "nullable": true, "example": "iPhone 16" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }