{
  "openapi": "3.0.4",
  "info": {
    "title": "LastMile Public API",
    "description": "The LastMile Public API lets a shipping company build its own website or integration on top of its LastMile account.\r\nAll endpoints live under `/api/public/v1`. Request and response bodies are JSON (camelCase); enums are strings.\r\n\r\n## Authentication\r\nUse **one** of the two methods on every request except `auth/login` and `auth/refresh`:\r\n\r\n1. **Username and password.** `POST /api/public/v1/auth/login` returns an `accessToken` (a JWT) and a single-use\r\n   `refreshToken`. Send `Authorization: Bearer <accessToken>`. Renew with `POST /api/public/v1/auth/refresh`.\r\n   The caller's dashboard permissions decide what is allowed.\r\n2. **API key and secret.** Create a key in the dashboard under Settings > API access. Send both headers:\r\n   `X-API-Key: lmc_live_...` and `X-API-Secret: <secret>`. The secret is shown once at creation. Each key has\r\n   scopes (`shipments:read`, `shipments:write`, `merchants:read`, `merchants:write`, `geography:read`,\r\n   `pricing:read`, `branches:read`, `webhooks:manage`) and an optional expiry. Use `GET /api/public/v1/auth/me`\r\n   to see which scopes a credential holds.\r\n\r\nSending both an `Authorization: Bearer` header and an `X-API-Key` header on the same request is rejected with\r\n`400 ambiguous_credentials`; send exactly one kind of credential.\r\n\r\nThe public API must be enabled for the company (granted by the platform and switched on in company settings);\r\notherwise every call answers `403 channel_disabled`.\r\n\r\n## Errors\r\nEvery non-2xx response has the same body:\r\n```json\r\n{ \"code\": \"shipment.not_found\", \"message\": \"...\", \"status\": 404, \"details\": null, \"traceId\": \"00-...\" }\r\n```\r\n`code` is stable and meant for programs; `message` is Arabic by default and English when the\r\n`Accept-Language` header prefers English (the Arabic text is then in `details.messageAr`).\r\n`details` is `{ \"errors\": { \"field\": [\"message\"] } }` for `400 validation_failed`, and\r\n`{ \"level\", \"input\", \"candidates\": [...] }` for geography errors (`geo_city_not_found`, ...).\r\nGeneric codes: `unauthorized` (401), `forbidden` (403), `channel_disabled` (403), `company_required` (403),\r\n`tenant_blocked` (403), `validation_failed` (400), `ambiguous_credentials` (400), `rate_limited` (429), `business_rule_violation` (422),\r\n`internal_error` (500). Business errors use `<area>.<reason>` codes, 404 for not found, 409 for conflicts and\r\n422 for rule violations.\r\n\r\n## Pagination\r\nList endpoints accept `page` (default 1) and `pageSize` (default 25, maximum 100) and return\r\n`{ \"items\": [], \"page\": 1, \"pageSize\": 25, \"totalCount\": 0, \"totalPages\": 0 }`.\r\n\r\n## Rate limits\r\n120 requests per minute per API key (or per signed-in user) by default, plus a higher ceiling per network address\r\n(600 per minute) that applies before authentication. Over the limit the\r\nAPI answers `429 rate_limited` with a `Retry-After` header (seconds). Sign-in is limited per network address and\r\nfailed attempts lock the account temporarily.\r\n\r\n## Idempotency\r\n`POST /shipments`, `POST /merchants` and `POST /merchants/{id}/addresses` accept an optional `Idempotency-Key`\r\nheader (`X-Idempotency-Key` is an alias). Retrying with the same key and the same body within 24 hours returns the\r\nfirst response with the header `Idempotent-Replayed: true`; the same key with a different body answers\r\n`409 idempotency_key_reused`. Keys are scoped to your company and credential; failed attempts are not remembered.\r\n\r\n## Places by name\r\nWherever a country, city or district is accepted, you may send an id, a code or a name in Arabic or English.\r\nNames are matched strictly and nothing is ever created: failures answer `422` with `geo_country_not_found`,\r\n`geo_city_not_found`, `geo_district_not_found`, `geo_city_ambiguous` or `geo_district_ambiguous`, with\r\n`details.field` naming the failed address (`pickup`, `recipient`, `address`) and `details.candidates` suggesting\r\nthe closest matches. Addresses in Saudi Arabia need the national `shortAddress` (4 letters and 4 digits).\r\n\r\n## Webhooks\r\nA webhook subscription belongs to a merchant (`/merchants/{merchantId}/webhooks`) and receives that merchant's\r\nshipment events. Every delivery is a `POST` with a JSON body `{ \"event\", \"occurredAt\", \"data\" }` and the headers\r\n`X-Event-Type`, `X-Signature` and `X-Webhook-Signature`. The signature is the lowercase hexadecimal\r\nHMAC-SHA256 of the raw request body keyed with the subscription secret: `hex(HMAC_SHA256(secret, rawBody))`.\r\nAnswer any 2xx status; failures are retried after 1, 5 and 15 minutes.\r\n\r\n## Merchant logins\r\nA password login that belongs to a merchant can only see and book its own merchant's shipments, read its own\r\nmerchant record and addresses, and quote prices. Editing and cancelling shipments, managing merchants and\r\nreading other merchants answer `403` or `404`.",
    "version": "v1"
  },
  "paths": {
    "/api/public/v1/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Sign in with username and password.",
        "description": "Returns a bearer token pair. Failed attempts count toward the same lockout and per-network/device\r\nthrottling as the dashboard sign-in (HTTP 401 `auth.invalid_credentials`, then 429\r\n`auth.login_temporarily_blocked`). The company must have the public API enabled, otherwise\r\n403 `channel_disabled` and no token is issued. Rate limit policy: 30 requests per minute per IP.",
        "requestBody": {
          "description": "The credentials.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLoginRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLoginRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicLoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "Wrong username or password.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "Public API disabled for the company, company suspended, or account inactive.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many attempts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/auth/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Describe the current caller: company, user or API key, scopes and permissions.",
        "description": "Requires authentication (bearer token, or X-API-Key with X-API-Secret). No scope is needed.",
        "responses": {
          "200": {
            "description": "The caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "Public API disabled for the company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/auth/refresh": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Exchange a refresh token for a new token pair.",
        "description": "The refresh token is single use: store the new one returned here. Rate limit: 10 requests per minute per IP.",
        "requestBody": {
          "description": "The refresh token.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicRefreshRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicRefreshRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicRefreshRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New token pair.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTokenResponse"
                }
              }
            }
          },
          "401": {
            "description": "The refresh token is invalid or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "Public API disabled for the company.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/branches": {
      "get": {
        "tags": [
          "Branches"
        ],
        "summary": "List branches.",
        "description": "Paginated; ordered by name. Scope `branches:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional text matched against name, code and city.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "activeOnly",
            "in": "query",
            "description": "When true, only active branches.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of branches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicBranchDtoPublicPage"
                }
              }
            }
          },
          "403": {
            "description": "Missing scope or public API disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/branches/{id}": {
      "get": {
        "tags": [
          "Branches"
        ],
        "summary": "Get one branch.",
        "description": "Scope `branches:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Branch id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicBranchDto"
                }
              }
            }
          },
          "404": {
            "description": "Code `branch.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/cities": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "List cities, optionally of one country.",
        "description": "Active approved cities plus your company's own pending cities (`pending: true`). Paginated;\r\nscope `geography:read`.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Optional country: id, ISO code (e.g. `SA`) or name in Arabic or English.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional text matched against the Arabic name, English name and city code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of cities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCityDtoPublicPage"
                }
              }
            }
          },
          "422": {
            "description": "The country could not be resolved (`geo_country_not_found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/countries": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "List countries.",
        "description": "Only active, approved countries. Paginated; scope `geography:read`.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional text matched against the Arabic name, English name and ISO code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of countries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCountryDtoPublicPage"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/coverage": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "Does the company deliver to / pick up from a city?",
        "description": "Delivery is true when the city is in an active pricing zone (or its country in an international zone) or\r\ncovered by an active branch with a delivery role; pickup when an active branch covers it with a pickup\r\nrole. Scope `geography:read`.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Optional country (id, ISO code or name); narrows an ambiguous city name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Required city: id, code or name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Coverage of the city.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCityCoverageDto"
                }
              }
            }
          },
          "400": {
            "description": "`city` is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "Country or city could not be resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/coverage/cities": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "List the cities the company covers.",
        "description": "Active approved cities with delivery and pickup flags. Paginated; scope `geography:read`.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Optional country filter (id, ISO code or name).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional text matched against names and city code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of covered cities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCoveredCityDtoPublicPage"
                }
              }
            }
          },
          "422": {
            "description": "The country could not be resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/districts": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "List the districts of a city.",
        "description": "Active approved districts plus your company's own pending districts (`pending: true`). Paginated;\r\nscope `geography:read`.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Optional country (id, ISO code or name); narrows an ambiguous city name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Required city: id, code or name in Arabic or English.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Optional text matched against the Arabic name, English name and district code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of districts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDistrictDtoPublicPage"
                }
              }
            }
          },
          "400": {
            "description": "`city` is missing (`validation_failed`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "Country or city could not be resolved (`geo_*` codes with candidates).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/geography/resolve": {
      "get": {
        "tags": [
          "Geography"
        ],
        "summary": "Validate a location by names (or ids/codes) before creating a shipment.",
        "description": "Returns the resolved ids and names. Nothing is ever created. When a level cannot be matched, the\r\nresponse is 422 with code `geo_country_not_found`, `geo_city_not_found`,\r\n`geo_district_not_found`, `geo_city_ambiguous` or `geo_district_ambiguous` and\r\n`details` = `{ level, input, candidates[] }` with \"did you mean\" suggestions.\r\nAt least one parameter is required; a district requires a city. Scope `geography:read`.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Country: id, ISO code or name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "City: id, code or name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "district",
            "in": "query",
            "description": "District: id, code or name.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The resolved location.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicResolvedLocationDto"
                }
              }
            }
          },
          "400": {
            "description": "No parameter was given.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "The location could not be resolved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "List merchants.",
        "description": "Ordered by name, paginated. No banking, commission, API key or pricing fields are exposed.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Text matched against name, contact person, phone and email.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "isActive",
            "in": "query",
            "description": "Only active (true) or only inactive (false) merchants.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of merchants.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantDtoPublicPage"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Create a merchant.",
        "description": "Uses the dashboard's rules: commercial registration number and email are required, the VAT number is required\r\nunless `notVatRegistered` is true, and the primary pickup address is required (country/city/district by names,\r\nmatched strictly; nothing is created). Data that matches another merchant on the platform is refused with 409\r\n(`merchant.email_taken_format`, `merchant.same_merchant_format`) or, when it only looks similar, with 409\r\n`merchant.possible_duplicate` unless `confirmPossibleDuplicate` is true. Unlike the dashboard, no merchant login\r\nand no email are created. Retries are safe with `Idempotency-Key`.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional key (up to 128 characters, no spaces; `X-Idempotency-Key` is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header `Idempotent-Replayed: true`); the same key with a different body answers 409 `idempotency_key_reused`. Scoped to your company and credential.",
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The merchant.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantDto"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{id}": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "Get a merchant.",
        "description": "Required scope (API key) or equivalent permission (password): `merchants:read`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The merchant with its primary address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Merchants"
        ],
        "summary": "Update a merchant.",
        "description": "Changes the name and contact fields you send; everything else (registration numbers, pricing, banking) is untouched.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "The changes.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateMerchantRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateMerchantRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateMerchantRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{id}/addresses": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "List the saved pickup addresses of a merchant.",
        "description": "The primary address first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The addresses.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicMerchantAddressDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Add a saved pickup address.",
        "description": "Country, city and district are matched strictly by id, code or name (Arabic or English); nothing is created\r\n(`geo_*` errors with `details.field` = `address`). A short address is required for Saudi addresses. The first\r\naddress of a merchant is always primary.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional key (up to 128 characters, no spaces; `X-Idempotency-Key` is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header `Idempotent-Replayed: true`); the same key with a different body answers 409 `idempotency_key_reused`. Scoped to your company and credential.",
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The address.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantAddressRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantAddressRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateMerchantAddressRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantAddressDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{id}/addresses/{addressId}": {
      "put": {
        "tags": [
          "Merchants"
        ],
        "summary": "Replace a saved pickup address.",
        "description": "The body replaces the whole address (same fields as when adding). The primary flag is unchanged; use the `primary` route to change it.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "addressId",
            "in": "path",
            "description": "Address id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "The address.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicMerchantAddressInput"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicMerchantAddressInput"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicMerchantAddressInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantAddressDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `merchant.address_not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Merchants"
        ],
        "summary": "Delete a saved address.",
        "description": "The only address of a merchant cannot be deleted. When the primary one is deleted, the oldest remaining becomes primary.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "addressId",
            "in": "path",
            "description": "Address id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `merchant.address_not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{id}/addresses/{addressId}/primary": {
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Make an address the primary one.",
        "description": "The primary address is the default pickup of the merchant's shipments and the destination of its returns.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "addressId",
            "in": "path",
            "description": "Address id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The address, now primary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicMerchantAddressDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `merchant.address_not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{merchantId}/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List the webhook subscriptions of a merchant.",
        "description": "Required scope (API key) or equivalent permission (password): `webhooks:manage`.",
        "parameters": [
          {
            "name": "merchantId",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The subscriptions (without secrets).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicWebhookDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Create a webhook subscription.",
        "description": "The response contains the signing `secret`. It is shown only now; store it. Use it to verify the signature of\r\nevery delivery (see the description of this section).",
        "parameters": [
          {
            "name": "merchantId",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "description": "The subscription.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateWebhookRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateWebhookRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateWebhookRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The subscription, including its secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicWebhookCreatedDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{merchantId}/webhooks/{id}": {
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete a webhook subscription.",
        "description": "Required scope (API key) or equivalent permission (password): `webhooks:manage`.",
        "parameters": [
          {
            "name": "merchantId",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "Subscription id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted. Past delivery logs are kept."
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `webhook.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{merchantId}/webhooks/{id}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Rotate the signing secret.",
        "description": "The new secret is returned once and the old one stops working immediately.",
        "parameters": [
          {
            "name": "merchantId",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "Subscription id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The new secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicWebhookSecretDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `webhook.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/merchants/{merchantId}/webhooks/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Send a test event.",
        "description": "Queues a signed `ping` delivery (`{ \"event\": \"ping\", \"occurredAt\": ..., \"data\": { \"message\": ..., \"subscriptionId\": ... } }`)\r\nto the subscription's URL, exactly like a real event. Only active subscriptions can be tested.",
        "parameters": [
          {
            "name": "merchantId",
            "in": "path",
            "description": "Merchant id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "id",
            "in": "path",
            "description": "Subscription id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ping was queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicWebhookTestDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `merchant.not_found` or `webhook.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/pricing/quote": {
      "post": {
        "tags": [
          "Pricing"
        ],
        "summary": "Quote a shipment price.",
        "description": "Prices exactly like shipment creation (rate card of the merchant, zone of the destination, handling surcharges,\r\nCOD fee) and applies the company's coverage, but creates nothing: no shipment, no tracking number, no quota is\r\nused. `total` equals the shipping fee the created shipment will carry. Without `merchant` the company's default\r\npricing applies.\r\n            \r\nA destination (or pickup) outside the company's coverage is not an error: the answer is 200 with\r\n`deliverable: false` and `reason` set to `destination_not_covered`, `pickup_not_covered` or\r\n`rate_card_not_found`. Locations that do not exist answer 422 with the `geo_*` codes and `details.field`\r\n= `pickup` or `recipient`.",
        "requestBody": {
          "description": "The shipment to price.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicQuoteRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicQuoteRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicQuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuoteDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "The merchant was not found (`merchant.not_found`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "summary": "Create a shipment.",
        "description": "Books a shipment through the same engine as the dashboard: coverage, quota, rate-card pricing, estimated\r\ndelivery date, tracking number, and the `shipment.created` webhook event are all identical.\r\nThe fee is computed from the rate card; it cannot be sent.\r\n            \r\n**Sender.** `sender.type = \"merchant\"` takes `sender.merchant` (an id, or the exact account name; ambiguous\r\nnames answer 422 `merchant.ambiguous` with `details.candidates`). When `pickup` is omitted the merchant's\r\nprimary saved address is the pickup. `sender.type = \"custom\"` books a one-off sender on the company's shared\r\nwalk-in account and requires `sender.name`, `sender.phone` and `pickup`. A merchant login always sends as its\r\nown merchant and cannot use `custom`.\r\n            \r\n**Places.** `country`, `city` and `district` of `pickup` and `recipient` accept an id, a code or a name in\r\nArabic or English. They are matched strictly and nothing is ever created: failures answer 422 with\r\n`geo_country_not_found`, `geo_city_not_found`, `geo_district_not_found`, `geo_city_ambiguous` or\r\n`geo_district_ambiguous`; `details.field` is `pickup` or `recipient` and `details.candidates` lists suggestions.\r\nFor addresses in Saudi Arabia `shortAddress` (4 letters + 4 digits) is required.\r\n            \r\n**Pickup branch.** Chosen from the pickup district's branch coverage unless `pickup.branch` names one.\r\n            \r\n**Retries.** Send `Idempotency-Key` to make a retry safe.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional key (up to 128 characters, no spaces; `X-Idempotency-Key` is accepted too) that makes a retry safe. The same key with the same body within 24 hours returns the first response (header `Idempotent-Replayed: true`); the same key with a different body answers 409 `idempotency_key_reused`. Scoped to your company and credential.",
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The shipment.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateShipmentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateShipmentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCreateShipmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicShipmentDto"
                }
              }
            }
          },
          "409": {
            "description": "The Idempotency-Key was used with a different body (`idempotency_key_reused`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "Scope missing, or a merchant login named another merchant or a custom sender.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "A business rule or a location could not be satisfied (codes such as `geo_city_not_found`, `shipment.cannot_cancel`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Merchant or branch not found (`merchant.not_found`, `branch.not_found`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "List shipments.",
        "description": "Newest first, paginated. All filters are optional and combine with AND.\r\n`city` filters by destination city (id, code or name; an unknown city answers 422 `geo_city_not_found`).\r\n`search` matches the tracking number, reference, recipient name and phone, and sender name.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Items per page, 1 to 100 (larger values are clamped to 100).",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 25
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "One status or several separated by commas, as keys (`delivered,outForDelivery`) or numeric codes. See `GET /shipments/statuses`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "merchant",
            "in": "query",
            "description": "Merchant id or exact account name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reference",
            "in": "query",
            "description": "Your order reference (exact match, ignoring case).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "trackingNumber",
            "in": "query",
            "description": "Exact tracking number.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipientPhone",
            "in": "query",
            "description": "Part of the recipient's phone.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "description": "Destination city: id, code or name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "createdFrom",
            "in": "query",
            "description": "Created at or after this instant (ISO 8601, e.g. `2026-01-01T00:00:00Z`).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "createdTo",
            "in": "query",
            "description": "Created at or before this instant (ISO 8601).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Free text.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of shipments.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicShipmentSummaryDtoPublicPage"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments/statuses": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "List shipment statuses.",
        "description": "The catalog of statuses with their keys, codes, Arabic and English names and whether they are final. Use `key`\r\nto map statuses in your system; `status` of a shipment is one of these keys.",
        "responses": {
          "200": {
            "description": "All statuses in code order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicStatusDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments/{trackingNumber}": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Get a shipment.",
        "description": "Required scope (API key) or equivalent permission (password): `shipments:read`.",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "Tracking number.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicShipmentDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `shipment.not_found` (also when the shipment belongs to someone else).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Shipments"
        ],
        "summary": "Update a shipment.",
        "description": "Changes the recipient (name, phones, address by names, coordinates), the order reference, COD amount, who pays\r\nthe freight and the parcel (weight, dimensions, pieces, declared value). Only the fields you send change. The\r\nfee is recalculated when something that affects it changes. `reason` is required and goes to the shipment's\r\naudit trail. Allowed until the shipment reaches a final status; once it is out for delivery only contact\r\ndetails, address and COD can change (`shipment.field_locked_out_for_delivery`).\r\nNot editable through the API: sender, pickup address, service type and tier, handling flags. Merchant logins\r\ncannot edit shipments.",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "Tracking number.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The changes.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateShipmentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateShipmentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicUpdateShipmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicShipmentDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `shipment.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "Not editable in this state, no change, or an unresolved location.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments/{trackingNumber}/cancel": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "summary": "Cancel a shipment.",
        "description": "Possible while the shipment is a draft, created or scheduled for pickup; later it answers 422\r\n`shipment.cannot_cancel`. A pending return created with an exchange is cancelled with it. Merchant logins\r\ncannot cancel through the API.",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "Tracking number.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "The reason.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCancelShipmentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCancelShipmentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PublicCancelShipmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancelled shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicShipmentDto"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid (code `validation_failed`, `details.errors` lists every field).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `shipment.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "422": {
            "description": "Code `shipment.cannot_cancel` or another state-machine code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments/{trackingNumber}/label": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Print the shipping label.",
        "description": "The label (air waybill, 100x150 mm) as a PDF, with the company's branding.",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "Tracking number.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The PDF file.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `shipment.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/shipments/{trackingNumber}/tracking": {
      "get": {
        "tags": [
          "Shipments"
        ],
        "summary": "Track a shipment.",
        "description": "The status timeline (oldest first) with Arabic and English labels, the current status and the estimated\r\ndelivery date. It carries no internal user names; `note` is present only for failed attempts, postponements,\r\ncancellation, returns, loss and damage.",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "description": "Tracking number.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The tracking timeline.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTrackingDto"
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "404": {
            "description": "Code `shipment.not_found`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    },
    "/api/public/v1/webhooks/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List webhook event types.",
        "description": "Every event type you can subscribe to, with a description and an example payload. Use `shipment.*` to receive all\r\nshipment events or `*` for everything.",
        "responses": {
          "200": {
            "description": "The event catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/PublicWebhookEventDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is missing or invalid (code `unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required scope, or the public API is disabled (codes `forbidden`, `channel_disabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (code `rate_limited`); wait for the `Retry-After` header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyAuth": [],
            "apiSecretAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "PublicAddressDto": {
        "type": "object",
        "properties": {
          "country": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "city": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "district": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark.",
            "nullable": true
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address.",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "description": "Latitude.",
            "format": "double",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "description": "Longitude.",
            "format": "double",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A resolved address."
      },
      "PublicApiError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable code, e.g. `shipment.not_found` or `validation_failed`.",
            "nullable": true
          },
          "message": {
            "type": "string",
            "description": "Human readable message. Arabic by default; English when Accept-Language prefers English.",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code, repeated in the body.",
            "format": "int32"
          },
          "details": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            },
            "description": "Extra data: `errors` (field to messages) for validation_failed; `level`, `input` and\r\n`candidates` for geo errors; `messageAr` when the message is English.",
            "nullable": true
          },
          "traceId": {
            "type": "string",
            "description": "Correlation id of the request, quote it when contacting support.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Error envelope returned for every non-2xx response of the public API (`/api/public/v1`)."
      },
      "PublicApiKeyDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "API key id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Label given to the key.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The API key behind a key-authenticated call."
      },
      "PublicBranchDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Branch id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Branch name.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "description": "Branch code.",
            "nullable": true
          },
          "city": {
            "type": "string",
            "description": "City name as entered on the branch.",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "description": "Branch phone, when set.",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "description": "Latitude, when set.",
            "format": "double",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "description": "Longitude, when set.",
            "format": "double",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether the branch is active."
          }
        },
        "additionalProperties": false,
        "description": "Public-safe view of a branch (no manager, capacity, counters or other internal fields)."
      },
      "PublicBranchDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicBranchDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicBranchRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Branch id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Branch name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A branch reference."
      },
      "PublicCancelShipmentRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Why the shipment is cancelled (kept in the shipment history). Up to 500 characters.",
            "nullable": true,
            "example": "Customer cancelled the order"
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /shipments/{trackingNumber}/cancel`."
      },
      "PublicCityCoverageDto": {
        "type": "object",
        "properties": {
          "city": {
            "$ref": "#/components/schemas/PublicGeoNodeDto"
          },
          "delivery": {
            "type": "boolean",
            "description": "True when the company delivers to the city."
          },
          "pickup": {
            "type": "boolean",
            "description": "True when the company picks up from the city."
          }
        },
        "additionalProperties": false,
        "description": "Whether the company delivers to / picks up from a city."
      },
      "PublicCityDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "City id.",
            "format": "uuid"
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "description": "City code (unique within its country), when defined.",
            "nullable": true
          },
          "countryId": {
            "type": "string",
            "description": "Id of the country the city belongs to.",
            "format": "uuid"
          },
          "pending": {
            "type": "boolean",
            "description": "True for a city created by your company that the platform has not approved yet."
          }
        },
        "additionalProperties": false,
        "description": "City item of the public geography endpoints."
      },
      "PublicCityDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCityDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicColdChainRange": {
        "enum": [
          "frozen",
          "chilled",
          "ambient"
        ],
        "type": "string",
        "description": "Temperature range of cold-chain goods."
      },
      "PublicCompanyDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Company id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Company name.",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "description": "Company slug.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Company identity shown by the public `auth/me` endpoint."
      },
      "PublicCountryDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Country id.",
            "format": "uuid"
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 code.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Country item of the public geography endpoints."
      },
      "PublicCountryDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCountryDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicCoveredCityDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "City id.",
            "format": "uuid"
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "description": "City code, when defined.",
            "nullable": true
          },
          "countryId": {
            "type": "string",
            "description": "Country id.",
            "format": "uuid"
          },
          "delivery": {
            "type": "boolean",
            "description": "True when the company delivers to the city."
          },
          "pickup": {
            "type": "boolean",
            "description": "True when the company picks up from the city."
          }
        },
        "additionalProperties": false,
        "description": "A city the company covers."
      },
      "PublicCoveredCityDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicCoveredCityDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicCreateMerchantAddressRequest": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Short label of the address, for example \"Main warehouse\". Required, up to 100 characters.",
            "nullable": true,
            "example": "Main warehouse"
          },
          "contactName": {
            "type": "string",
            "description": "Person to contact at this address (defaults to the merchant name).",
            "nullable": true,
            "example": "Omar Hassan"
          },
          "contactPhone": {
            "type": "string",
            "description": "Phone at this address. Required.",
            "nullable": true,
            "example": "0501234567"
          },
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Riyadh"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Required. Unknown districts are never created: you get `geo_district_not_found`.",
            "nullable": true,
            "example": "Al Olaya"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark. Required, up to 500 characters.",
            "nullable": true,
            "example": "King Fahd Road, Warehouse 4"
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.",
            "nullable": true,
            "example": "RNBA6769"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude (optional).",
            "format": "double",
            "nullable": true,
            "example": 24.7136
          },
          "longitude": {
            "type": "number",
            "description": "Longitude (optional).",
            "format": "double",
            "nullable": true,
            "example": 46.6753
          },
          "makePrimary": {
            "type": "boolean",
            "description": "Make this the primary address (the first address of a merchant is always primary).",
            "example": false
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /merchants/{id}/addresses`."
      },
      "PublicCreateMerchantRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Account (store) name. Not unique, but a name that matches another merchant on the platform needs `confirmPossibleDuplicate`. Required, up to 200 characters.",
            "nullable": true,
            "example": "Noor Electronics"
          },
          "contactName": {
            "type": "string",
            "description": "Contact person.",
            "nullable": true,
            "example": "Omar Hassan"
          },
          "contactPhone": {
            "type": "string",
            "description": "Contact phone.",
            "nullable": true,
            "example": "0501234567"
          },
          "contactEmail": {
            "type": "string",
            "description": "Contact email. Required; unique across the platform.",
            "nullable": true,
            "example": "orders@noor-electronics.example"
          },
          "commercialRegNo": {
            "type": "string",
            "description": "Commercial registration number (or freelance licence number). Required.",
            "nullable": true,
            "example": "1010123456"
          },
          "taxId": {
            "type": "string",
            "description": "VAT number. Required unless `notVatRegistered` is true.",
            "nullable": true,
            "example": "300123456700003"
          },
          "notVatRegistered": {
            "type": "boolean",
            "description": "True when the merchant is not registered for VAT.",
            "example": false
          },
          "address": {
            "$ref": "#/components/schemas/PublicMerchantAddressInput"
          },
          "confirmPossibleDuplicate": {
            "type": "boolean",
            "description": "Confirm that this is a different store even though its registration number, VAT number or name matches another\r\nmerchant on the platform. Without it such a request is refused with 409 `merchant.possible_duplicate`.",
            "example": false
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /merchants`."
      },
      "PublicCreateShipmentRequest": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "Your own order reference (shown on the label and searchable). Up to 100 characters.",
            "nullable": true,
            "example": "ORD-1001"
          },
          "serviceType": {
            "$ref": "#/components/schemas/PublicServiceType"
          },
          "serviceTier": {
            "$ref": "#/components/schemas/PublicServiceTier"
          },
          "sender": {
            "$ref": "#/components/schemas/PublicSenderInput"
          },
          "pickup": {
            "$ref": "#/components/schemas/PublicPickupInput"
          },
          "recipient": {
            "$ref": "#/components/schemas/PublicRecipientInput"
          },
          "parcel": {
            "$ref": "#/components/schemas/PublicParcelInput"
          },
          "payment": {
            "$ref": "#/components/schemas/PublicPaymentInput"
          },
          "delivery": {
            "$ref": "#/components/schemas/PublicDeliveryOptionsInput"
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /shipments`. Prices are computed from the company's rate card; never send a fee."
      },
      "PublicCreateWebhookRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "HTTPS URL that receives the events. Private and local addresses are refused.",
            "nullable": true,
            "example": "https://shop.example.com/hooks/lastmile"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Event types to receive, from `GET /webhooks/events`. Wildcards: `shipment.*` (all shipment events) or\r\n`*` (everything). At least one.",
            "nullable": true,
            "example": [
              "shipment.created",
              "shipment.delivered"
            ]
          },
          "description": {
            "type": "string",
            "description": "Free text to recognise the subscription (optional, up to 200 characters).",
            "nullable": true,
            "example": "Order system"
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /merchants/{merchantId}/webhooks`."
      },
      "PublicDeliveryOptionsDto": {
        "type": "object",
        "properties": {
          "allowOpenPackage": {
            "type": "boolean",
            "description": "The recipient may open the package."
          },
          "requireSignature": {
            "type": "boolean",
            "description": "Signature required."
          },
          "requireIdVerification": {
            "type": "boolean",
            "description": "ID check required."
          },
          "allowNeighborDelivery": {
            "type": "boolean",
            "description": "Neighbour delivery allowed."
          }
        },
        "additionalProperties": false,
        "description": "Handover rules."
      },
      "PublicDeliveryOptionsInput": {
        "type": "object",
        "properties": {
          "allowOpenPackage": {
            "type": "boolean",
            "description": "The recipient may open the package before accepting. Default false.",
            "nullable": true,
            "example": false
          },
          "requireSignature": {
            "type": "boolean",
            "description": "A signature is required on delivery. Default true.",
            "nullable": true,
            "example": true
          },
          "requireIdVerification": {
            "type": "boolean",
            "description": "The courier must verify the recipient's ID. Default false.",
            "nullable": true,
            "example": false
          },
          "allowNeighborDelivery": {
            "type": "boolean",
            "description": "A neighbour may accept the parcel. Default true.",
            "nullable": true,
            "example": true
          }
        },
        "additionalProperties": false,
        "description": "Handover rules at the recipient's door. Omitted values use the system defaults shown."
      },
      "PublicDistrictDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "District id.",
            "format": "uuid"
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "description": "District code, when defined.",
            "nullable": true
          },
          "cityId": {
            "type": "string",
            "description": "Id of the city the district belongs to.",
            "format": "uuid"
          },
          "pending": {
            "type": "boolean",
            "description": "True for a district created by your company that the platform has not approved yet."
          }
        },
        "additionalProperties": false,
        "description": "District item of the public geography endpoints."
      },
      "PublicDistrictDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicDistrictDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicGeoNodeDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Resolved id.",
            "format": "uuid"
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A resolved geography node (id and both names)."
      },
      "PublicLoginRequest": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string",
            "description": "Username or e-mail address.",
            "nullable": true
          },
          "password": {
            "type": "string",
            "description": "Password.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Credentials of a user of the shipping company."
      },
      "PublicMeResponse": {
        "type": "object",
        "properties": {
          "authMethod": {
            "type": "string",
            "description": "`password` or `api_key`.",
            "nullable": true
          },
          "company": {
            "$ref": "#/components/schemas/PublicCompanyDto"
          },
          "user": {
            "$ref": "#/components/schemas/PublicUserDto"
          },
          "apiKey": {
            "$ref": "#/components/schemas/PublicApiKeyDto"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "API scopes granted (for password callers: the scopes the user's permissions cover).",
            "nullable": true
          },
          "permissions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Permission codes held by the caller.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Identity and permissions of the current caller."
      },
      "PublicMerchantAddressDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Address id.",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "description": "Short label.",
            "nullable": true
          },
          "contactName": {
            "type": "string",
            "description": "Contact person at the address.",
            "nullable": true
          },
          "contactPhone": {
            "type": "string",
            "description": "Phone at the address.",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "city": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "district": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark.",
            "nullable": true
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address.",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "description": "Latitude.",
            "format": "double",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "description": "Longitude.",
            "format": "double",
            "nullable": true
          },
          "isPrimary": {
            "type": "boolean",
            "description": "True for the primary address (used by default as the pickup of the merchant's shipments)."
          }
        },
        "additionalProperties": false,
        "description": "A saved pickup address of a merchant."
      },
      "PublicMerchantAddressInput": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Short label of the address, for example \"Main warehouse\". Required, up to 100 characters.",
            "nullable": true,
            "example": "Main warehouse"
          },
          "contactName": {
            "type": "string",
            "description": "Person to contact at this address (defaults to the merchant name).",
            "nullable": true,
            "example": "Omar Hassan"
          },
          "contactPhone": {
            "type": "string",
            "description": "Phone at this address. Required.",
            "nullable": true,
            "example": "0501234567"
          },
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Riyadh"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Required. Unknown districts are never created: you get `geo_district_not_found`.",
            "nullable": true,
            "example": "Al Olaya"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark. Required, up to 500 characters.",
            "nullable": true,
            "example": "King Fahd Road, Warehouse 4"
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address (4 letters and 4 digits). Required for addresses in Saudi Arabia.",
            "nullable": true,
            "example": "RNBA6769"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude (optional).",
            "format": "double",
            "nullable": true,
            "example": 24.7136
          },
          "longitude": {
            "type": "number",
            "description": "Longitude (optional).",
            "format": "double",
            "nullable": true,
            "example": 46.6753
          }
        },
        "additionalProperties": false,
        "description": "A saved pickup address of a merchant, given by names. Country, city and district each accept an id, a code or a name in Arabic or English."
      },
      "PublicMerchantDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Merchant id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Account name.",
            "nullable": true
          },
          "contactName": {
            "type": "string",
            "description": "Contact person.",
            "nullable": true
          },
          "contactPhone": {
            "type": "string",
            "description": "Contact phone.",
            "nullable": true
          },
          "contactEmail": {
            "type": "string",
            "description": "Contact email.",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether the merchant can book shipments."
          },
          "createdAt": {
            "type": "string",
            "description": "Creation time (UTC).",
            "format": "date-time"
          },
          "primaryAddress": {
            "$ref": "#/components/schemas/PublicMerchantAddressDto"
          }
        },
        "additionalProperties": false,
        "description": "A merchant of the company (no banking, commission, API keys or pricing details)."
      },
      "PublicMerchantDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicMerchantDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicMerchantRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Merchant id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Merchant account name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A merchant reference."
      },
      "PublicNamedRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Catalog id, or null for legacy shipments that only stored a name.",
            "format": "uuid",
            "nullable": true
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A catalog entry shown in both languages."
      },
      "PublicOrderSource": {
        "enum": [
          "dashboard",
          "excelImport",
          "merchantPortal",
          "api",
          "integration",
          "inviteLink",
          "publicWebsite",
          "phone",
          "whatsApp",
          "socialMedia",
          "walkIn",
          "other"
        ],
        "type": "string",
        "description": "How the order reached the system."
      },
      "PublicParcelDto": {
        "type": "object",
        "properties": {
          "weightKg": {
            "type": "number",
            "description": "Actual weight.",
            "format": "double"
          },
          "lengthCm": {
            "type": "number",
            "description": "Length.",
            "format": "double"
          },
          "widthCm": {
            "type": "number",
            "description": "Width.",
            "format": "double"
          },
          "heightCm": {
            "type": "number",
            "description": "Height.",
            "format": "double"
          },
          "chargeableWeightKg": {
            "type": "number",
            "description": "Weight used for pricing: the larger of actual and volumetric weight.",
            "format": "double"
          },
          "pieces": {
            "type": "integer",
            "description": "Number of pieces.",
            "format": "int32"
          },
          "description": {
            "type": "string",
            "description": "What is inside.",
            "nullable": true
          },
          "declaredValue": {
            "type": "number",
            "description": "Declared value.",
            "format": "double"
          },
          "fragile": {
            "type": "boolean",
            "description": "Fragile."
          },
          "requiresColdChain": {
            "type": "boolean",
            "description": "Needs cold chain."
          },
          "coldChainRange": {
            "$ref": "#/components/schemas/PublicColdChainRange"
          },
          "flammable": {
            "type": "boolean",
            "description": "Flammable."
          },
          "hazardous": {
            "type": "boolean",
            "description": "Hazardous."
          },
          "containsAlcohol": {
            "type": "boolean",
            "description": "Contains alcohol."
          },
          "liquid": {
            "type": "boolean",
            "description": "Liquid."
          },
          "highValue": {
            "type": "boolean",
            "description": "High value."
          }
        },
        "additionalProperties": false,
        "description": "Parcel data of a shipment."
      },
      "PublicParcelInput": {
        "type": "object",
        "properties": {
          "weightKg": {
            "type": "number",
            "description": "Actual weight in kilograms, greater than 0.",
            "format": "double",
            "example": 1.5
          },
          "lengthCm": {
            "type": "number",
            "description": "Length in centimetres, greater than 0.",
            "format": "double",
            "example": 20
          },
          "widthCm": {
            "type": "number",
            "description": "Width in centimetres, greater than 0.",
            "format": "double",
            "example": 15
          },
          "heightCm": {
            "type": "number",
            "description": "Height in centimetres, greater than 0.",
            "format": "double",
            "example": 10
          },
          "pieces": {
            "type": "integer",
            "description": "Number of pieces (default 1).",
            "format": "int32",
            "nullable": true,
            "example": 1
          },
          "description": {
            "type": "string",
            "description": "What is inside (optional, shown on the label).",
            "nullable": true,
            "example": "Mobile phone case"
          },
          "declaredValue": {
            "type": "number",
            "description": "Declared value of the goods (default 0).",
            "format": "double",
            "nullable": true,
            "example": 250
          },
          "fragile": {
            "type": "boolean",
            "description": "Fragile goods.",
            "example": false
          },
          "requiresColdChain": {
            "type": "boolean",
            "description": "Needs cold chain; then `coldChainRange` is required.",
            "example": false
          },
          "coldChainRange": {
            "$ref": "#/components/schemas/PublicColdChainRange"
          },
          "flammable": {
            "type": "boolean",
            "description": "Flammable goods.",
            "example": false
          },
          "hazardous": {
            "type": "boolean",
            "description": "Hazardous goods.",
            "example": false
          },
          "containsAlcohol": {
            "type": "boolean",
            "description": "Contains alcohol.",
            "example": false
          },
          "liquid": {
            "type": "boolean",
            "description": "Liquid goods.",
            "example": false
          },
          "highValue": {
            "type": "boolean",
            "description": "High-value goods.",
            "example": false
          }
        },
        "additionalProperties": false,
        "description": "The parcel. Weight and dimensions describe the whole shipment."
      },
      "PublicPaymentDto": {
        "type": "object",
        "properties": {
          "codAmount": {
            "type": "number",
            "description": "Cash to collect from the recipient.",
            "format": "double"
          },
          "shippingFee": {
            "type": "number",
            "description": "Shipping fee computed from the rate card.",
            "format": "double"
          },
          "freightOnDelivery": {
            "type": "boolean",
            "description": "True when the recipient pays the fee."
          }
        },
        "additionalProperties": false,
        "description": "Payment data of a shipment."
      },
      "PublicPaymentInput": {
        "type": "object",
        "properties": {
          "codAmount": {
            "type": "number",
            "description": "Amount the courier collects from the recipient (cash on delivery). Default 0. Must be 0 for `return`.",
            "format": "double",
            "nullable": true,
            "example": 199.5
          },
          "freightOnDelivery": {
            "type": "boolean",
            "description": "True when the recipient pays the shipping fee on delivery.",
            "nullable": true,
            "example": false
          }
        },
        "additionalProperties": false,
        "description": "Cash on delivery and freight payment."
      },
      "PublicPickupInput": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Riyadh"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Required. Unknown districts are never created: you get `geo_district_not_found`.",
            "nullable": true,
            "example": "Al Olaya"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark. Required, up to 500 characters.",
            "nullable": true,
            "example": "King Fahd Road, Building 12, Floor 3"
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.",
            "nullable": true,
            "example": "RNBA6769"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude, -90 to 90 (optional).",
            "format": "double",
            "nullable": true,
            "example": 24.7136
          },
          "longitude": {
            "type": "number",
            "description": "Longitude, -180 to 180 (optional).",
            "format": "double",
            "nullable": true,
            "example": 46.6753
          },
          "branch": {
            "type": "string",
            "description": "Branch that handles the pickup: branch id, code or name. Optional; by default the branch covering the pickup\r\ndistrict is chosen automatically (`branch_coverage.no_coverage_for_city` when none covers it).",
            "nullable": true,
            "example": "RUH-01"
          }
        },
        "additionalProperties": false,
        "description": "The pickup address."
      },
      "PublicPieceDto": {
        "type": "object",
        "properties": {
          "barcode": {
            "type": "string",
            "description": "Piece barcode (the tracking number followed by `-P1`, `-P2`...).",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "One piece of a shipment."
      },
      "PublicQuoteDto": {
        "type": "object",
        "properties": {
          "deliverable": {
            "type": "boolean",
            "description": "False when the company does not cover the pickup or the destination (see `reason`)."
          },
          "reason": {
            "type": "string",
            "description": "`destination_not_covered`, `pickup_not_covered` or `rate_card_not_found` when not deliverable.",
            "nullable": true
          },
          "shippingFee": {
            "type": "number",
            "description": "Shipping fee without the COD fee (weight price plus handling surcharges).",
            "format": "double",
            "nullable": true
          },
          "codFee": {
            "type": "number",
            "description": "Fee charged for collecting cash on delivery.",
            "format": "double",
            "nullable": true
          },
          "total": {
            "type": "number",
            "description": "What the shipment will be charged: `shippingFee + codFee`. Equals `payment.shippingFee` of the created shipment.",
            "format": "double",
            "nullable": true
          },
          "chargeableWeightKg": {
            "type": "number",
            "description": "The larger of actual and volumetric weight.",
            "format": "double",
            "nullable": true
          },
          "zone": {
            "$ref": "#/components/schemas/PublicZoneRef"
          },
          "breakdown": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicQuoteLineDto"
            },
            "description": "Price lines; they add up to `total`.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A price quote. Nothing is created or consumed: no tracking number, no quota."
      },
      "PublicQuoteLineDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "`baseShipping`, `handling`, `codFee` or `reverseAdjustment`.",
            "nullable": true
          },
          "label": {
            "type": "string",
            "description": "Readable label (the handling flag name for `handling` lines).",
            "nullable": true
          },
          "amount": {
            "type": "number",
            "description": "Amount of the line.",
            "format": "double"
          }
        },
        "additionalProperties": false,
        "description": "One line of a price."
      },
      "PublicQuoteLocationInput": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Jeddah"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Optional for a quote; when sent it must exist.",
            "nullable": true,
            "example": "Al Rawdah"
          }
        },
        "additionalProperties": false,
        "description": "A place given by names for a quote. Each level accepts an id, a code or a name in Arabic or English."
      },
      "PublicQuoteRequest": {
        "type": "object",
        "properties": {
          "merchant": {
            "type": "string",
            "description": "Merchant id or exact account name; the merchant's own rate card applies. Optional: without it the company's\r\ndefault pricing is used. A merchant login always quotes for itself. Required for `return` quotes.",
            "nullable": true,
            "example": "Noor Electronics"
          },
          "pickup": {
            "$ref": "#/components/schemas/PublicQuoteLocationInput"
          },
          "recipient": {
            "$ref": "#/components/schemas/PublicQuoteLocationInput"
          },
          "parcel": {
            "$ref": "#/components/schemas/PublicParcelInput"
          },
          "payment": {
            "$ref": "#/components/schemas/PublicPaymentInput"
          },
          "serviceType": {
            "$ref": "#/components/schemas/PublicServiceType"
          },
          "serviceTier": {
            "$ref": "#/components/schemas/PublicServiceTier"
          }
        },
        "additionalProperties": false,
        "description": "Body of `POST /pricing/quote`."
      },
      "PublicRecipientDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Recipient name.",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "description": "Recipient phone.",
            "nullable": true
          },
          "secondaryPhone": {
            "type": "string",
            "description": "Second phone.",
            "nullable": true
          },
          "country": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "city": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "district": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark.",
            "nullable": true
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address.",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "description": "Latitude.",
            "format": "double",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "description": "Longitude.",
            "format": "double",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The recipient."
      },
      "PublicRecipientInput": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Riyadh"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Required. Unknown districts are never created: you get `geo_district_not_found`.",
            "nullable": true,
            "example": "Al Olaya"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark. Required, up to 500 characters.",
            "nullable": true,
            "example": "King Fahd Road, Building 12, Floor 3"
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.",
            "nullable": true,
            "example": "RNBA6769"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude, -90 to 90 (optional).",
            "format": "double",
            "nullable": true,
            "example": 24.7136
          },
          "longitude": {
            "type": "number",
            "description": "Longitude, -180 to 180 (optional).",
            "format": "double",
            "nullable": true,
            "example": 46.6753
          },
          "name": {
            "type": "string",
            "description": "Recipient name. Required, up to 200 characters.",
            "nullable": true,
            "example": "Khaled Alotaibi"
          },
          "phone": {
            "type": "string",
            "description": "Recipient phone. Required; digits, spaces, +, - and brackets.",
            "nullable": true,
            "example": "0555123456"
          },
          "secondaryPhone": {
            "type": "string",
            "description": "Second phone (optional).",
            "nullable": true,
            "example": "0555987654"
          }
        },
        "additionalProperties": false,
        "description": "The recipient and the delivery address."
      },
      "PublicRefreshRequest": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string",
            "description": "The refresh token returned by login or by a previous refresh (single use).",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Request to exchange a refresh token for a new token pair."
      },
      "PublicResolvedLocationDto": {
        "type": "object",
        "properties": {
          "country": {
            "$ref": "#/components/schemas/PublicGeoNodeDto"
          },
          "city": {
            "$ref": "#/components/schemas/PublicGeoNodeDto"
          },
          "district": {
            "$ref": "#/components/schemas/PublicGeoNodeDto"
          }
        },
        "additionalProperties": false,
        "description": "Result of validating a location by names."
      },
      "PublicSenderDto": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/PublicSenderType"
          },
          "name": {
            "type": "string",
            "description": "Sender name.",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "description": "Sender phone.",
            "nullable": true
          },
          "email": {
            "type": "string",
            "description": "Sender email.",
            "nullable": true
          },
          "merchant": {
            "$ref": "#/components/schemas/PublicMerchantRef"
          }
        },
        "additionalProperties": false,
        "description": "The sender of a shipment."
      },
      "PublicSenderInput": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/PublicSenderType"
          },
          "merchant": {
            "type": "string",
            "description": "For `merchant`: the merchant id, or the exact account name (compared ignoring case and Arabic letter variants).",
            "nullable": true,
            "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          },
          "name": {
            "type": "string",
            "description": "For `custom`: sender name (required).",
            "nullable": true,
            "example": "Sara Ahmed"
          },
          "phone": {
            "type": "string",
            "description": "For `custom`: sender phone (required).",
            "nullable": true,
            "example": "0501234567"
          },
          "email": {
            "type": "string",
            "description": "For `custom`: sender email (optional).",
            "nullable": true,
            "example": "sara@example.com"
          }
        },
        "additionalProperties": false,
        "description": "The sender of a shipment."
      },
      "PublicSenderType": {
        "enum": [
          "merchant",
          "custom"
        ],
        "type": "string",
        "description": "Who sends the shipment."
      },
      "PublicServiceTier": {
        "enum": [
          "standard",
          "express",
          "sameDay"
        ],
        "type": "string",
        "description": "Speed of the service; it drives the estimated delivery date."
      },
      "PublicServiceType": {
        "enum": [
          "delivery",
          "exchange",
          "return"
        ],
        "type": "string",
        "description": "Kind of service requested for a shipment."
      },
      "PublicShipmentDto": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string",
            "description": "Tracking number; identifies the shipment in every route.",
            "nullable": true
          },
          "reference": {
            "type": "string",
            "description": "Your order reference.",
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Status key, e.g. `created`, `outForDelivery`, `delivered`. See `GET /shipments/statuses`.",
            "nullable": true
          },
          "statusCode": {
            "type": "integer",
            "description": "Numeric status code.",
            "format": "int32"
          },
          "statusLabelAr": {
            "type": "string",
            "description": "Arabic status label.",
            "nullable": true
          },
          "statusLabelEn": {
            "type": "string",
            "description": "English status label.",
            "nullable": true
          },
          "isFinal": {
            "type": "boolean",
            "description": "True when the shipment reached a final status."
          },
          "serviceType": {
            "$ref": "#/components/schemas/PublicServiceType"
          },
          "serviceTier": {
            "$ref": "#/components/schemas/PublicServiceTier"
          },
          "source": {
            "$ref": "#/components/schemas/PublicOrderSource"
          },
          "createdAt": {
            "type": "string",
            "description": "Creation time (UTC).",
            "format": "date-time"
          },
          "estimatedDeliveryDate": {
            "type": "string",
            "description": "Estimated delivery date (yyyy-MM-dd), when known.",
            "format": "date",
            "nullable": true
          },
          "sender": {
            "$ref": "#/components/schemas/PublicSenderDto"
          },
          "pickup": {
            "$ref": "#/components/schemas/PublicAddressDto"
          },
          "recipient": {
            "$ref": "#/components/schemas/PublicRecipientDto"
          },
          "parcel": {
            "$ref": "#/components/schemas/PublicParcelDto"
          },
          "delivery": {
            "$ref": "#/components/schemas/PublicDeliveryOptionsDto"
          },
          "payment": {
            "$ref": "#/components/schemas/PublicPaymentDto"
          },
          "pieces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicPieceDto"
            },
            "description": "The pieces.",
            "nullable": true
          },
          "branch": {
            "$ref": "#/components/schemas/PublicBranchRef"
          },
          "canCancel": {
            "type": "boolean",
            "description": "True while the shipment can still be cancelled."
          },
          "isEditable": {
            "type": "boolean",
            "description": "True while the shipment can still be edited."
          }
        },
        "additionalProperties": false,
        "description": "A shipment as returned by the public API."
      },
      "PublicShipmentSummaryDto": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string",
            "description": "Tracking number.",
            "nullable": true
          },
          "reference": {
            "type": "string",
            "description": "Your order reference.",
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Status key.",
            "nullable": true
          },
          "statusLabelAr": {
            "type": "string",
            "description": "Arabic status label.",
            "nullable": true
          },
          "statusLabelEn": {
            "type": "string",
            "description": "English status label.",
            "nullable": true
          },
          "merchant": {
            "$ref": "#/components/schemas/PublicMerchantRef"
          },
          "senderName": {
            "type": "string",
            "description": "Sender name.",
            "nullable": true
          },
          "recipientName": {
            "type": "string",
            "description": "Recipient name.",
            "nullable": true
          },
          "recipientPhone": {
            "type": "string",
            "description": "Recipient phone.",
            "nullable": true
          },
          "city": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "district": {
            "$ref": "#/components/schemas/PublicNamedRef"
          },
          "codAmount": {
            "type": "number",
            "description": "Cash on delivery amount.",
            "format": "double"
          },
          "shippingFee": {
            "type": "number",
            "description": "Shipping fee.",
            "format": "double"
          },
          "createdAt": {
            "type": "string",
            "description": "Creation time (UTC).",
            "format": "date-time"
          },
          "estimatedDeliveryDate": {
            "type": "string",
            "description": "Estimated delivery date.",
            "format": "date",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A shipment row of the list endpoint."
      },
      "PublicShipmentSummaryDtoPublicPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicShipmentSummaryDto"
            },
            "description": "Items of the requested page.",
            "nullable": true
          },
          "page": {
            "type": "integer",
            "description": "Current page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "Requested page size (1 to 100, default 25).",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of items across all pages.",
            "format": "int32"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages.",
            "format": "int32",
            "readOnly": true
          }
        },
        "additionalProperties": false,
        "description": "Standard paged response of every public list endpoint."
      },
      "PublicStatusDto": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Numeric status code.",
            "format": "int32"
          },
          "key": {
            "type": "string",
            "description": "Status key used in the API.",
            "nullable": true
          },
          "nameAr": {
            "type": "string",
            "description": "Arabic name.",
            "nullable": true
          },
          "nameEn": {
            "type": "string",
            "description": "English name.",
            "nullable": true
          },
          "isFinal": {
            "type": "boolean",
            "description": "True when no further status follows (delivered, returned to sender, cancelled, lost, disposed)."
          }
        },
        "additionalProperties": false,
        "description": "A shipment status of the catalog."
      },
      "PublicTokenResponse": {
        "type": "object",
        "properties": {
          "accessToken": {
            "type": "string",
            "description": "JWT to send as `Authorization: Bearer ...`.",
            "nullable": true
          },
          "refreshToken": {
            "type": "string",
            "description": "Single-use refresh token.",
            "nullable": true
          },
          "tokenType": {
            "type": "string",
            "description": "Always `Bearer`.",
            "nullable": true
          },
          "expiresIn": {
            "type": "integer",
            "description": "Lifetime of the access token in seconds.",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Token pair returned by login and refresh."
      },
      "PublicTrackingDto": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string",
            "description": "Tracking number.",
            "nullable": true
          },
          "status": {
            "type": "string",
            "description": "Current status key.",
            "nullable": true
          },
          "statusLabelAr": {
            "type": "string",
            "description": "Arabic label of the current status.",
            "nullable": true
          },
          "statusLabelEn": {
            "type": "string",
            "description": "English label of the current status.",
            "nullable": true
          },
          "estimatedDeliveryDate": {
            "type": "string",
            "description": "Estimated delivery date.",
            "format": "date",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicTrackingEventDto"
            },
            "description": "Timeline, oldest first.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Tracking of one shipment."
      },
      "PublicTrackingEventDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status key.",
            "nullable": true
          },
          "statusLabelAr": {
            "type": "string",
            "description": "Arabic label.",
            "nullable": true
          },
          "statusLabelEn": {
            "type": "string",
            "description": "English label.",
            "nullable": true
          },
          "at": {
            "type": "string",
            "description": "When the status was set (UTC).",
            "format": "date-time"
          },
          "note": {
            "type": "string",
            "description": "Reason, only for failed attempts, postponements, cancellation, returns, loss and damage.",
            "nullable": true
          },
          "location": {
            "type": "string",
            "description": "Reserved; not populated yet.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "One step of the status timeline."
      },
      "PublicUpdateMerchantRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "New account name.",
            "nullable": true,
            "example": "Noor Electronics"
          },
          "contactName": {
            "type": "string",
            "description": "New contact person.",
            "nullable": true,
            "example": "Omar Hassan"
          },
          "contactPhone": {
            "type": "string",
            "description": "New contact phone.",
            "nullable": true,
            "example": "0501234567"
          },
          "contactEmail": {
            "type": "string",
            "description": "New contact email.",
            "nullable": true,
            "example": "orders@noor-electronics.example"
          }
        },
        "additionalProperties": false,
        "description": "Body of `PUT /merchants/{id}`. Only the fields you send change."
      },
      "PublicUpdateParcelInput": {
        "type": "object",
        "properties": {
          "weightKg": {
            "type": "number",
            "description": "Weight in kilograms.",
            "format": "double",
            "nullable": true,
            "example": 2
          },
          "lengthCm": {
            "type": "number",
            "description": "Length in centimetres.",
            "format": "double",
            "nullable": true,
            "example": 20
          },
          "widthCm": {
            "type": "number",
            "description": "Width in centimetres.",
            "format": "double",
            "nullable": true,
            "example": 15
          },
          "heightCm": {
            "type": "number",
            "description": "Height in centimetres.",
            "format": "double",
            "nullable": true,
            "example": 10
          },
          "pieces": {
            "type": "integer",
            "description": "Number of pieces.",
            "format": "int32",
            "nullable": true,
            "example": 1
          },
          "declaredValue": {
            "type": "number",
            "description": "Declared value of the goods.",
            "format": "double",
            "nullable": true,
            "example": 300
          }
        },
        "additionalProperties": false,
        "description": "Parcel fields that can change. Only the fields you send are changed."
      },
      "PublicUpdateRecipientInput": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country id, ISO code or name. Optional when the city name is unambiguous.",
            "nullable": true,
            "example": "SA"
          },
          "city": {
            "type": "string",
            "description": "City id, code or name. Required.",
            "nullable": true,
            "example": "Riyadh"
          },
          "district": {
            "type": "string",
            "description": "District id, code or name. Required. Unknown districts are never created: you get `geo_district_not_found`.",
            "nullable": true,
            "example": "Al Olaya"
          },
          "addressLine": {
            "type": "string",
            "description": "Street, building and landmark. Required, up to 500 characters.",
            "nullable": true,
            "example": "King Fahd Road, Building 12, Floor 3"
          },
          "shortAddress": {
            "type": "string",
            "description": "Saudi national short address: 4 letters and 4 digits. Required when the city is in Saudi Arabia.",
            "nullable": true,
            "example": "RNBA6769"
          },
          "latitude": {
            "type": "number",
            "description": "Latitude, -90 to 90 (optional).",
            "format": "double",
            "nullable": true,
            "example": 24.7136
          },
          "longitude": {
            "type": "number",
            "description": "Longitude, -180 to 180 (optional).",
            "format": "double",
            "nullable": true,
            "example": 46.6753
          },
          "name": {
            "type": "string",
            "description": "Recipient name.",
            "nullable": true,
            "example": "Khaled Alotaibi"
          },
          "phone": {
            "type": "string",
            "description": "Recipient phone.",
            "nullable": true,
            "example": "0555123456"
          },
          "secondaryPhone": {
            "type": "string",
            "description": "Second phone.",
            "nullable": true,
            "example": "0555987654"
          }
        },
        "additionalProperties": false,
        "description": "Recipient fields that can change. Sending any address field re-resolves the whole address (city and district are then required)."
      },
      "PublicUpdateShipmentRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Why the shipment is edited (kept in the shipment's audit trail). Required, up to 300 characters.",
            "nullable": true,
            "example": "Customer changed the delivery address"
          },
          "reference": {
            "type": "string",
            "description": "New order reference.",
            "nullable": true,
            "example": "ORD-1001-B"
          },
          "recipient": {
            "$ref": "#/components/schemas/PublicUpdateRecipientInput"
          },
          "parcel": {
            "$ref": "#/components/schemas/PublicUpdateParcelInput"
          },
          "payment": {
            "$ref": "#/components/schemas/PublicPaymentInput"
          }
        },
        "additionalProperties": false,
        "description": "Body of `PUT /shipments/{trackingNumber}`. Every field except `reason` is optional: only the fields you\r\nsend change, everything else keeps its current value. At least one field is required."
      },
      "PublicUserDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Full name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The user behind a password-authenticated call."
      },
      "PublicWebhookCreatedDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Subscription id.",
            "format": "uuid"
          },
          "merchantId": {
            "type": "string",
            "description": "The merchant whose shipments trigger the events.",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "description": "The receiving URL.",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Subscribed event types.",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "Description.",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether it is active."
          },
          "createdAt": {
            "type": "string",
            "description": "Creation time (UTC).",
            "format": "date-time"
          },
          "secret": {
            "type": "string",
            "description": "Signing secret: keep it safe, use it to verify the `X-Signature` header of every delivery.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A newly created subscription. The signing secret is returned here once and cannot be read again."
      },
      "PublicWebhookDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Subscription id.",
            "format": "uuid"
          },
          "merchantId": {
            "type": "string",
            "description": "The merchant whose shipments trigger the events.",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "description": "The receiving URL.",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Subscribed event types.",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "Description.",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "description": "False when the subscription is paused."
          },
          "createdAt": {
            "type": "string",
            "description": "Creation time (UTC).",
            "format": "date-time"
          }
        },
        "additionalProperties": false,
        "description": "A webhook subscription of a merchant."
      },
      "PublicWebhookEventDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Event type, e.g. `shipment.delivered`.",
            "nullable": true
          },
          "description": {
            "type": "string",
            "description": "When the event is sent.",
            "nullable": true
          },
          "examplePayload": {
            "description": "An example of the JSON body of the delivery (`event`, `occurredAt`, `data`).",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "An event type that can be subscribed to."
      },
      "PublicWebhookSecretDto": {
        "type": "object",
        "properties": {
          "secret": {
            "type": "string",
            "description": "The new signing secret.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A rotated signing secret (shown once; the previous secret stops working immediately)."
      },
      "PublicWebhookTestDto": {
        "type": "object",
        "properties": {
          "queued": {
            "type": "boolean",
            "description": "True when a signed `ping` event was queued for delivery."
          },
          "eventType": {
            "type": "string",
            "description": "The event type sent (`ping`).",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Result of a test delivery request."
      },
      "PublicZoneRef": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Zone id.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Zone name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A pricing zone."
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "Access token from POST /api/public/v1/auth/login.",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "description": "Company API key (starts with lmc_live_). Must be sent together with X-API-Secret.",
        "name": "X-API-Key",
        "in": "header"
      },
      "apiSecretAuth": {
        "type": "apiKey",
        "description": "Secret of the API key, shown once when the key is created.",
        "name": "X-API-Secret",
        "in": "header"
      }
    }
  },
  "tags": [
    {
      "name": "Auth"
    },
    {
      "name": "Branches"
    },
    {
      "name": "Geography"
    },
    {
      "name": "Merchants"
    },
    {
      "name": "Pricing"
    },
    {
      "name": "Shipments"
    },
    {
      "name": "Webhooks"
    }
  ]
}
