{ "openapi": "3.1.0", "info": { "title": "Riders", "version": "1.0.0", "description": "API reference for Riders vendor integrations. Authenticate using your vendor API key as a Bearer token.\n\n## Webhooks\n\nRegister webhook endpoints (via `POST \/api\/vendor\/webhooks` or the vendor panel) to receive order status changes as they happen, instead of polling `GET \/api\/vendor\/orders\/{uid}`.\n\n### Events\n\nEvents follow the pattern `order.status.{STATUS}`, one per fleet status: `DRAFT`, `NEW`, `READY`, `DISPATCHED`, `SHIPPED`, `IN_TRANSIT`, `OUT_FOR_DELIVERY`, `DELIVERED`, `DELIVERY_ATTEMPTED`, `CANCELLED`, `CLOSED`, `DISPATCHED_FOR_RETURN`, `RETURN_IN_PROGRESS`, `RETURN_COMPLETED`, `RETURN_ATTEMPTED`, `PENDING_RETURN`. Subscribe to `[\"*\"]` to receive all of them. A `webhook.test` event is sent when you use the test endpoint.\n\n### Payload\n\n```json\n{\n \"id\": \"9c8f1e2a-5b7d-4a3e-9f2c-1d8e7b6a5c4d\",\n \"event\": \"order.status.DELIVERED\",\n \"timestamp\": \"2026-08-05T14:32:11+00:00\",\n \"data\": {\n \"order\": {\n \"id\": 123,\n \"uid\": \"RO-AB12CD\",\n \"fleetrunnr_order_number\": \"FR-000123\",\n \"fleet_status\": \"DELIVERED\",\n \"previous_fleet_status\": \"OUT_FOR_DELIVERY\",\n \"is_cancellable\": false,\n \"driver\": { \"name\": \"Ahmed\", \"phone\": \"+96555555555\" },\n \"meta_fields\": [ { \"key\": \"your_correlation_key\", \"value\": \"555\" } ]\n }\n }\n}\n```\n\n`driver.name` \/ `driver.phone` are `null` until a driver is assigned. `meta_fields` round-trips exactly what you sent when creating the order, as an array of `{key, value}` objects.\n\n### Signature\n\nEvery delivery carries an `X-Riders-Signature` header: the hex HMAC-SHA256 of the raw request body, keyed with the endpoint's signing secret (included in all webhook endpoint responses and shown in the vendor panel). Verify with a constant-time comparison:\n\n```php\n$valid = hash_equals(hash_hmac('sha256', $rawBody, $secret), $request->header('X-Riders-Signature'));\n```\n\n### Acknowledgement & retries\n\nRespond with any `2xx` status within 10 seconds to acknowledge. Anything else (or a timeout) is retried up to 5 times with exponential backoff (roughly 10s, 100s, 17min, then ~3h). Deliveries are at-least-once and can arrive out of order \u2014 deduplicate on `id` (stable across retries of the same delivery) and order by `timestamp`." }, "servers": [ { "url": "https:\/\/vendor.tryriders.com\/api", "description": "API Base URL" } ], "tags": [ { "name": "Profile" }, { "name": "Branches" }, { "name": "Geo Data" }, { "name": "Orders" }, { "name": "Webhooks" } ], "security": [ { "bearerAuth": [] } ], "paths": { "\/vendor\/me": { "get": { "operationId": "vendorProfile.me", "description": "Also available while the account is under review \u2014 use the \"status\"\nfield to check whether the account has been approved.", "summary": "My profile", "tags": [ "Profile" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "instagram": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "logo": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "payment_plan": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone", "instagram", "tags", "logo", "status", "payment_plan", "created_at" ] } }, "required": [ "success", "message", "data" ] } } } } } }, "put": { "operationId": "vendorProfile.update", "summary": "Update my profile", "tags": [ "Profile" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateVendorProfileRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Profile updated successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "instagram": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "logo": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "payment_plan": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone", "instagram", "tags", "logo", "status", "payment_plan", "created_at" ] } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/me\/logo": { "post": { "operationId": "vendorProfile.updateLogo", "description": "Accepts either a multipart image upload (\"logo\") or a direct, publicly\naccessible image URL (\"logo_url\"). JPEG, PNG and WebP up to 4 MB are\nsupported. The previous logo is replaced.", "summary": "Update my logo", "tags": [ "Profile" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/UpdateVendorLogoRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Logo updated successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "instagram": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "logo": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "payment_plan": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone", "instagram", "tags", "logo", "status", "payment_plan", "created_at" ] } }, "required": [ "success", "message", "data" ] }, { "type": "string" } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/shipping-methods": { "get": { "operationId": "vendorProfile.shippingMethods", "description": "The methods this account may use on orders. \/geo\/areas lists methods\navailable in an area generally, not this account's entitlement.", "summary": "Available shipping methods", "tags": [ "Profile" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "name_en": { "type": "string" }, "name_ar": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "name_en", "name_ar" ] } } }, "required": [ "shipping_methods" ] } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/branches": { "get": { "operationId": "vendorBranch.index", "summary": "My branches", "tags": [ "Branches" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "branches": { "type": "array", "items": {} } }, "required": [ "branches" ] } }, "required": [ "success", "message", "data" ] } } } } } }, "post": { "operationId": "vendorBranch.store", "summary": "Create branch", "tags": [ "Branches" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreVendorBranchRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch created successfully" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "string" }, "phone": { "type": "string" }, "governorate_id": { "type": "string" }, "area_id": { "type": "string" }, "block_id": { "type": "string" }, "street_id": { "type": "string" }, "governorate": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "avenue": { "type": "string" }, "house": { "type": "string" }, "notes": { "type": "string" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" } }, "required": [ "lat", "lng" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_default", "phone", "governorate_id", "area_id", "block_id", "street_id", "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates", "created_at" ] } }, "required": [ "branch" ] } }, "required": [ "success", "message", "data" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/branches\/{branchId}": { "get": { "operationId": "vendorBranch.show", "summary": "Branch details", "tags": [ "Branches" ], "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "string" }, "phone": { "type": "string" }, "governorate_id": { "type": "string" }, "area_id": { "type": "string" }, "block_id": { "type": "string" }, "street_id": { "type": "string" }, "governorate": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "avenue": { "type": "string" }, "house": { "type": "string" }, "notes": { "type": "string" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" } }, "required": [ "lat", "lng" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_default", "phone", "governorate_id", "area_id", "block_id", "street_id", "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates", "created_at" ] } }, "required": [ "branch" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } }, "put": { "operationId": "vendorBranch.update", "summary": "Update branch", "tags": [ "Branches" ], "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateVendorBranchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch updated successfully" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "string" }, "phone": { "type": "string" }, "governorate_id": { "type": "string" }, "area_id": { "type": "string" }, "block_id": { "type": "string" }, "street_id": { "type": "string" }, "governorate": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "avenue": { "type": "string" }, "house": { "type": "string" }, "notes": { "type": "string" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" } }, "required": [ "lat", "lng" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_default", "phone", "governorate_id", "area_id", "block_id", "street_id", "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates", "created_at" ] } }, "required": [ "branch" ] } }, "required": [ "success", "message", "data" ] }, { "type": "string" } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "vendorBranch.destroy", "description": "The default branch cannot be deleted while other branches exist, and the\nlast remaining branch cannot be deleted.", "summary": "Delete branch", "tags": [ "Branches" ], "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch deleted successfully" }, "data": { "type": "object", "properties": { "branch_id": { "type": "string" } }, "required": [ "branch_id" ] } }, "required": [ "success", "message", "data" ] }, { "type": "string" } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/branches\/{branchId}\/default": { "post": { "operationId": "vendorBranch.setDefault", "summary": "Set default branch", "tags": [ "Branches" ], "parameters": [ { "name": "branchId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Default branch updated successfully" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "is_default": { "type": "string" }, "phone": { "type": "string" }, "governorate_id": { "type": "string" }, "area_id": { "type": "string" }, "block_id": { "type": "string" }, "street_id": { "type": "string" }, "governorate": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "block": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "avenue": { "type": "string" }, "house": { "type": "string" }, "notes": { "type": "string" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" } }, "required": [ "lat", "lng" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "is_default", "phone", "governorate_id", "area_id", "block_id", "street_id", "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates", "created_at" ] } }, "required": [ "branch" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Branch not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/search-by-pacino": { "get": { "operationId": "geoData.searchByPACINo", "description": "Retrives the exact address of a given PACINo\n\nVIP customers can retrieve inactive areas.", "summary": "Search by PACINo", "tags": [ "Geo Data" ], "parameters": [ { "name": "civilid", "in": "query", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] }, "block": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "street": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "house": { "type": "string" }, "notes": { "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "lat": { "type": "null" }, "lng": { "type": "null" } }, "required": [ "lat", "lng" ] } ] } }, "required": [ "governorate", "area", "block", "street", "house", "notes", "location" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "No address found for this civil ID" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "KF Server Error, please try again later" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/geo\/govs": { "get": { "operationId": "geoData.getGovernorates", "description": "Retrieves all governorates marked as active from the database,\ntransforms them using the GovernorateTransformer, and returns\nthe transformed collection as a JSON response.", "summary": "List active governorates", "tags": [ "Geo Data" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/areas": { "get": { "operationId": "geoData.getAreas", "description": "Retrieves all areas marked as active from the database that are\nassociated with the given governorate_id, transforms them using the\nAreaTransformer, and returns the transformed collection as a JSON\nresponse.\n\nVIP customers can see all areas (including inactive ones).", "summary": "List active areas for a given governorate", "tags": [ "Geo Data" ], "parameters": [ { "name": "governorate_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/blocks": { "get": { "operationId": "geoData.getBlocks", "description": "Retrieves all blocks from the database that are associated with the\nprovided area_id, transforms them using the BlockTransformer, and\nreturns the transformed collection as a JSON response.", "summary": "List blocks for a specific area", "tags": [ "Geo Data" ], "parameters": [ { "name": "area_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/streets": { "get": { "operationId": "geoData.getStreets", "description": "Retrieves all streets from the database that are associated with the\nprovided block_id, transforms them using the StreetTransformer, and\nreturns the transformed collection as a JSON response.", "summary": "List streets for a specific block", "tags": [ "Geo Data" ], "parameters": [ { "name": "block_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "array", "items": {} } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/houses": { "get": { "operationId": "geoData.getHousesByStreet", "description": "Retrieves all houses from PACI data that are associated with the provided street_id", "summary": "Get houses for a specific street", "tags": [ "Geo Data" ], "parameters": [ { "name": "street_id", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Houses retrieved successfully" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "unit_type": { "type": "string" }, "building_type": { "type": "string" }, "unit_no": { "type": "string" }, "coordinates": { "type": "object", "properties": { "lat": { "type": "string" }, "lng": { "type": "string" } }, "required": [ "lat", "lng" ] } }, "required": [ "name", "unit_type", "building_type", "unit_no", "coordinates" ] } } }, "required": [ "success", "message", "data" ] }, { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "No houses found for this street" }, "data": { "type": "object", "properties": { "street": { "anyOf": [ { "$ref": "#\/components\/schemas\/Street" }, { "type": "null" } ] } }, "required": [ "street" ] } }, "required": [ "success", "message", "data" ] } ] } } } } } } }, "\/geo\/geo-by-coordinates": { "get": { "operationId": "geoData.getGeoByCoordinates", "description": "When include_relations=true, the response will include:\n- gov.areas (all areas in the governorate)\n- area.blocks (all blocks in the area)\n- block.streets (all streets in the block)", "summary": "Reverse search by coordinates within a radius (meters)", "tags": [ "Geo Data" ], "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "include_relations", "in": "query", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "radius", "in": "query", "schema": { "type": [ "number", "null" ], "minimum": 1, "maximum": 500 } } ], "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Location found" }, "data": { "type": "object", "properties": { "gov": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] }, "block": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "street": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "house": { "type": "string" }, "notes": { "type": "string" }, "coordinates": { "type": "string" }, "distance_meters": { "type": "string" }, "accuracy_note": { "type": "string" }, "original_coordinates": { "type": "string" } }, "required": [ "gov", "area", "block", "street", "house", "notes", "coordinates", "distance_meters", "accuracy_note", "original_coordinates" ] } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/resolve-coordinates": { "post": { "operationId": "geoData.resolveAddressCoordinates", "description": "Resolve coordinates for an address based on street and house information", "summary": "Resolve coordinates for address", "tags": [ "Geo Data" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "street_id": { "type": "integer" }, "house": { "type": "string" }, "governorate_id": { "type": [ "integer", "null" ] }, "area_id": { "type": [ "integer", "null" ] }, "block_id": { "type": [ "integer", "null" ] } }, "required": [ "street_id", "house" ] } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Address coordinates resolved successfully" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/geo\/resolve-address": { "post": { "operationId": "geoData.resolveAddressText", "description": "Resolves a one-line Kuwaiti address (English or Arabic, any formatting\nquality) into governorate\/area\/block\/street components, coordinates and\na confidence score, using local geo data and Kuwait Finder services.\n\nThe `delivery_address` key in the response is ready to be posted\nverbatim as the structured address of a vendor order.", "summary": "Resolve free-text address", "tags": [ "Geo Data" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "minLength": 5, "maxLength": 500 } }, "required": [ "address" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Address resolved successfully" }, "data": { "type": "object", "properties": { "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] }, "block": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "street": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "house": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avenue": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "notes": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "coordinates": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "lat", "lng" ] }, "confidence": { "type": "integer" }, "method": { "type": "string" }, "warnings": { "anyOf": [ { "type": "array", "items": {} }, { "type": "string" } ] }, "delivery_address": { "type": "string" } }, "required": [ "governorate", "area", "block", "street", "house", "avenue", "notes", "coordinates", "confidence", "method", "warnings", "delivery_address" ] } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/orders\/calculate": { "post": { "operationId": "vendorOrder.calculate", "description": "Returns a full, itemised price breakdown for a prospective vendor order\n(delivery zone shipping price + distance) WITHOUT creating an order,\npriced against the vendor's assigned delivery zone. The \"available\" flag\nreports whether the shipping method can serve the branch \u2192 delivery route.\nAccepts an area_id and\/or explicit coordinates for the delivery. Passing\norder_type=roundtrip prices the trip in both directions.\nshipping_method_id follows the same entitlement as create: omit it or\npass the assigned method when the account is fixed; choosable accounts\nmust pass an allowed method.", "summary": "Calculate order cost", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/VendorCalculateOrderRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Order cost calculated successfully", "Unable to calculate the order cost", "Data retrieved successfully" ] } ] }, "data": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean" }, "message": { "type": [ "string", "null" ] }, "currency": { "type": "string", "const": "KWD" }, "order_type": { "type": "string" }, "distance": { "type": "object", "properties": { "km": { "type": [ "number", "null" ] }, "mode": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "km", "mode", "label" ] }, "shipping": { "type": [ "object", "null" ], "properties": { "charge_type": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "fixed" ] } ] }, "charge_type_label": { "type": "string", "enum": [ "Distance based", "Default price", "Fixed price" ] }, "sector_id": { "type": [ "string", "null" ] }, "base_price": { "type": "number" }, "base_km": { "type": [ "number", "null" ] }, "price_per_km": { "type": [ "number", "null" ] }, "chargeable_km": { "type": [ "integer", "null" ] }, "additional_cost": { "type": [ "number", "null" ] }, "max_price": { "type": [ "number", "null" ] }, "max_applied": { "type": "boolean" }, "price": { "type": "number" } }, "required": [ "charge_type", "charge_type_label", "sector_id", "base_price", "base_km", "price_per_km", "chargeable_km", "additional_cost", "max_price", "max_applied", "price" ] }, "roundtrip": { "type": "object", "properties": { "applied": { "type": "boolean" }, "multiplier": { "type": "integer", "enum": [ 2, 1 ] } }, "required": [ "applied", "multiplier" ] }, "subtotal": { "type": "number" }, "fees": { "type": "object", "properties": { "total": { "type": "number" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "key", "label", "amount" ] } } }, "required": [ "total", "items" ] }, "tips": { "type": "number" }, "coupon": { "type": [ "string", "null" ] }, "discount": { "type": "number" }, "total": { "type": "number" } }, "required": [ "available", "message", "currency", "order_type", "distance", "shipping", "roundtrip", "subtotal", "fees", "tips", "coupon", "discount", "total" ] }, { "type": "object", "properties": { "available": { "type": "boolean" }, "message": { "type": [ "string", "null" ] }, "currency": { "type": "string", "const": "KWD" }, "order_type": { "type": "string" }, "distance": { "type": "object", "properties": { "km": { "type": [ "number", "null" ] }, "mode": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "km", "mode", "label" ] }, "shipping": { "type": [ "object", "null" ], "properties": { "charge_type": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "fixed" ] } ] }, "charge_type_label": { "type": "string", "enum": [ "Distance based", "Default price", "Fixed price" ] }, "sector_id": { "type": [ "string", "null" ] }, "base_price": { "type": "number" }, "base_km": { "type": [ "number", "null" ] }, "price_per_km": { "type": [ "number", "null" ] }, "chargeable_km": { "type": [ "integer", "null" ] }, "additional_cost": { "type": [ "number", "null" ] }, "max_price": { "type": [ "number", "null" ] }, "max_applied": { "type": "boolean" }, "price": { "type": "number" } }, "required": [ "charge_type", "charge_type_label", "sector_id", "base_price", "base_km", "price_per_km", "chargeable_km", "additional_cost", "max_price", "max_applied", "price" ] }, "roundtrip": { "type": "object", "properties": { "applied": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ] }, "multiplier": { "type": "integer", "enum": [ 2, 1 ] } }, "required": [ "applied", "multiplier" ] }, "subtotal": { "type": "number" }, "fees": { "type": "object", "properties": { "total": { "type": "number" }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "key", "label", "amount" ] } } }, "required": [ "total", "items" ] }, "tips": { "type": "number" }, "coupon": { "type": [ "string", "null" ] }, "discount": { "type": "number" }, "total": { "type": "number" } }, "required": [ "available", "message", "currency", "order_type", "distance", "shipping", "roundtrip", "subtotal", "fees", "tips", "coupon", "discount", "total" ] } ] } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/orders": { "post": { "operationId": "vendorOrder.store", "description": "shipping_method_id may be omitted, or must match the account's assigned\nmethod, when the vendor cannot choose. Choosable accounts must pass an\nallowed method.", "summary": "Create order", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/VendorOrderRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Order created successfully" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "uid": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor_branch": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] } }, "required": [ "id", "name", "phone", "governorate", "area" ] }, "recipient_name_first": { "type": "string" }, "recipient_name_last": { "type": "string" }, "recipient_phone": { "type": "string" }, "delivery_address": { "type": "object", "properties": { "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] }, "block": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "street": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "avenue": { "type": [ "string", "null" ] }, "house": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "coordinates": { "type": "object", "properties": { "lat": { "type": [ "string", "null" ] }, "lng": { "type": [ "string", "null" ] } }, "required": [ "lat", "lng" ] } }, "required": [ "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates" ] }, "meta_fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "key", "value" ] } }, "shipping_method": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "type": { "type": "string" }, "is_active": { "type": "boolean" }, "default_price": { "type": "string" } }, "required": [ "id", "name", "image", "type", "is_active", "default_price" ] }, "order_type": { "type": "string" }, "roundtrip": { "type": [ "object", "null" ], "properties": { "group_uid": { "type": "string" }, "leg": { "type": "integer", "enum": [ 1, 2 ] }, "linked_uid": { "type": "string" } }, "required": [ "group_uid", "leg", "linked_uid" ] }, "base_price": { "type": "string" }, "subtotal": { "type": "string" }, "total": { "type": "string" }, "status": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ] }, "fleet_status": { "type": "string" }, "fleetrunnr_order_number": { "type": "string" }, "driver": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "phone" ] }, "is_cancellable": { "type": "boolean" }, "schedule_date": { "type": "string" }, "bulk_order_uid": { "type": "string" }, "created_at": { "type": "string" }, "formated_date": { "type": [ "string", "null" ] }, "formated_time": { "type": [ "string", "null" ] } }, "required": [ "id", "uid", "vendor_id", "vendor_branch", "recipient_name_first", "recipient_name_last", "recipient_phone", "delivery_address", "meta_fields", "shipping_method", "order_type", "roundtrip", "base_price", "subtotal", "total", "status", "tracking_url", "fleet_status", "fleetrunnr_order_number", "driver", "is_cancellable", "schedule_date", "bulk_order_uid", "created_at", "formated_date", "formated_time" ] } }, "required": [ "order" ] } }, "required": [ "success", "message", "data" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "get": { "operationId": "vendorOrder.index", "summary": "List orders", "tags": [ "Orders" ], "parameters": [ { "name": "filter[status]", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "paid", "unpaid", "cancelled", null ] } }, { "name": "filter[fleet_status]", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "DRAFT", "NEW", "READY", "DISPATCHED", "SHIPPED", "IN_TRANSIT", "OUT_FOR_DELIVERY", "DELIVERED", "DELIVERY_ATTEMPTED", "CANCELLED", "CLOSED", "DISPATCHED_FOR_RETURN", "RETURN_IN_PROGRESS", "RETURN_COMPLETED", "RETURN_ATTEMPTED", "PENDING_RETURN", null ] } }, { "name": "size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Orders retrieved successfully" }, "data": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "object", "properties": { "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "links": { "type": "object", "properties": { "next": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "first": { "type": "string" }, "last": { "type": "string" } }, "required": [ "next", "prev", "first", "last" ] } }, "required": [ "current_page", "last_page", "per_page", "total", "links" ] }, "data": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "meta", "data" ] } ] } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/orders\/bulk": { "post": { "operationId": "vendorOrder.storeBulk", "description": "Create many orders in one request, grouped by a shared bulk_order_uid.", "summary": "Create bulk order", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/VendorBulkOrderRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Bulk order created successfully" }, "data": { "type": "object", "properties": { "bulk_order_uid": { "type": "string" }, "total": { "type": "number" }, "orders": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "bulk_order_uid", "total", "orders" ] } }, "required": [ "success", "message", "data" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/orders\/{uid}": { "get": { "operationId": "vendorOrder.show", "summary": "Get order", "tags": [ "Orders" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "uid": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor_branch": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] } }, "required": [ "id", "name", "phone", "governorate", "area" ] }, "recipient_name_first": { "type": "string" }, "recipient_name_last": { "type": "string" }, "recipient_phone": { "type": "string" }, "delivery_address": { "type": "object", "properties": { "governorate": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "area": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" }, "shipping_methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number", "description": "[DEPRECATED area-pricing] 'price' => $area->getPriceForShippingMethod($method->id) ?? (float) $method->default_price," }, "image": { "type": "string" }, "is_active": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "price", "image", "is_active", "type" ] } } }, "required": [ "id", "objectid", "name", "lng", "lat", "shipping_methods" ] }, "block": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "street": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "objectid": { "type": "string" }, "name": { "type": "string" }, "lng": { "type": "string" }, "lat": { "type": "string" } }, "required": [ "id", "objectid", "name", "lng", "lat" ] }, "avenue": { "type": [ "string", "null" ] }, "house": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "coordinates": { "type": "object", "properties": { "lat": { "type": [ "string", "null" ] }, "lng": { "type": [ "string", "null" ] } }, "required": [ "lat", "lng" ] } }, "required": [ "governorate", "area", "block", "street", "avenue", "house", "notes", "coordinates" ] }, "meta_fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "key", "value" ] } }, "shipping_method": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "type": { "type": "string" }, "is_active": { "type": "boolean" }, "default_price": { "type": "string" } }, "required": [ "id", "name", "image", "type", "is_active", "default_price" ] }, "order_type": { "type": "string" }, "roundtrip": { "type": [ "object", "null" ], "properties": { "group_uid": { "type": "string" }, "leg": { "type": "integer", "enum": [ 1, 2 ] }, "linked_uid": { "type": "string" } }, "required": [ "group_uid", "leg", "linked_uid" ] }, "base_price": { "type": "string" }, "subtotal": { "type": "string" }, "total": { "type": "string" }, "status": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ] }, "fleet_status": { "type": "string" }, "fleetrunnr_order_number": { "type": "string" }, "driver": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name", "phone" ] }, "is_cancellable": { "type": "boolean" }, "schedule_date": { "type": "string" }, "bulk_order_uid": { "type": "string" }, "created_at": { "type": "string" }, "formated_date": { "type": [ "string", "null" ] }, "formated_time": { "type": [ "string", "null" ] } }, "required": [ "id", "uid", "vendor_id", "vendor_branch", "recipient_name_first", "recipient_name_last", "recipient_phone", "delivery_address", "meta_fields", "shipping_method", "order_type", "roundtrip", "base_price", "subtotal", "total", "status", "tracking_url", "fleet_status", "fleetrunnr_order_number", "driver", "is_cancellable", "schedule_date", "bulk_order_uid", "created_at", "formated_date", "formated_time" ] } }, "required": [ "order" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Order not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/orders\/{uid}\/cancel": { "post": { "operationId": "vendorOrder.cancel", "summary": "Cancel order", "tags": [ "Orders" ], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Order cancelled successfully" }, "data": { "type": "object", "properties": { "order_uid": { "type": "string" } }, "required": [ "order_uid" ] } }, "required": [ "success", "message", "data" ] }, { "type": "string" } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Order not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/webhooks": { "get": { "operationId": "vendorWebhook.index", "description": "List all registered webhook endpoints, including each endpoint's\nsigning secret.", "summary": "My webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": {} } }, "required": [ "webhooks" ] } }, "required": [ "success", "message", "data" ] } } } } } }, "post": { "operationId": "vendorWebhook.store", "description": "Register an endpoint URL and the events it should receive. The response\nincludes the signing `secret` used for the X-Riders-Signature header.\nUse `[\"*\"]` in `events` to subscribe to every event.", "summary": "Register webhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreVendorWebhookRequest" } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook registered successfully" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "string" }, "secret": { "type": "string" }, "is_active": { "type": "string" }, "last_triggered_at": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "secret", "is_active", "last_triggered_at", "last_success_at", "consecutive_failures", "created_at" ] } }, "required": [ "webhook" ] } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/vendor\/webhooks\/{webhookId}": { "get": { "operationId": "vendorWebhook.show", "summary": "Webhook details", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "string" }, "secret": { "type": "string" }, "is_active": { "type": "string" }, "last_triggered_at": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "secret", "is_active", "last_triggered_at", "last_success_at", "consecutive_failures", "created_at" ] } }, "required": [ "webhook" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } }, "put": { "operationId": "vendorWebhook.update", "summary": "Update webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateVendorWebhookRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook updated successfully" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "string" }, "secret": { "type": "string" }, "is_active": { "type": "string" }, "last_triggered_at": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "secret", "is_active", "last_triggered_at", "last_success_at", "consecutive_failures", "created_at" ] } }, "required": [ "webhook" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "vendorWebhook.destroy", "summary": "Delete webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook deleted successfully" }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string" } }, "required": [ "webhook_id" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/webhooks\/{webhookId}\/test": { "post": { "operationId": "vendorWebhook.test", "description": "Queue a `webhook.test` delivery to this endpoint so you can verify\nreachability and signature handling. Delivered regardless of the\nendpoint's event subscriptions.", "summary": "Send test delivery", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Test delivery queued" }, "data": { "type": "object", "properties": { "delivery_uuid": { "type": "string" } }, "required": [ "delivery_uuid" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/webhooks\/{webhookId}\/rotate-secret": { "post": { "operationId": "vendorWebhook.rotateSecret", "description": "Generate a new signing secret for this endpoint. The response includes\nthe new `secret`. The old secret stops being used immediately.", "summary": "Rotate secret", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook secret rotated successfully" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "string" }, "secret": { "type": "string" }, "is_active": { "type": "string" }, "last_triggered_at": { "type": [ "string", "null" ] }, "last_success_at": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "secret", "is_active", "last_triggered_at", "last_success_at", "consecutive_failures", "created_at" ] } }, "required": [ "webhook" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } }, "\/vendor\/webhooks\/{webhookId}\/deliveries": { "get": { "operationId": "vendorWebhook.deliveries", "description": "Paginated log of recent delivery attempts for this endpoint, newest first.", "summary": "Delivery log", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Data retrieved successfully" }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": {} } }, "required": [ "deliveries" ] } }, "required": [ "success", "message", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Webhook not found" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "success", "message", "data" ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "StoreVendorBranchRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "pattern": "^(18\\d{5}|(?:[2569]\\d|41)\\d{6})$" }, "governorate_id": { "type": "integer" }, "area_id": { "type": "integer" }, "block_id": { "type": [ "integer", "null" ] }, "street_id": { "type": [ "integer", "null" ] }, "avenue": { "type": [ "string", "null" ], "maxLength": 255 }, "house": { "type": [ "string", "null" ], "maxLength": 255 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "coordinates": { "type": "object", "properties": { "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } } } }, "required": [ "name", "governorate_id", "area_id" ], "title": "StoreVendorBranchRequest" }, "StoreVendorWebhookRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "order.status.DRAFT", "order.status.NEW", "order.status.READY", "order.status.DISPATCHED", "order.status.SHIPPED", "order.status.IN_TRANSIT", "order.status.OUT_FOR_DELIVERY", "order.status.DELIVERED", "order.status.DELIVERY_ATTEMPTED", "order.status.CANCELLED", "order.status.CLOSED", "order.status.DISPATCHED_FOR_RETURN", "order.status.RETURN_IN_PROGRESS", "order.status.RETURN_COMPLETED", "order.status.RETURN_ATTEMPTED", "order.status.PENDING_RETURN" ] }, "minItems": 1 }, "is_active": { "type": "boolean" } }, "required": [ "url", "events" ], "title": "StoreVendorWebhookRequest" }, "Street": { "type": "object", "properties": { "id": { "type": "integer" }, "block_id": { "type": "integer" }, "name_en": { "type": "string" }, "name_ar": { "type": [ "string", "null" ] }, "lat": { "type": [ "string", "null" ] }, "lng": { "type": [ "string", "null" ] }, "objectid": { "type": [ "string", "null" ] }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "block_id", "name_en", "name_ar", "lat", "lng", "objectid", "deleted_at" ], "title": "Street" }, "UpdateVendorBranchRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "pattern": "^(18\\d{5}|(?:[2569]\\d|41)\\d{6})$" }, "governorate_id": { "type": "integer" }, "area_id": { "type": "integer" }, "block_id": { "type": [ "integer", "null" ] }, "street_id": { "type": [ "integer", "null" ] }, "avenue": { "type": [ "string", "null" ], "maxLength": 255 }, "house": { "type": [ "string", "null" ], "maxLength": 255 }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 }, "coordinates": { "type": "object", "properties": { "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } } } }, "title": "UpdateVendorBranchRequest" }, "UpdateVendorLogoRequest": { "type": "object", "properties": { "logo": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 4096 kilobytes." }, "logo_url": { "type": "string", "format": "uri", "maxLength": 4096 } }, "title": "UpdateVendorLogoRequest" }, "UpdateVendorProfileRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "pattern": "^(18\\d{5}|(?:[2569]\\d|41)\\d{6})$" }, "instagram": { "type": [ "string", "null" ], "maxLength": 255 }, "password": { "type": "string", "minLength": 8, "maxLength": 60 }, "current_password": { "type": "string" } }, "title": "UpdateVendorProfileRequest" }, "UpdateVendorWebhookRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "order.status.DRAFT", "order.status.NEW", "order.status.READY", "order.status.DISPATCHED", "order.status.SHIPPED", "order.status.IN_TRANSIT", "order.status.OUT_FOR_DELIVERY", "order.status.DELIVERED", "order.status.DELIVERY_ATTEMPTED", "order.status.CANCELLED", "order.status.CLOSED", "order.status.DISPATCHED_FOR_RETURN", "order.status.RETURN_IN_PROGRESS", "order.status.RETURN_COMPLETED", "order.status.RETURN_ATTEMPTED", "order.status.PENDING_RETURN" ] }, "minItems": 1 }, "is_active": { "type": "boolean" } }, "title": "UpdateVendorWebhookRequest" }, "VendorBulkOrderRequest": { "type": "object", "properties": { "shipping_method_id": { "type": [ "integer", "null" ] }, "vendor_branch_id": { "type": [ "integer", "null" ] }, "schedule_date": { "type": [ "string", "null" ], "format": "date-time" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "recipient_name_first": { "type": "string", "maxLength": 50 }, "recipient_name_last": { "type": "string", "maxLength": 50 }, "recipient_phone": { "type": "string" }, "delivery_address": { "type": "object", "properties": { "coordinates": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "lat", "lng" ] }, "governorate_id": { "type": "integer" }, "area_id": { "type": "integer" }, "block_id": { "type": [ "integer", "null" ] }, "street_id": { "type": [ "integer", "null" ] }, "avenue": { "type": [ "string", "null" ] }, "house": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "coordinates", "governorate_id", "area_id" ] }, "meta_fields": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 255 }, "value": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "key" ] } } }, "required": [ "recipient_name_first", "recipient_name_last", "recipient_phone", "delivery_address" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "recipients" ], "title": "VendorBulkOrderRequest" }, "VendorCalculateOrderRequest": { "type": "object", "properties": { "vendor_branch_id": { "type": [ "integer", "null" ] }, "shipping_method_id": { "type": [ "integer", "null" ] }, "order_type": { "type": [ "string", "null" ], "enum": [ "normal", "roundtrip", "bulk", null ] }, "delivery_address": { "type": "object", "properties": { "area_id": { "type": [ "integer", "null" ] }, "coordinates": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } } } } } }, "required": [ "delivery_address" ], "title": "VendorCalculateOrderRequest" }, "VendorOrderRequest": { "type": "object", "properties": { "shipping_method_id": { "type": [ "integer", "null" ] }, "vendor_branch_id": { "type": [ "integer", "null" ] }, "order_type": { "type": [ "string", "null" ], "enum": [ "normal", "roundtrip", "bulk", null ] }, "recipient_name_first": { "type": "string", "maxLength": 50 }, "recipient_name_last": { "type": "string", "maxLength": 50 }, "recipient_phone": { "type": "string" }, "delivery_address": { "type": "object", "properties": { "coordinates": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "lat", "lng" ] }, "governorate_id": { "type": "integer" }, "area_id": { "type": "integer" }, "block_id": { "type": [ "integer", "null" ] }, "street_id": { "type": [ "integer", "null" ] }, "avenue": { "type": [ "string", "null" ] }, "house": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "coordinates", "governorate_id", "area_id" ] }, "meta_fields": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 255 }, "value": { "type": [ "string", "null" ], "maxLength": 255 } }, "required": [ "key" ] } }, "schedule_date": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "recipient_name_first", "recipient_name_last", "recipient_phone", "delivery_address" ], "title": "VendorOrderRequest" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }