{
  "openapi": "3.1.0",
  "info": {
    "title": "Last Mile Express — Partner REST API",
    "version": "2.13",
    "summary": "Create, label and track cross-border shipments to Morocco; estimate import duties.",
    "description": "Last Mile Express (LME) clears cross-border e-commerce parcels through Moroccan customs and delivers them to the consignee. This REST API lets shippers, marketplaces and online shops:\n\n- **create, update and cancel shipments** and get their labels as PDF;\n- **declare a flight** (pre-alert) and **finalize** shipments with re-weighed data and verified HS codes;\n- **follow every status change**, by polling the delta-tracking endpoint or by receiving a signed **webhook**;\n- for online shops: **suggest the Moroccan HS code** of a product and **estimate the import duties and taxes** of a basket.\n\nRequests and responses are JSON over HTTPS, encoded in UTF-8. Dates and times are in UTC.\n\n# Base URL\n\n| Environment | Base URL |\n|-------------|----------|\n| Sandbox | `https://sandbox.lastmile.ma` |\n| Production | `https://api.lastmile.ma` |\n\nHTTPS only. All paths below are relative to the base URL of the environment you call.\n\n# Accounts and environments\n\nLME runs **two separate environments**, each with its own server address and its own database:\n\n| Environment | Base URL | What happens to the data |\n|-------------|----------|--------------------------|\n| **Sandbox** | `https://sandbox.lastmile.ma` | Integration and tests. Shipments are **never** processed, delivered, billed or declared to customs, and no e-mail is sent. Your webhooks are delivered normally. |\n| **Production** | `https://api.lastmile.ma` | Live shipments: processed and billed. |\n\nEach partner receives **one API account per environment**. Credentials and tokens are not shared: a sandbox token is refused by production, and the reverse.\n\nDevelop and test against the **sandbox**, then switch the base URL and the credentials to go live. Use clearly fictitious data there (consignee names, order references). LME may reset the sandbox: its data is then erased and you receive new sandbox credentials.\n\nSince nothing is processed in the sandbox, **you move your shipments yourself**: `POST /api/v1/sandbox/shipments/{ref}/simulate` walks a shipment through a realistic scenario (delivered, held by customs then released, refused at the door…) with real tracking events, so you can test your status handling, your webhook endpoint and the reception lock. See [Sandbox](#tag/Sandbox).\n\nEvery account comes with three secrets: an **API username**, an **API password** and a **license number**. The LME integration team hands them over through a secure channel, never by plain e-mail and never in this document.\n\n**Data isolation.** An account only ever sees its own shipments and pre-alerts. A reference that belongs to another account answers `404 Not Found`, exactly like a reference that does not exist.\n\n# Authentication\n\n1. **Get a token** — `POST /api/v1/auth/token` with your `username`, `password` and `license`, plus an optional `label` naming the integration (for example `\"woocommerce-shop\"`). The answer contains a Bearer token (64 hexadecimal characters) valid for **24 hours**, and its expiry time in `expires_at`.\n2. **Call the API** — send `Authorization: Bearer <token>` on every other request. Credentials placed in the JSON body of a business endpoint are **not** accepted and return `401`.\n3. **Refresh before expiry** — `POST /api/v1/auth/refresh` with the current token returns a new 24-hour token; the token you sent stops working immediately. An expired token cannot be refreshed: call `/api/v1/auth/token` again.\n4. **Revoke** — `POST /api/v1/auth/revoke` invalidates the token you send, for example when you decommission an integration.\n\n> **Several tokens per account.** Each call to `/api/v1/auth/token` issues an **additional** token: the tokens already issued keep working. Several servers or integrations (an online-shop plugin and a back office, say) can therefore use the same account, each with its own token. `/api/v1/auth/refresh` and `/api/v1/auth/revoke` act **only on the token sent** in the `Authorization` header and never affect the account's other tokens.\n>\n> An account holds at most **10 active tokens**: when an 11th is issued, the oldest one is revoked. Do not call `/api/v1/auth/token` before every request — obtain a token once per integration, reuse it, and refresh it before it expires.\n\nThe password is used **only** on `/api/v1/auth/token`, which has its own, stricter rate limit and locks out an IP address after repeated failures (see [Limits](#section/Limits)). Store the token as a secret: LME keeps only a hash of it and cannot show it to you again.\n\n# Limits\n\n### Rate limits\n\n| Scope | Limit |\n|-------|-------|\n| Per IP address, every authenticated endpoint | 600 requests per 60 seconds |\n| Per API account, after authentication | 600 requests per 60 seconds by default; LME can set a different quota for your account |\n| `POST /api/v1/auth/token`, per IP address | 10 requests per 60 seconds |\n| Login lockout | 5 failed logins within 5 minutes from the same IP address lock `/api/v1/auth/token` for that address for 5 minutes, even with the right credentials |\n| Public tracking (`GET /api/v1/tracking/{ref}`), per IP address | 120 requests per 60 seconds |\n\nFor the per-IP limits, all IPv6 addresses of the same `/64` network count as one address.\n\nAuthenticated responses carry the headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Window` (seconds). Over the limit, the API answers `429 Too Many Requests`: wait and retry with exponential backoff.\n\n### Sizes\n\n| Limit | Value |\n|-------|-------|\n| Request body | 1 MB (`413 Payload Too Large` above) |\n| Items per shipment, or per manifest entry | 200 |\n| Shipments per `POST /api/v1/shipments/manifest` call | 200 |\n| Items per online-shop request (`/api/v1/shop/*`) | 100 |\n| Shipments per delta-tracking page | 2,000 (default 500) |\n\n### Field formats\n\n| Field | Rule |\n|-------|------|\n| Names, companies, contacts, address lines | 500 characters |\n| `description`, `special_instructions` | 2,000 characters |\n| `reference_number`, cities, countries, `box_number`, `flight_number`, `mawb` | 100 characters |\n| Airports | 10 characters |\n| `items[].hs_code` / `items[].description` / `items[].origin_country` | 30 / 500 / 100 characters |\n| Phone numbers | up to 30 characters: digits, spaces, `+ - ( ) .` |\n| Postal codes | up to 20 characters: letters, digits, spaces, `-` |\n| Weights (kg) | 0 to 999,999 |\n| Values and amounts | 0 to 9,999,999 |\n| Pieces and quantities | whole numbers, 0 to 99,999 |\n\nInput that breaks a rule is **rejected with `400`, never truncated**. In addition:\n\n- numbers must be finite: `NaN` and `Infinity` are refused;\n- enumerated fields (`incoterm`, `product_type`, `cod_payment_type`) accept only their listed values;\n- text that ends up in customs spreadsheets (`reference_number`, `shipper_company`, `consignee_name`, `description`, `box_number`, `items[].description`) must **not start with `=`** (spreadsheet-formula guard).\n\n# Errors\n\nSuccessful responses of the shipment, pre-alert and authentication endpoints carry a status envelope:\n\n```json\n{ \"status\": { \"code\": 1, \"description\": \"Success\" } }\n```\n\nErrors are reported by the HTTP status code, with this body, where `error.code` repeats the HTTP status:\n\n```json\n{ \"error\": { \"code\": 400, \"message\": \"Field consignee_phone contains invalid characters\" } }\n```\n\n| HTTP status | Meaning |\n|-------------|---------|\n| `200` | Success |\n| `201` | Created (shipment, pre-alert) |\n| `400` | Invalid JSON, invalid field, or operation not allowed in the shipment's current state |\n| `401` | Missing, invalid or expired token; wrong credentials on `/api/v1/auth/token` |\n| `404` | Shipment or pre-alert not found **for your account** |\n| `409` | MAWB already used by another account (pre-alerts) |\n| `413` | Request body larger than 1 MB |\n| `429` | Rate limit exceeded, or login locked out |\n| `500` | Internal error — the message contains a reference such as `Internal error (ref: a1b2c3d4e5f6)` |\n\nWhen you contact support about an error, give the error reference (for `500`), the UTC time of the call, the endpoint and your account code.\n\nThree endpoints differ from this pattern, as documented on each of them: the online-shop endpoints (`/api/v1/shop/*`) return their result without a `status` envelope; `POST /api/v1/shipments/manifest` answers `400` with its usual body when no entry at all could be processed; the public tracking endpoint returns errors as `{\"error\": \"<message>\"}`.\n\n# Idempotence and retries\n\n| Operation | Safe to retry? |\n|-----------|----------------|\n| `POST /api/v1/shipments` | **Yes, with an `Idempotency-Key` header** (see below). Without it, a retried call creates a second shipment: `reference_number` is not deduplicated, because one order can ship in several parcels. |\n| `PUT /api/v1/shipments/{ref}` | Yes — the same body gives the same result (`items`, when sent, replaces the whole list). |\n| `DELETE /api/v1/shipments/{ref}` | Yes — cancelling an already-cancelled shipment answers `200`. |\n| `POST /api/v1/shipments/manifest` | Yes, per reference — the first call answers `\"status\": \"created\"`, the next ones `\"updated\"`. |\n| `POST /api/v1/prealerts` | **No.** Each call creates a new pre-alert manifest, even for a MAWB you already declared. An empty pre-alert can be removed with `DELETE /api/v1/prealerts/{ref}`. |\n| Webhook deliveries | Retries reuse the same `X-LME-Delivery` identifier: use it to ignore duplicates. |\n\n### Idempotency-Key\n\nSend a unique `Idempotency-Key` header (1 to 128 visible ASCII characters, for example a UUID) with each `POST /api/v1/shipments`, and reuse it when you retry the same request after a timeout or a network error:\n\n- the first call creates the shipment (`201`);\n- a retry with the **same key and the same body** creates nothing and returns the original answer, with the header `Idempotent-Replayed: true`;\n- the **same key with a different body** is refused with `409`;\n- a creation that failed (`4xx` validation or `500`) does not keep the key: retrying with it is safe.\n\nKeys are private to your account and kept for 7 days.\n\n# Quick start\n\n**1. Get a token** (with your test account):\n\n```bash\ncurl -X POST https://sandbox.lastmile.ma/api/v1/auth/token \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\", \"license\": \"YOUR_LICENSE_NUMBER\"}'\n```\n\n**2. Create a shipment:**\n\n```bash\ncurl -X POST https://sandbox.lastmile.ma/api/v1/shipments \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"reference_number\": \"SHOP-ORDER-12345\",\n    \"shipper_company\": \"Sample Export Co.\",\n    \"shipper_address1\": \"123 Industrial Road\",\n    \"shipper_city\": \"Shanghai\",\n    \"shipper_country\": \"CN\",\n    \"consignee_name\": \"Ahmed Benali\",\n    \"consignee_phone\": \"+212 6 12 34 56 78\",\n    \"consignee_address1\": \"45 Rue Mohamed V\",\n    \"consignee_city\": \"Casablanca\",\n    \"weight\": 1.5,\n    \"declared_value\": 45.0,\n    \"items\": [{\"hs_code\": \"8544429090\", \"description\": \"USB cable\", \"quantity\": 2, \"unit_price\": 22.5, \"origin_country\": \"CN\"}]\n  }'\n```\n\nThe answer contains the LME reference (`\"reference\": \"LME9100123\"`).\n\n**3. Get the label (base64 PDF):**\n\n```bash\ncurl -X POST https://sandbox.lastmile.ma/api/v1/shipments/LME9100123/label \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\n**4. Follow the statuses** — of one shipment, or of every shipment changed since your last call:\n\n```bash\ncurl https://sandbox.lastmile.ma/api/v1/shipments/LME9100123/track \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n\ncurl \"https://sandbox.lastmile.ma/api/v1/shipments/tracking/changes?since=2026-03-19T10:00:00Z&limit=500\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\nPython:\n\n```python\nimport requests\n\nBASE = \"https://sandbox.lastmile.ma\"\nauth = requests.post(f\"{BASE}/api/v1/auth/token\", json={\n    \"username\": \"YOUR_USERNAME\", \"password\": \"YOUR_PASSWORD\", \"license\": \"YOUR_LICENSE_NUMBER\",\n}, timeout=30).json()\nheaders = {\"Authorization\": f\"Bearer {auth['auth']['token']}\"}\n\nresp = requests.post(f\"{BASE}/api/v1/shipments\", headers=headers, timeout=30, json={\n    \"reference_number\": \"SHOP-ORDER-12345\",\n    \"consignee_name\": \"Ahmed Benali\",\n    \"consignee_phone\": \"+212 6 12 34 56 78\",\n    \"consignee_address1\": \"45 Rue Mohamed V\",\n    \"consignee_city\": \"Casablanca\",\n    \"weight\": 1.5,\n})\nresp.raise_for_status()\nprint(resp.json()[\"shipment\"][\"reference\"])\n```\n\n# Support\n\nWrite to the LME integration team at [info@lastmiledeliveryexpress.ma](mailto:info@lastmiledeliveryexpress.ma) to request API accounts, enable the status webhook or report an issue.",
    "contact": {
      "name": "LME integration team",
      "email": "info@lastmiledeliveryexpress.ma"
    }
  },
  "servers": [
    {
      "url": "https://api.lastmile.ma",
      "description": "Production"
    },
    {
      "url": "https://sandbox.lastmile.ma",
      "description": "Sandbox"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Exchange your credentials for a 24-hour Bearer token, refresh it, revoke it. See [Authentication](#section/Authentication)."
    },
    {
      "name": "Shipments",
      "description": "Create, read, update and cancel shipments, get their labels, and finalize them in bulk with verified data.\n\nEvery `{ref}` accepts the LME reference or your own `reference_number`. A shipment of another account answers `404`."
    },
    {
      "name": "Tracking",
      "description": "Three ways to follow your shipments:\n\n- **One shipment** — `GET /api/v1/shipments/{ref}/track` returns its full event history.\n- **Everything that changed** — `GET /api/v1/shipments/tracking/changes?since=…` returns only the shipments whose status changed since a timestamp, with their new events. This is the recommended way to synchronise many shipments.\n- **Push** — LME can call your endpoint on every status change: see [Status webhook](#tag/Status-webhook).\n\nThe public tracking endpoint (`GET /api/v1/tracking/{ref}`) needs no token and shows only the events meant for consumers.\n\n### Shipment states\n\n| `state` | Meaning | Set by |\n|---------|---------|--------|\n| `draft` | Created but not registered (not used for shipments created through this API) | — |\n| `registered` | Registered | creation through the API, `EC`, `SP` |\n| `in_customs` | In customs clearance | `IC` |\n| `cleared` | Released by customs | `CR` |\n| `dispatched` | Handed over to the last-mile carrier or to the linehaul | `HN`, `DH` |\n| `in_delivery` | Out for delivery | `LV` |\n| `delivered` | Delivered to the consignee | `OK` |\n| `failed` | Delivery failure | `NF`, `NU`, `DR` |\n| `returned` | Returned to the warehouse or to origin, or delivery rescheduled | `RW`, `RO`, `RD` |\n| `cancelled` | Cancelled, damaged or lost, abandoned, or deposited with customs | `DELETE /api/v1/shipments/{ref}`, `ED`, `AS`, `DC` |\n\nOther event codes update `last_status_code` but leave `state` unchanged.\n\n### Event codes\n\nYour API responses and webhooks only contain the codes below. Internal warehouse and customs-control steps (on hold, customs targeting, unloading, overstay zone…) are not exposed; a shipment put on hold is reported in the `customs` block instead (see below). The `description` of an event is always the official label of its code.\n\n| Code | Name | Phase | Webhook milestone | Public tracking |\n|------|------|-------|-------------------|-----------------|\n| `EC` | Ecom Registration | E-commerce | — | Yes |\n| `SP` | Shipment Preparation | Pick-up | — | Yes |\n| `PU` | Pick Up | Pick-up | — | Yes |\n| `AR` | Arrival to Facility | Warehouse | Yes | Yes |\n| `IC` | Into Customs | Warehouse | Yes | Yes |\n| `SI` | Shipment Inspection | Warehouse | — | No |\n| `CN` | Customer Notified | Warehouse | — | Yes |\n| `CP` | Customs Clearance in Progress | Warehouse | — | Yes |\n| `CR` | Clearance Release | Warehouse | Yes | Yes |\n| `DF` | Depart From Facility | Warehouse | — | Yes |\n| `HN` | Handover | Warehouse | Yes | Yes |\n| `SL` | Sorting at Location | Warehouse | — | Yes |\n| `SS` | SMS Sent | Warehouse | — | Yes |\n| `TP` | Transferred To Partner | Warehouse | — | Yes |\n| `DP` | Delivered By Partner | Warehouse | — | Yes |\n| `RW` | Returned To Warehouse | Warehouse | — | Yes |\n| `RO` | Return To Origin | Warehouse | Yes | Yes |\n| `AX` | Awaiting Customer Clearance | Delivery | Yes | Yes |\n| `HP` | Held For Pickup | Warehouse | — | Yes |\n| `IN` | Incorrect Phone Number | Warehouse | — | Yes |\n| `LV` | Load Into Vehicle | Delivery | — | Yes |\n| `WC` | With Courier | Delivery | — | Yes |\n| `OK` | Delivered | Delivery | Yes | Yes |\n| `CF` | Clearance Failure | Customs | Yes | Yes |\n| `NH` | Customer Not Home | Delivery | — | Yes |\n| `ND` | Not Delivered | Exception | — | Yes |\n| `BA` | Bad Address | Exception | — | Yes |\n| `CD` | Customer Moved | Exception | — | Yes |\n| `ED` | Damaged / Lost | Exception | — | Yes |\n| `AS` | Abandoned Shipment | Exception | — | Yes |\n| `UC` | Unreachable Customer | Exception | — | Yes |\n| `CV` | Customer In Vacation | Exception | — | Yes |\n| `CS` | Customer Absent (Recurring) | Exception | — | Yes |\n| `IA` | Incomplete Address | Exception | — | Yes |\n| `IP` | Incomplete Phone Number | Exception | — | Yes |\n| `RD` | Rescheduling Delivery | Exception | — | Yes |\n| `PF` | Pick-up from Freight Station | Customs | — | Yes |\n| `WT` | Warehouse Tallying | Customs | — | No |\n| `DH` | Departure to Linehaul | Customs | Yes | Yes |\n| `DS` | Declaration Start | Customs | — | No |\n| `FS` | Filing Submitted | Customs | — | No |\n| `FT` | Freight in Transport | Customs | — | No |\n| `RC` | Receipt of Clearance | Customs | — | No |\n| `US` | Unclaimed Shipment - Overstay | Customs | Yes | Yes |\n| `DC` | Deposited with Customs | Customs | Yes | Yes |\n| `PG` | Prohibited Goods | Customs | Yes | Yes |\n| `NF` | Delivery Failure (Not Provider Fault) | Delivery | — | Yes |\n| `NU` | Delivery Failure (Unknown Reason) | Delivery | — | Yes |\n| `DR` | Delivery Rejected | Delivery | — | Yes |\n\n### Shipments on hold\n\nWhen the customs inspector holds a shipment, it leaves the simplified clearance procedure. Its `state` stays `in_customs`, so read the `customs` block returned by `GET /api/v1/shipments/{ref}`, by `tracking/changes` and in every webhook:\n\n| Field | Meaning |\n|-------|---------|\n| `customs_flow` | `simplified` (normal e-commerce clearance) or `blocked` (put on hold at least once, cleared individually — stays `blocked` after release) |\n| `on_hold` | `true` while the shipment waits after being put on hold (notifying the consignee or waiting for the customer's clearance does not end it) |\n| `on_hold_since` | UTC time it was put on hold, empty otherwise |\n| `mead_arrival` | UTC time of the first scan in the bonded warehouse (MEAD) |\n| `legal_deadline` | Date after which unclaimed goods are transferred to customs (MEAD arrival + 45 days) |\n\nThe LME team contacts the consignee for the duties of a held shipment; the outcome then appears as regular events (`CR`, `CF`, `PG`, `DC`, `US`, `AX`…).\n"
    },
    {
      "name": "Pre-alerts",
      "description": "Announce the flight (MAWB) that carries your shipments before it lands."
    },
    {
      "name": "Online shops",
      "description": "For e-commerce plugins (WooCommerce, Shopify…): suggest the Moroccan HS code of your products and show the duties and taxes of a basket at checkout. Same Bearer token as the other endpoints."
    },
    {
      "name": "Status webhook",
      "description": "LME can **push every status change** of your shipments to an HTTPS endpoint of yours, instead of you polling `GET /api/v1/shipments/tracking/changes`.\n\nTo enable it, send the LME integration team:\n\n- your **URL**: it must start with `https://` and resolve to a public internet address;\n- the **events** you want: `all`, `milestones` (arrival `AR`, into customs `IC`, release `CR`, handovers `HN` and `DH`, delivery `OK`, return `RO`, and the customs outcomes `CF`, `PG`, `DC`, `US`, `AX` — the default) or `delivery` (`OK`, `DR`, `NH`, `RO`, `RW`);\n- the **format**: JSON (default) or XML;\n- the shared secret, exchanged through a secure channel.\n\nA shared **secret**, agreed with LME and stored on your account, signs each request.\n\n### Verifying the signature\n\n`X-LME-Signature` is `sha256=` followed by the hexadecimal HMAC-SHA256 of the string `<X-LME-Timestamp>.<raw request body>`, keyed with the shared secret. Compute it on the **raw bytes** of the body, before any JSON parsing, compare in constant time, and reject requests whose `X-LME-Timestamp` is more than 5 minutes old (each retry carries a fresh timestamp and signature).\n\n```python\nimport hashlib, hmac, time\n\ndef verify(secret: str, headers, raw_body: bytes) -> bool:\n    timestamp = headers[\"X-LME-Timestamp\"]\n    if abs(time.time() - int(timestamp)) > 300:\n        return False\n    expected = \"sha256=\" + hmac.new(secret.encode(), timestamp.encode() + b\".\" + raw_body,\n                                    hashlib.sha256).hexdigest()\n    return hmac.compare_digest(expected, headers.get(\"X-LME-Signature\", \"\"))\n```\n\n```javascript\nconst crypto = require(\"crypto\");\n\nfunction verify(secret, headers, rawBody /* Buffer */) {\n  const timestamp = headers[\"x-lme-timestamp\"];\n  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;\n  const expected = \"sha256=\" + crypto.createHmac(\"sha256\", secret)\n    .update(Buffer.concat([Buffer.from(timestamp + \".\"), rawBody])).digest(\"hex\");\n  const given = Buffer.from(headers[\"x-lme-signature\"] || \"\");\n  return given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));\n}\n```\n\n### Response and retries\n\nAnswer with any **2xx status within 5 seconds** (LME waits at most 3 s to connect and 5 s for the answer); process the notification asynchronously if needed. Redirects are **not followed**: a 3xx answer counts as a failure, so configure the final URL. LME resolves your host name before every delivery and never calls a private, loopback, link-local, reserved or multicast address: such a delivery is abandoned at once, without retry and without pausing your endpoint. A non-2xx status, a timeout or a connection error is retried with increasing delays — 30 s, 1 min, 5 min, 15 min, 30 min, then every hour — up to **10 attempts** in total. Answering **`410 Gone`** stops the retries for that delivery at once.\n\n**Unreachable endpoint.** After 5 consecutive timeouts, connection errors, 5xx or 429 answers, LME pauses deliveries to your endpoint for 1 minute, then 2, 4… up to 1 hour, and resumes automatically; paused deliveries are kept and do not use up attempts. The first successful delivery ends the pause. A 4xx answer only affects that delivery. Your endpoint never slows down deliveries to other partners.\n\nRetries keep the same `X-LME-Delivery` identifier: use it to discard duplicates. Deliveries are not guaranteed to arrive in chronological order (a retried delivery can arrive after a later one): order the statuses by `status.datetime`.\n\nInternal codes are never sent, whichever selection you choose."
    },
    {
      "name": "Sandbox",
      "description": "**Sandbox only.** In the sandbox no shipment is ever processed, so nothing would ever move. These operations walk one of your sandbox shipments through a realistic scenario by recording real tracking events: the shipment status, the tracking endpoints, the `customs` block, the reception lock (`409` on update or cancel once LME holds the parcel) and your **status webhooks** all behave exactly as in production.\n\nIn production these paths do not exist: they answer `404`."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Access",
      "tags": [
        "Authentication"
      ]
    },
    {
      "name": "Shipping",
      "tags": [
        "Shipments",
        "Tracking",
        "Pre-alerts"
      ]
    },
    {
      "name": "E-commerce tools",
      "tags": [
        "Online shops"
      ]
    },
    {
      "name": "Webhooks",
      "tags": [
        "Status webhook"
      ]
    },
    {
      "name": "Testing",
      "tags": [
        "Sandbox"
      ]
    }
  ],
  "paths": {
    "/api/v1/auth/token": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "operationId": "getToken",
        "summary": "Get a token",
        "description": "Exchanges your API credentials for a new Bearer token valid **24 hours**. Every successful call issues an **additional** token: the tokens already issued to the account keep working, so each of your integrations can hold its own. An account holds at most 10 active tokens; beyond that, the oldest one is revoked.\n\nThis is the only endpoint that takes the password. It is limited to 10 requests per minute per IP address, and 5 failed attempts within 5 minutes lock it for that IP address for 5 minutes.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Authentication successful"
                  },
                  "auth": {
                    "token": "3f1c9a7e5b2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e",
                    "expires_at": "2026-11-20T09:30:00Z",
                    "account": "CUST-001",
                    "customer_name": "Sample Shop Ltd"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "missing": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Missing required fields: username, password, license"
                      }
                    }
                  },
                  "too_long": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Input too long"
                      }
                    }
                  },
                  "label_type": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "label must be a string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Wrong username, password or license.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_credentials": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Invalid credentials"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many login requests, or login locked out for this IP address.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate": {
                    "value": {
                      "error": {
                        "code": 429,
                        "message": "Too many requests"
                      }
                    },
                    "summary": "More than 10 requests per minute"
                  },
                  "locked": {
                    "value": {
                      "error": {
                        "code": 429,
                        "message": "Account temporarily locked due to too many failed attempts. Please try again in 5 minutes."
                      }
                    },
                    "summary": "Locked out after 5 failures"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/refresh": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "operationId": "refreshToken",
        "summary": "Refresh the token",
        "description": "Returns a new token valid 24 hours, in exchange for the current, **still valid** token sent in the `Authorization` header. The token sent stops working immediately; the account's other tokens are not affected. The new token keeps the `label` of the one it replaces. No request body. An expired token is refused: call `POST /api/v1/auth/token` instead.",
        "responses": {
          "200": {
            "description": "New token issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefreshResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Token refreshed successfully"
                  },
                  "auth": {
                    "token": "9b8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
                    "expires_at": "2026-11-20T09:30:00Z",
                    "account": "CUST-001"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "401": {
            "description": "No token, unknown token or expired token.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missing": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Missing Authorization header"
                      }
                    }
                  },
                  "empty": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Empty token"
                      }
                    }
                  },
                  "invalid": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Invalid token"
                      }
                    }
                  },
                  "expired": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Token expired — please re-authenticate"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ip": {
                    "value": {
                      "error": {
                        "code": 429,
                        "message": "Too many requests"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/revoke": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "operationId": "revokeToken",
        "summary": "Revoke the token",
        "description": "Invalidates the token sent in the `Authorization` header — and only that one: the account's other tokens keep working. No request body. Afterwards, the integration that used it calls `POST /api/v1/auth/token` to get a new one.",
        "responses": {
          "200": {
            "description": "Token revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOnly"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Token revoked successfully"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "401": {
            "description": "No token, unknown token or token already revoked.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missing": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Missing Authorization header"
                      }
                    }
                  },
                  "empty": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Empty token"
                      }
                    }
                  },
                  "invalid": {
                    "value": {
                      "error": {
                        "code": 401,
                        "message": "Invalid token"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ip": {
                    "value": {
                      "error": {
                        "code": 429,
                        "message": "Too many requests"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/shipments": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "operationId": "createShipment",
        "summary": "Create a shipment",
        "description": "Registers a new shipment and returns its LME reference. The shipment starts in state `registered` with the event `EC`. The destination hub is resolved from the consignee city (and postal code); when the city is unknown, `destination_hub` is empty and LME assigns it later.\n\nGet the label with `POST /api/v1/shipments/{ref}/label`.\n\n**Safe retries:** send an `Idempotency-Key` header and reuse it when you retry; without it, a retried call creates a second shipment — see [Idempotence and retries](#section/Idempotence-and-retries).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Shipment created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentCreated"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Shipment created successfully"
                  },
                  "shipment": {
                    "reference": "LME9100123",
                    "shipper_reference": "SHOP-ORDER-12345",
                    "weight": 0.7,
                    "pieces": 1,
                    "box_number": "",
                    "destination_hub": "CAS",
                    "items": [
                      {
                        "hs_code": "8544429090",
                        "description": "USB cable, type C",
                        "quantity": 2,
                        "unit_price": 15.0,
                        "weight": 0.5,
                        "origin_country": "CN"
                      },
                      {
                        "hs_code": "3926909990",
                        "description": "Phone case, plastic",
                        "quantity": 1,
                        "unit_price": 15.0,
                        "weight": 0.2,
                        "origin_country": "CN"
                      }
                    ]
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              },
              "Idempotent-Replayed": {
                "description": "`true` when this answer is the replay of an earlier request with the same `Idempotency-Key`.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "not_object": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "JSON object expected"
                      }
                    }
                  },
                  "too_long": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field consignee_city exceeds maximum length (100)"
                      }
                    }
                  },
                  "phone": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field consignee_phone contains invalid characters"
                      }
                    }
                  },
                  "selection": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field incoterm must be one of DDP, DDU"
                      }
                    }
                  },
                  "not_finite": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field weight must be a finite number"
                      }
                    }
                  },
                  "range": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field declared_value out of range (0-9999999.0)"
                      }
                    }
                  },
                  "formula": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field description must not start with \"=\""
                      }
                    }
                  },
                  "items": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Too many items (max 200)"
                      }
                    }
                  },
                  "item_field": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Item 0: Field hs_code exceeds maximum length (30)"
                      }
                    }
                  },
                  "cod": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "COD is prohibited for cross-border e-commerce (R-09)"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "409": {
            "description": "The `Idempotency-Key` was already used with a different request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "conflict": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "Idempotency-Key already used with a different request body"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique key of this creation request (1 to 128 visible ASCII characters, e.g. a UUID). Reuse it when you retry: the original answer is returned instead of creating a second shipment. Kept 7 days.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[\\x21-\\x7e]{1,128}$"
            },
            "example": "5f0c7e1e-8d6b-4a7e-9b55-2f1d0c3a9e41"
          }
        ]
      }
    },
    "/api/v1/shipments/{ref}": {
      "parameters": [
        {
          "name": "ref",
          "in": "path",
          "required": true,
          "description": "The shipment: LME reference (`LME9…`), your `reference_number`, the delivery barcode or the booking reference. Exact match first, then case-insensitive. Only shipments of your account are found.",
          "schema": {
            "type": "string",
            "maxLength": 100
          },
          "example": "LME9100123"
        }
      ],
      "get": {
        "tags": [
          "Shipments"
        ],
        "operationId": "getShipment",
        "summary": "Get a shipment",
        "description": "Returns the shipment as registered at LME: its state, the latest status code visible to you, its customs situation (`customs`, including whether it is on hold) and its customs lines.",
        "responses": {
          "200": {
            "description": "The shipment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Success"
                  },
                  "shipment": {
                    "reference": "LME9100123",
                    "shipper_reference": "SHOP-ORDER-12345",
                    "state": "in_customs",
                    "last_status_code": "IC",
                    "incoterm": "DDP",
                    "weight": 0.7,
                    "pieces": 1,
                    "declared_value": 45.0,
                    "cod_flag": false,
                    "cod_amount": 0.0,
                    "consignee_name": "Ahmed Benali",
                    "consignee_city": "Casablanca",
                    "consignee_country": "Morocco",
                    "box_number": "CTN-042",
                    "destination_hub": "CAS",
                    "items": [
                      {
                        "hs_code": "8544429090",
                        "description": "USB cable, type C",
                        "quantity": 2,
                        "unit_price": 15.0,
                        "weight": 0.5,
                        "origin_country": "CN"
                      },
                      {
                        "hs_code": "3926909990",
                        "description": "Phone case, plastic",
                        "quantity": 1,
                        "unit_price": 15.0,
                        "weight": 0.2,
                        "origin_country": "CN"
                      }
                    ],
                    "customs": {
                      "customs_flow": "simplified",
                      "on_hold": false,
                      "on_hold_since": "",
                      "mead_arrival": "2026-11-16T08:42:10Z",
                      "legal_deadline": "2026-12-31"
                    }
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "put": {
        "tags": [
          "Shipments"
        ],
        "operationId": "updateShipment",
        "summary": "Update a shipment",
        "description": "Changes the data of a shipment that is neither `delivered` nor `cancelled`. Send only the fields that change. Changing the city (or postal code) re-resolves the destination hub. `items`, when sent, replaces all customs lines.\n\n**Once LME has received the shipment** (first warehouse, customs or delivery scan, or customs document issued), only the contact details can still change: `consignee_contact`, `consignee_phone`, `consignee_address1` to `consignee_address3`, `consignee_zip`, `consignee_city` and `special_instructions`. Fields that make up the customs declaration (`consignee_name`, `weight`, `pieces`, `description`, `declared_value`, `cod_flag`, `cod_amount`, `items`) are refused with `409`: ask LME operations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentRefResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Shipment updated successfully"
                  },
                  "shipment": {
                    "reference": "LME9100123"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "state": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Cannot update a delivered or cancelled shipment"
                      }
                    }
                  },
                  "phone": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field consignee_phone contains invalid characters"
                      }
                    }
                  },
                  "not_finite": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field weight must be a finite number"
                      }
                    }
                  },
                  "cod": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "COD is prohibited for cross-border e-commerce (R-09)"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "409": {
            "description": "The shipment has already been received by LME (first warehouse, customs or delivery scan, or customs document issued).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "received": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "Shipment already received by LME: only contact details can still be updated (consignee_address1, consignee_address2, consignee_address3, consignee_city, consignee_contact, consignee_phone, consignee_zip, special_instructions). Ask LME operations to change: declared_value, weight."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Shipments"
        ],
        "operationId": "cancelShipment",
        "summary": "Cancel a shipment",
        "description": "Sets the shipment to `cancelled` (it is kept, not deleted). Only possible **before LME receives it**: once a warehouse, customs or delivery scan is recorded or a customs document is issued, the API answers `409` and the cancellation must be requested from LME operations. Cancelling an already-cancelled shipment succeeds.",
        "responses": {
          "200": {
            "description": "Shipment cancelled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentRefResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Shipment cancelled successfully"
                  },
                  "shipment": {
                    "reference": "LME9100123"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "state": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Cannot cancel a shipment already in delivery"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "409": {
            "description": "The shipment has already been received by LME (first warehouse, customs or delivery scan, or customs document issued).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "received": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "Shipment already received by LME (state in_customs): it can no longer be cancelled through the API. Ask LME operations."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/shipments/{ref}/label": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "operationId": "getLabel",
        "summary": "Get the label",
        "description": "Generates the shipping label of one shipment (PDF, 4 × 6 inches, Code 128 barcodes) and returns it base64-encoded. No request body. Call it again at any time to reprint.\n\nOnce you have sent verified data through `POST /api/v1/shipments/manifest`, the label prints the **verified weight**; before that, the declared weight.\n\nLabel rendering has its own quota: **60 labels per minute** per account, on top of the general quota. Beyond it the answer is `429`.\n\nIf the PDF cannot be generated, the answer is still `200` with an empty `label`.",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "The shipment: LME reference (`LME9…`), your `reference_number`, the delivery barcode or the booking reference. Exact match first, then case-insensitive. Only shipments of your account are found.",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "LME9100123"
          }
        ],
        "responses": {
          "200": {
            "description": "The label.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LabelResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Success"
                  },
                  "shipment": {
                    "reference": "LME9100123"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/shipments/{ref}/track": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "operationId": "trackShipment",
        "summary": "Track a shipment",
        "description": "Returns the tracking events of the shipment that are visible to you, oldest first, each with the official label of its code (see [Event codes](#tag/Tracking)). Internal steps are not returned; a shipment on hold is reported in the `customs` block of `GET /api/v1/shipments/{ref}`. The public tracking shows a shorter, consumer-facing subset.",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "The shipment: LME reference (`LME9…`), your `reference_number`, the delivery barcode or the booking reference. Exact match first, then case-insensitive. Only shipments of your account are found.",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "LME9100123"
          }
        ],
        "responses": {
          "200": {
            "description": "The tracking history.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingResponse"
                },
                "example": {
                  "shipment": {
                    "consignment_number": "LME9100123",
                    "reference_number": "SHOP-ORDER-12345"
                  },
                  "events": [
                    {
                      "code": "EC",
                      "description": "Enregistrement e-commerce",
                      "date": "2026-03-04",
                      "time": "09:12:40",
                      "location": ""
                    },
                    {
                      "code": "AR",
                      "description": "Arrivée au facility",
                      "date": "2026-03-06",
                      "time": "08:15:00",
                      "location": "Under Customs - Morocco"
                    },
                    {
                      "code": "IC",
                      "description": "Entrée en douane",
                      "date": "2026-03-06",
                      "time": "08:15:05",
                      "location": "Under Customs - Morocco"
                    }
                  ],
                  "status": {
                    "code": 1,
                    "description": "Success"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/shipments/tracking/changes": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "operationId": "getTrackingChanges",
        "summary": "List status changes since a date",
        "description": "Returns the shipments of your account whose status changed **after** `since`, oldest change first, each with the events visible to you recorded after `since` and its `customs` block. A shipment can appear with no new event when only an internal step changed — for example when it is put on hold: check `customs.on_hold`.\n\n**Polling.** When `has_more` is `false`, store `until` and pass it as `since` on the next call. Nothing is ever skipped between two calls chained this way.\n\n**What counts as a change.** Shipments are ordered by the time LME recorded the change, not by the business date of the status: a status entered later with an earlier date (for example a hand-over completed afterwards) is still served. `last_update` keeps the business date.\n\n**Events are delivered at least once.** An event may appear in two consecutive answers; each event carries an `id`, keep the ones you already have.\n\n**Pagination.** When `has_more` is `true`, call again with `cursor` set to `next_cursor` (an opaque string: send it back unchanged) until `has_more` is `false`. Pages are cut on a total order (change time, then record), so shipments changed in the same second are never split or lost across pages.\n\n**Freshness.** To guarantee that no change is missed, a change is served about **3 minutes** after it is recorded, once its transaction is surely committed. `until` is therefore a little behind the current time. For real-time needs, use the [status webhook](#tag/Status-webhook).\n\n**Recommended frequency:** every 2 to 15 minutes.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "UTC date-time, ISO 8601 (`2026-03-19T10:00:00Z`). Required unless `cursor` is given. A time-zone offset (`+01:00`) is converted to UTC.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-03-19T10:00:00Z"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` of the previous page, sent back unchanged. When both `cursor` and `since` are sent, `cursor` wins.",
            "schema": {
              "type": "string"
            },
            "example": "2026-03-19T14:30:00.000000Z"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of shipments in the page. Values above 2,000 are capped to 2,000.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The changed shipments.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingChangesResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Success"
                  },
                  "since": "2026-03-19T10:00:00Z",
                  "until": "2026-03-19T14:30:00Z",
                  "total_changed": 1,
                  "has_more": false,
                  "next_cursor": "",
                  "shipments": [
                    {
                      "tracking_number": "LME9100123",
                      "shipper_reference": "SHOP-ORDER-12345",
                      "current_status": "IC",
                      "current_status_label": "In Customs",
                      "state": "in_customs",
                      "last_update": "2026-03-19T14:30:00Z",
                      "destination_hub": "CAS",
                      "new_events": [
                        {
                          "id": 184467,
                          "code": "AR",
                          "description": "Arrivée au facility",
                          "datetime": "2026-03-19T14:29:55Z",
                          "location": "Under Customs - Morocco",
                          "agent_code": "AG01"
                        },
                        {
                          "id": 184468,
                          "code": "IC",
                          "description": "Entrée en douane",
                          "datetime": "2026-03-19T14:30:00Z",
                          "location": "Under Customs - Morocco",
                          "agent_code": "AG01"
                        }
                      ],
                      "customs": {
                        "customs_flow": "simplified",
                        "on_hold": false,
                        "on_hold_since": "",
                        "mead_arrival": "2026-11-16T08:42:10Z",
                        "legal_deadline": "2026-12-31"
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "missing": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Missing 'since' parameter (ISO 8601 datetime)"
                      }
                    }
                  },
                  "format": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid 'since' format. Use ISO 8601 (e.g. 2026-03-19T10:00:00Z)"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/shipments/manifest": {
      "post": {
        "tags": [
          "Shipments"
        ],
        "operationId": "finalizeShipments",
        "summary": "Finalize shipments (bulk)",
        "description": "After your own physical check (re-weighing, HS code verification, cartonization), sends the verified data of up to **200 shipments** in one call. LME keeps your original declaration and records the verified data separately; customs and labels use the verified data. **No label is returned**: your parcels are already labelled at this stage. If you need to reprint one, call `POST /api/v1/shipments/{ref}/label` for that shipment — it prints the verified weight.\n\nShipments are processed one by one: invalid entries are listed in `errors` without blocking the others. An entry that fails is rolled back as a whole: it is never half-updated, and an existing entry keeps its previous items. A field sent as `null` (or an empty string for a number) is ignored: the verified value is left unchanged. The answer is `200` when at least one entry was processed, `400` (same body) when none was.\n\nIdempotent per reference: `status` is `created` the first time, `updated` afterwards. Shipments are looked up by LME reference or `reference_number`; cancelled shipments are refused, and so are shipments already received by LME (as for `PUT` and `DELETE`, which answer `409`): their entry is listed in `errors` and their verified data is left unchanged — ask LME operations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManifestRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "At least one entry processed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ManifestResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Manifest processed"
                  },
                  "manifest": {
                    "total_submitted": 2,
                    "total_updated": 1,
                    "total_errors": 1,
                    "shipments": [
                      {
                        "reference": "LME9100123",
                        "shipper_reference": "SHOP-ORDER-12345",
                        "status": "created",
                        "actual_weight": 0.8,
                        "declared_value": 45.0,
                        "pieces": 1,
                        "box_number": "CTN-001",
                        "destination_hub": "CAS"
                      }
                    ],
                    "errors": [
                      {
                        "reference": "SHOP-ORDER-12399",
                        "error": "Shipment not found"
                      }
                    ]
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request, or no entry could be processed.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ManifestResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "examples": {
                  "all_failed": {
                    "summary": "No entry processed",
                    "value": {
                      "status": {
                        "code": 1,
                        "description": "Manifest processed"
                      },
                      "manifest": {
                        "total_submitted": 1,
                        "total_updated": 0,
                        "total_errors": 1,
                        "shipments": [],
                        "errors": [
                          {
                            "reference": "LME9100123",
                            "error": "actual_weight must be > 0"
                          }
                        ]
                      }
                    }
                  },
                  "missing": {
                    "summary": "Empty request",
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Missing shipments array"
                      }
                    }
                  },
                  "too_many": {
                    "summary": "More than 200 entries",
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Maximum 200 shipments per manifest call (received 250)"
                      }
                    }
                  },
                  "invalid_json": {
                    "summary": "Invalid JSON",
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/prealerts": {
      "post": {
        "tags": [
          "Pre-alerts"
        ],
        "operationId": "createPrealert",
        "summary": "Create a pre-alert",
        "description": "Announces a flight (MAWB) before it lands and opens a pre-alert manifest for your account. The MAWB is normalised (spaces removed, upper case, `NNN-NNNNNNNN` when given as 11 digits). If LME already knows it, the existing flight is reused only when it is open to your account: LME operations named you as its expected customer, or no customer is expected and the flight carries no manifest of another account. Otherwise the call answers `409`.\n\n**Not idempotent:** each call opens a new manifest, even for the same MAWB.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrealertInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Pre-alert created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrealertResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Pre-alert created"
                  },
                  "prealert": {
                    "flight": "XX1234",
                    "mawb": "999-12345678",
                    "manifest": "MAN-00007"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "mawb": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field mawb is required (airline prefix and number, e.g. 147-12345678)"
                      }
                    }
                  },
                  "date": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field arrival_date is not a readable date (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)"
                      }
                    }
                  },
                  "too_long": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Field departure_airport exceeds maximum length (10)"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The MAWB is not available for your account: it is handled for another account, or LME operations expect another customer on it. The answer is the same in every case and reveals nothing about the flight; contact LME operations if the MAWB is yours.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "conflict": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "MAWB not available for this account"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/v1/prealerts/{ref}": {
      "delete": {
        "tags": [
          "Pre-alerts"
        ],
        "operationId": "deletePrealert",
        "summary": "Delete a pre-alert",
        "description": "Deletes a pre-alert manifest of your account, as long as no shipment is attached to it.",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Pre-alert manifest reference, as returned by `POST /api/v1/prealerts`.",
            "schema": {
              "type": "string"
            },
            "example": "MAN-00007"
          }
        ],
        "responses": {
          "200": {
            "description": "Pre-alert deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusOnly"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Pre-alert deleted"
                  }
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_empty": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Cannot delete a manifest with shipments"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No pre-alert with this reference in your account.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "error": {
                        "code": 404,
                        "message": "Pre-alert manifest not found"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/shop/hscode": {
      "post": {
        "tags": [
          "Online shops"
        ],
        "operationId": "classifyProducts",
        "summary": "Suggest Moroccan HS codes",
        "description": "For each product, proposes the Moroccan tariff position (10-digit HS code, ADIL nomenclature) and its import duty rate. LME first looks for the same product in earlier customs declarations, then remaps the HS code you send onto the Moroccan tariff. A product that cannot be classified with confidence is returned with an empty `hs_code` and `method` = `non_resolu`: it is never guessed.\n\nUp to 100 products per call. The answer has no `status` envelope.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HsCodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per product, in the request order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HsCodeResponse"
                },
                "example": {
                  "items": [
                    {
                      "hs_code": "8544429090",
                      "method": "adil",
                      "designation": "Autres conducteurs électriques, munis de pièces de connexion",
                      "duty_rate": 17.5,
                      "description": "USB cable, type C"
                    },
                    {
                      "hs_code": "",
                      "method": "non_resolu",
                      "designation": "",
                      "duty_rate": null,
                      "description": "Gift set"
                    }
                  ]
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "items": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "\"items\" must be a non-empty list"
                      }
                    }
                  },
                  "too_many": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "At most 100 items per request"
                      }
                    }
                  },
                  "item": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Each item must be an object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/shop/quote": {
      "post": {
        "tags": [
          "Online shops"
        ],
        "operationId": "quoteDuties",
        "summary": "Estimate duties and taxes",
        "description": "Estimates the Moroccan import duties and taxes of a basket, per item and in total, for display at checkout. Each item is classified as in `POST /api/v1/shop/hscode`, then taxed:\n\n- import duty (`000110`) at the rate of the tariff position, on the value;\n- parafiscal tax (`007217`), 0.25 % of the value;\n- VAT (`002109`), 20 % of value + import duty + parafiscal tax;\n- each tax rounded up to the dirham, 1 MAD minimum.\n\nWhere customs actually applied a different rate to a tariff position (reduced VAT, environment fund on plastics `004801`…), that rate is used. Unclassified items get no tax and set `complete` to `false`.\n\nThis is an **estimate**: the amount due is the one assessed by customs. Up to 100 items per call; the answer has no `status` envelope.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The estimate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteResponse"
                },
                "example": {
                  "currency": "USD",
                  "rate_to_mad": 9.2,
                  "complete": true,
                  "items": [
                    {
                      "description": "USB cable, type C",
                      "quantity": 2.0,
                      "value_mad": 276.0,
                      "hs_code": "8544429090",
                      "method": "adil",
                      "designation": "Autres conducteurs électriques, munis de pièces de connexion",
                      "taxes": [
                        {
                          "code": "000110",
                          "label": "Droit d'importation",
                          "rate": 17.5,
                          "base_mad": 276.0,
                          "amount_mad": 49
                        },
                        {
                          "code": "007217",
                          "label": "Taxe parafiscale",
                          "rate": 0.25,
                          "base_mad": 276.0,
                          "amount_mad": 1
                        },
                        {
                          "code": "002109",
                          "label": "TVA",
                          "rate": 20.0,
                          "base_mad": 326,
                          "amount_mad": 66
                        }
                      ],
                      "total_mad": 116
                    }
                  ],
                  "totals_mad": {
                    "000110": 49,
                    "007217": 1,
                    "002109": 66
                  },
                  "total_mad": 116,
                  "total": 12.61,
                  "disclaimer": "Estimation selon le tarif ADIL et les liquidations constatées ; le montant définitif est celui de la liquidation douanière."
                }
              }
            },
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Invalid JSON body"
                      }
                    }
                  },
                  "items": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "\"items\" must be a non-empty list"
                      }
                    }
                  },
                  "too_many": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "At most 100 items per request"
                      }
                    }
                  },
                  "numbers": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "\"unit_value\" and \"quantity\" must be numbers"
                      }
                    }
                  },
                  "currency": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Devise inconnue : XYZ"
                      }
                    },
                    "summary": "Unknown currency"
                  },
                  "inactive_currency": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Devise GBP non prise en charge : utilisez USD ou MAD."
                      }
                    },
                    "summary": "Currency not enabled"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/tracking/{ref}": {
      "get": {
        "tags": [
          "Tracking"
        ],
        "operationId": "getPublicTracking",
        "summary": "Public tracking",
        "description": "Tracking without authentication, for consumer-facing pages: returns the state and the consumer-visible events only. Accepts the LME reference, the delivery barcode or the booking reference (not your `reference_number`). Limited to 120 requests per minute per IP address.\n\nErrors use a simplified body: `{\"error\": \"<message>\"}`.",
        "security": [],
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "LME reference, delivery barcode or booking reference.",
            "schema": {
              "type": "string"
            },
            "example": "LME9100123"
          }
        ],
        "responses": {
          "200": {
            "description": "The public tracking.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicTracking"
                },
                "example": {
                  "reference": "LME9100123",
                  "status": "in_customs",
                  "consignee_city": "Casablanca",
                  "events": [
                    {
                      "code": "EC",
                      "description": "Enregistrement e-commerce",
                      "datetime": "2026-03-04T09:12:40",
                      "location": ""
                    },
                    {
                      "code": "AR",
                      "description": "Arrivée au facility",
                      "datetime": "2026-03-06T08:15:00",
                      "location": "Under Customs - Morocco"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Unknown reference.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicError"
                },
                "example": {
                  "error": "Shipment not found"
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests per minute from this IP address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicError"
                },
                "example": {
                  "error": "Too many requests"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sandbox/scenarios": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "listSimulationScenarios",
        "summary": "List the simulation scenarios",
        "description": "**Sandbox only** (`404` in production).",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Available scenarios.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimulationScenariosResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not the sandbox: this path does not exist in production.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "production": {
                    "value": {
                      "error": {
                        "code": 404,
                        "message": "Not Found"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "servers": [
        {
          "url": "https://sandbox.lastmile.ma",
          "description": "Sandbox"
        }
      ]
    },
    "/api/v1/sandbox/shipments/{ref}/simulate": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "simulateShipment",
        "summary": "Move a sandbox shipment through a scenario",
        "description": "**Sandbox only** (`404` in production). Records the next steps of the scenario on one of your shipments, one second apart. Each status is a real tracking event: `GET /api/v1/shipments/{ref}/track`, `GET /api/v1/shipments/tracking/changes` and your status webhook (according to your webhook filter) see it exactly as they would see a scan in production.\n\nTypical test: create a shipment, play `steps: 1` (arrival), check that `PUT` and `DELETE` now answer `409`, then play the rest and check your webhook endpoint.\n\nLimited to 60 calls per minute per account.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "description": "Shipment reference (`LME…`), barcode or your order reference, as in the other shipment operations.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SimulationRequest"
              },
              "examples": {
                "one_step": {
                  "summary": "Arrival only",
                  "value": {
                    "scenario": "customs_hold_released",
                    "steps": 1
                  }
                },
                "all": {
                  "summary": "Whole scenario",
                  "value": {
                    "scenario": "delivered"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Steps recorded.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimulationResponse"
                },
                "example": {
                  "status": {
                    "code": 1,
                    "description": "Success"
                  },
                  "shipment": {
                    "reference": "LME9100123",
                    "state": "in_customs",
                    "last_status": "AX",
                    "customs": {
                      "customs_flow": "blocked",
                      "blocked": true,
                      "on_hold": true,
                      "on_hold_since": "2026-11-19T10:41:02Z"
                    }
                  },
                  "simulation": {
                    "scenario": "customs_hold_released",
                    "applied": [
                      "AR",
                      "IC",
                      "OH",
                      "CN",
                      "AX"
                    ],
                    "remaining": [
                      [
                        "CR"
                      ],
                      [
                        "DF",
                        "HN"
                      ],
                      [
                        "LV",
                        "WC"
                      ],
                      [
                        "OK"
                      ]
                    ],
                    "complete": false
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "scenario": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "Unknown scenario. Valid values: delivered, delivered_after_failed_attempt, customs_hold_released, customs_refused, prohibited_goods, refused_by_consignee"
                      }
                    }
                  },
                  "steps": {
                    "value": {
                      "error": {
                        "code": 400,
                        "message": "\"steps\" must be a positive integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ShipmentNotFound"
          },
          "409": {
            "description": "The shipment is cancelled, already follows another scenario, or its scenario is complete.",
            "headers": {
              "X-RateLimit-Limit": {
                "$ref": "#/components/headers/X-RateLimit-Limit"
              },
              "X-RateLimit-Remaining": {
                "$ref": "#/components/headers/X-RateLimit-Remaining"
              },
              "X-RateLimit-Window": {
                "$ref": "#/components/headers/X-RateLimit-Window"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "other": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "Shipment already follows scenario \"delivered\": create another shipment to try \"customs_refused\""
                      }
                    }
                  },
                  "complete": {
                    "value": {
                      "error": {
                        "code": 409,
                        "message": "Scenario \"delivered\" is already complete for this shipment"
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      },
      "servers": [
        {
          "url": "https://sandbox.lastmile.ma",
          "description": "Sandbox"
        }
      ]
    }
  },
  "webhooks": {
    "shipment.status": {
      "post": {
        "tags": [
          "Status webhook"
        ],
        "operationId": "onShipmentStatus",
        "summary": "Shipment status changed",
        "description": "Sent by LME to **your** URL each time an event selected for your account (`all`, `milestones` or `delivery`) is recorded on one of your shipments. One notification per event. JSON by default; XML (root element `LmeWebhook`, same fields) if you chose it.",
        "parameters": [
          {
            "name": "X-LME-Event",
            "in": "header",
            "required": true,
            "description": "Notification type.",
            "schema": {
              "type": "string",
              "enum": [
                "shipment.status",
                "ping"
              ]
            }
          },
          {
            "name": "X-LME-Delivery",
            "in": "header",
            "required": true,
            "description": "Unique delivery identifier, identical across retries: use it to discard duplicates.",
            "schema": {
              "type": "string"
            },
            "example": "48213"
          },
          {
            "name": "X-LME-Timestamp",
            "in": "header",
            "required": true,
            "description": "Unix time (seconds) of this attempt; part of the signed string.",
            "schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "example": "1789321212"
          },
          {
            "name": "X-LME-Signature",
            "in": "header",
            "required": false,
            "description": "`sha256=` + hex HMAC-SHA256 of `<X-LME-Timestamp>.<raw body>` with your shared secret. Present whenever a secret is configured on your account (always, once LME has enabled the webhook).",
            "schema": {
              "type": "string",
              "pattern": "^sha256=[0-9a-f]{64}$"
            },
            "example": "sha256=5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592"
          },
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "LME-Odoo-Webhook/1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookShipmentStatus"
              },
              "example": {
                "event": "shipment.status",
                "version": "1",
                "sent_at": "2026-09-12T17:40:12Z",
                "shipment": {
                  "reference": "LME9100123",
                  "shipper_reference": "SHOP-ORDER-12345",
                  "booking_reference": "",
                  "customer_account": "CUST-001",
                  "state": "in_customs",
                  "last_status": "IC",
                  "customs": {
                    "customs_flow": "simplified",
                    "on_hold": false,
                    "on_hold_since": "",
                    "mead_arrival": "2026-11-16T08:42:10Z",
                    "legal_deadline": "2026-12-31"
                  }
                },
                "status": {
                  "code": "IC",
                  "name": "Into Customs",
                  "label_fr": "Entrée en douane",
                  "phase": "warehouse",
                  "datetime": "2026-09-12T17:40:10Z",
                  "location": "Under Customs - Morocco",
                  "hub": "GTW1",
                  "description": "",
                  "source": "internal"
                }
              }
            },
            "application/xml": {
              "schema": {
                "type": "string"
              },
              "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><LmeWebhook><event>shipment.status</event><version>1</version><sent_at>2026-09-12T17:40:12Z</sent_at><shipment><reference>LME9100123</reference><shipper_reference>SHOP-ORDER-12345</shipper_reference><booking_reference></booking_reference><customer_account>CUST-001</customer_account><state>in_customs</state><last_status>IC</last_status><customs><customs_flow>simplified</customs_flow><on_hold>false</on_hold><on_hold_since></on_hold_since><mead_arrival>2026-11-16T08:42:10Z</mead_arrival><legal_deadline>2026-12-31</legal_deadline></customs></shipment><status><code>IC</code><name>Into Customs</name><label_fr>Entrée en douane</label_fr><phase>warehouse</phase><datetime>2026-09-12T17:40:10Z</datetime><location>Under Customs - Morocco</location><hub>GTW1</hub><description></description><source>internal</source></status></LmeWebhook>"
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Notification accepted. Answer within 5 seconds; the body is ignored."
          },
          "410": {
            "description": "Gone: LME stops retrying this delivery immediately."
          },
          "default": {
            "description": "Any other status, a timeout or a connection error: the delivery is retried (30 s, 1 min, 5 min, 15 min, 30 min, then hourly; 10 attempts in total)."
          }
        }
      }
    },
    "ping": {
      "post": {
        "tags": [
          "Status webhook"
        ],
        "operationId": "onPing",
        "summary": "Connectivity test",
        "description": "Sent when LME tests your endpoint (for example when enabling the webhook). Same headers, signature and retry policy as status notifications; answer `2xx`.",
        "parameters": [
          {
            "name": "X-LME-Event",
            "in": "header",
            "required": true,
            "description": "Notification type.",
            "schema": {
              "type": "string",
              "enum": [
                "shipment.status",
                "ping"
              ]
            }
          },
          {
            "name": "X-LME-Delivery",
            "in": "header",
            "required": true,
            "description": "Unique delivery identifier, identical across retries: use it to discard duplicates.",
            "schema": {
              "type": "string"
            },
            "example": "48213"
          },
          {
            "name": "X-LME-Timestamp",
            "in": "header",
            "required": true,
            "description": "Unix time (seconds) of this attempt; part of the signed string.",
            "schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "example": "1789321212"
          },
          {
            "name": "X-LME-Signature",
            "in": "header",
            "required": false,
            "description": "`sha256=` + hex HMAC-SHA256 of `<X-LME-Timestamp>.<raw body>` with your shared secret. Present whenever a secret is configured on your account (always, once LME has enabled the webhook).",
            "schema": {
              "type": "string",
              "pattern": "^sha256=[0-9a-f]{64}$"
            },
            "example": "sha256=5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592"
          },
          {
            "name": "User-Agent",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "LME-Odoo-Webhook/1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPing"
              },
              "example": {
                "event": "ping",
                "version": "1",
                "sent_at": "2026-09-12T17:38:00Z",
                "customer_account": "CUST-001"
              }
            },
            "application/xml": {
              "schema": {
                "type": "string"
              },
              "example": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><LmeWebhook><event>ping</event><version>1</version><sent_at>2026-09-12T17:38:00Z</sent_at><customer_account>CUST-001</customer_account></LmeWebhook>"
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Notification accepted. Answer within 5 seconds; the body is ignored."
          },
          "410": {
            "description": "Gone: LME stops retrying this delivery immediately."
          },
          "default": {
            "description": "Any other status, a timeout or a connection error: the delivery is retried (30 s, 1 min, 5 min, 15 min, 30 min, then hourly; 10 attempts in total)."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "64 hexadecimal characters",
        "description": "Token from `POST /api/v1/auth/token`, sent as `Authorization: Bearer <token>`. Valid 24 hours."
      }
    },
    "schemas": {
      "Status": {
        "type": "object",
        "description": "Success envelope. `code` is always `1` on a successful response.",
        "properties": {
          "code": {
            "type": "integer",
            "const": 1,
            "example": 1
          },
          "description": {
            "type": "string",
            "example": "Success"
          }
        },
        "required": [
          "code",
          "description"
        ]
      },
      "Error": {
        "type": "object",
        "description": "Error body. `error.code` repeats the HTTP status.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer",
                "example": 400
              },
              "message": {
                "type": "string",
                "example": "Invalid JSON body"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ],
        "example": {
          "error": {
            "code": 400,
            "message": "Invalid JSON body"
          }
        }
      },
      "TokenRequest": {
        "type": "object",
        "required": [
          "username",
          "password",
          "license"
        ],
        "properties": {
          "username": {
            "type": "string",
            "maxLength": 100,
            "description": "API username.",
            "example": "YOUR_USERNAME"
          },
          "password": {
            "type": "string",
            "format": "password",
            "maxLength": 200,
            "description": "API password.",
            "example": "YOUR_PASSWORD"
          },
          "license": {
            "type": "string",
            "maxLength": 100,
            "description": "License number.",
            "example": "YOUR_LICENSE_NUMBER"
          },
          "label": {
            "type": "string",
            "maxLength": 64,
            "description": "Optional name of the integration that will use the token (shown to LME support; kept on refresh).",
            "example": "woocommerce-shop"
          }
        },
        "example": {
          "username": "YOUR_USERNAME",
          "password": "YOUR_PASSWORD",
          "license": "YOUR_LICENSE_NUMBER"
        }
      },
      "TokenResponse": {
        "type": "object",
        "required": [
          "status",
          "auth"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "auth": {
            "type": "object",
            "required": [
              "token",
              "expires_at",
              "account",
              "customer_name"
            ],
            "properties": {
              "token": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "Bearer token, valid 24 hours. Adds to the account's other tokens, which keep working (at most 10 active tokens per account)."
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "UTC expiry time of the token (24 hours after issue).",
                "example": "2026-11-20T09:30:00Z"
              },
              "account": {
                "type": "string",
                "description": "Your LME customer account code.",
                "example": "CUST-001"
              },
              "customer_name": {
                "type": "string",
                "description": "Customer name registered at LME.",
                "example": "Sample Shop Ltd"
              }
            }
          }
        }
      },
      "RefreshResponse": {
        "type": "object",
        "required": [
          "status",
          "auth"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "auth": {
            "type": "object",
            "required": [
              "token",
              "expires_at",
              "account"
            ],
            "properties": {
              "token": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "New Bearer token, valid 24 hours. The token sent no longer works; the account's other tokens are not affected."
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "description": "UTC expiry time of the token (24 hours after issue).",
                "example": "2026-11-20T09:30:00Z"
              },
              "account": {
                "type": "string",
                "example": "CUST-001"
              }
            }
          }
        }
      },
      "StatusOnly": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          }
        }
      },
      "ShipmentInput": {
        "type": "object",
        "description": "A new shipment. The API does not enforce required fields, but a shipment cannot be cleared and delivered without the consignee name, phone, address and city, the weight and the items: always send them.",
        "properties": {
          "reference_number": {
            "type": "string",
            "description": "Your own order reference. It is returned as `shipper_reference` and can be used in place of the LME reference in every `{ref}` path parameter. Must not start with `=`.",
            "maxLength": 100,
            "example": "SHOP-ORDER-12345"
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DDP",
              "DDU"
            ],
            "default": "DDP",
            "description": "`DDP` (delivered duty paid) or `DDU` (delivered duty unpaid)."
          },
          "shipper_company": {
            "type": "string",
            "description": "Shipper company name. Must not start with `=`.",
            "maxLength": 500,
            "example": "Sample Export Co."
          },
          "shipper_contact": {
            "type": "string",
            "description": "Shipper contact person.",
            "maxLength": 500,
            "example": "Shipping Department"
          },
          "shipper_phone": {
            "type": "string",
            "maxLength": 30,
            "pattern": "^[\\d\\s+\\-().]{0,30}$",
            "description": "Shipper phone number.",
            "example": "+86 21 0000 0000"
          },
          "shipper_address1": {
            "type": "string",
            "description": "Shipper address line 1.",
            "maxLength": 500,
            "example": "123 Industrial Road"
          },
          "shipper_address2": {
            "type": "string",
            "description": "Shipper address line 2.",
            "maxLength": 500,
            "example": "Building B"
          },
          "shipper_address3": {
            "type": "string",
            "description": "Shipper address line 3.",
            "maxLength": 500,
            "example": ""
          },
          "shipper_zip": {
            "type": "string",
            "maxLength": 20,
            "pattern": "^[\\w\\s\\-]{0,20}$",
            "description": "Shipper postal code.",
            "example": "200000"
          },
          "shipper_city": {
            "type": "string",
            "description": "Shipper city.",
            "maxLength": 100,
            "example": "Shanghai"
          },
          "shipper_country": {
            "type": "string",
            "description": "Shipper country: ISO 3166-1 alpha-2 code (recommended) or English name. Any country other than Morocco makes the shipment cross-border.",
            "maxLength": 100,
            "example": "CN"
          },
          "consignee_name": {
            "type": "string",
            "description": "Consignee full name. Must not start with `=`.",
            "maxLength": 500,
            "example": "Ahmed Benali"
          },
          "consignee_contact": {
            "type": "string",
            "description": "Contact person, if different from the consignee.",
            "maxLength": 500,
            "example": "Ahmed Benali"
          },
          "consignee_phone": {
            "type": "string",
            "maxLength": 30,
            "pattern": "^[\\d\\s+\\-().]{0,30}$",
            "description": "Consignee phone number (used to arrange delivery).",
            "example": "+212 6 12 34 56 78"
          },
          "consignee_address1": {
            "type": "string",
            "description": "Address line 1.",
            "maxLength": 500,
            "example": "45 Rue Mohamed V"
          },
          "consignee_address2": {
            "type": "string",
            "description": "Address line 2.",
            "maxLength": 500,
            "example": "Apt 3"
          },
          "consignee_address3": {
            "type": "string",
            "description": "Address line 3.",
            "maxLength": 500,
            "example": ""
          },
          "consignee_zip": {
            "type": "string",
            "maxLength": 20,
            "pattern": "^[\\w\\s\\-]{0,20}$",
            "description": "Postal code.",
            "example": "20000"
          },
          "consignee_city": {
            "type": "string",
            "description": "City. LME resolves the destination hub from the city (and the postal code as a fallback).",
            "maxLength": 100,
            "example": "Casablanca"
          },
          "consignee_country": {
            "type": "string",
            "description": "Consignee country: ISO code or English name. Default `MA` (Morocco).",
            "maxLength": 100,
            "example": "MA"
          },
          "product_type": {
            "type": "string",
            "enum": [
              "P",
              "D"
            ],
            "default": "P",
            "description": "`P` = parcel, `D` = document."
          },
          "pieces": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999,
            "description": "Number of pieces. Default `1`.",
            "example": 1
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999,
            "description": "Declared weight in kg.",
            "example": 0.7
          },
          "description": {
            "type": "string",
            "description": "Description of the content. Must not start with `=`.",
            "maxLength": 2000,
            "example": "Phone accessories"
          },
          "declared_value": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Declared value of the content, in USD.",
            "example": 45.0
          },
          "cod_flag": {
            "type": "boolean",
            "default": false,
            "description": "Cash on delivery. **Prohibited for cross-border shipments** (shipper country other than Morocco): the request is then refused with `400`. For domestic shipments, LME either refuses the request or silently removes the cash-on-delivery data, depending on its configuration."
          },
          "cod_amount": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Amount to collect, in MAD (domestic shipments only).",
            "example": 0
          },
          "cod_payment_type": {
            "type": "string",
            "enum": [
              "cash",
              "cheque"
            ],
            "default": "cash",
            "description": "How the cash-on-delivery amount is paid (domestic shipments only)."
          },
          "special_instructions": {
            "type": "string",
            "description": "Delivery instructions.",
            "maxLength": 2000,
            "example": "Call before delivery"
          },
          "items": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ItemInput"
            },
            "description": "Customs invoice lines (at most 200)."
          }
        },
        "example": {
          "reference_number": "SHOP-ORDER-12345",
          "incoterm": "DDP",
          "shipper_company": "Sample Export Co.",
          "shipper_contact": "Shipping Department",
          "shipper_phone": "+86 21 0000 0000",
          "shipper_address1": "123 Industrial Road",
          "shipper_address2": "Building B",
          "shipper_zip": "200000",
          "shipper_city": "Shanghai",
          "shipper_country": "CN",
          "consignee_name": "Ahmed Benali",
          "consignee_contact": "Ahmed Benali",
          "consignee_phone": "+212 6 12 34 56 78",
          "consignee_address1": "45 Rue Mohamed V",
          "consignee_address2": "Apt 3",
          "consignee_zip": "20000",
          "consignee_city": "Casablanca",
          "consignee_country": "MA",
          "product_type": "P",
          "pieces": 1,
          "weight": 0.7,
          "description": "Phone accessories",
          "declared_value": 45.0,
          "special_instructions": "Call before delivery",
          "items": [
            {
              "hs_code": "8544429090",
              "description": "USB cable, type C",
              "quantity": 2,
              "unit_price": 15.0,
              "weight": 0.5,
              "origin_country": "CN"
            },
            {
              "hs_code": "3926909990",
              "description": "Phone case, plastic",
              "quantity": 1,
              "unit_price": 15.0,
              "weight": 0.2,
              "origin_country": "CN"
            }
          ]
        }
      },
      "ShipmentUpdate": {
        "type": "object",
        "description": "Fields to change. Send only what changes; only the fields below are taken into account (others are validated, then ignored). Shipper data, incoterm, product type and countries cannot be changed.",
        "properties": {
          "consignee_name": {
            "type": "string",
            "description": "Consignee full name. Must not start with `=`.",
            "maxLength": 500,
            "example": "Ahmed Benali"
          },
          "consignee_contact": {
            "type": "string",
            "description": "Contact person, if different from the consignee.",
            "maxLength": 500,
            "example": "Ahmed Benali"
          },
          "consignee_phone": {
            "type": "string",
            "maxLength": 30,
            "pattern": "^[\\d\\s+\\-().]{0,30}$",
            "description": "Consignee phone number (used to arrange delivery).",
            "example": "+212 6 12 34 56 78"
          },
          "consignee_address1": {
            "type": "string",
            "description": "Address line 1.",
            "maxLength": 500,
            "example": "45 Rue Mohamed V"
          },
          "consignee_address2": {
            "type": "string",
            "description": "Address line 2.",
            "maxLength": 500,
            "example": "Apt 3"
          },
          "consignee_address3": {
            "type": "string",
            "description": "Address line 3.",
            "maxLength": 500,
            "example": ""
          },
          "consignee_zip": {
            "type": "string",
            "maxLength": 20,
            "pattern": "^[\\w\\s\\-]{0,20}$",
            "description": "Postal code.",
            "example": "20000"
          },
          "consignee_city": {
            "type": "string",
            "description": "City. LME resolves the destination hub from the city (and the postal code as a fallback).",
            "maxLength": 100,
            "example": "Casablanca"
          },
          "pieces": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999,
            "description": "Number of pieces. Default `1`.",
            "example": 1
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999,
            "description": "Declared weight in kg.",
            "example": 0.7
          },
          "description": {
            "type": "string",
            "description": "Description of the content. Must not start with `=`.",
            "maxLength": 2000,
            "example": "Phone accessories"
          },
          "declared_value": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Declared value of the content, in USD.",
            "example": 45.0
          },
          "cod_flag": {
            "type": "boolean",
            "default": false,
            "description": "Cash on delivery. **Prohibited for cross-border shipments** (shipper country other than Morocco): the request is then refused with `400`. For domestic shipments, LME either refuses the request or silently removes the cash-on-delivery data, depending on its configuration."
          },
          "cod_amount": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Amount to collect, in MAD (domestic shipments only).",
            "example": 0
          },
          "special_instructions": {
            "type": "string",
            "description": "Delivery instructions.",
            "maxLength": 2000,
            "example": "Leave at reception"
          },
          "items": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ItemInput"
            },
            "description": "Customs invoice lines. When present, **replaces all** existing lines (at most 200)."
          }
        },
        "example": {
          "consignee_phone": "+212 6 98 76 54 32",
          "consignee_address1": "99 Boulevard Hassan II",
          "consignee_city": "Rabat",
          "weight": 0.9,
          "special_instructions": "Leave at reception"
        }
      },
      "ItemInput": {
        "type": "object",
        "description": "One customs invoice line.",
        "properties": {
          "hs_code": {
            "type": "string",
            "description": "HS / commodity code as known to you. LME verifies it against the Moroccan tariff.",
            "maxLength": 30,
            "example": "8544429090"
          },
          "description": {
            "type": "string",
            "description": "Item description, as precise as possible (material, use). Must not start with `=`.",
            "maxLength": 500,
            "example": "USB cable, type C"
          },
          "quantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999,
            "description": "Quantity. Default `1`.",
            "example": 2
          },
          "unit_price": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Unit price, in USD.",
            "example": 15.0
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999,
            "description": "Weight of the line, in kg.",
            "example": 0.5
          },
          "origin_country": {
            "type": "string",
            "description": "Country of origin: ISO code (`CN`, `TR`…) or English name.",
            "maxLength": 100,
            "example": "CN"
          }
        },
        "example": {
          "hs_code": "8544429090",
          "description": "USB cable, type C",
          "quantity": 2,
          "unit_price": 15.0,
          "weight": 0.5,
          "origin_country": "CN"
        }
      },
      "Item": {
        "type": "object",
        "description": "A customs invoice line as stored by LME.",
        "properties": {
          "hs_code": {
            "type": "string",
            "example": "8544429090"
          },
          "description": {
            "type": "string",
            "example": "USB cable, type C"
          },
          "quantity": {
            "type": "integer",
            "example": 2
          },
          "unit_price": {
            "type": "number",
            "description": "USD.",
            "example": 15.0
          },
          "weight": {
            "type": "number",
            "description": "kg.",
            "example": 0.5
          },
          "origin_country": {
            "type": "string",
            "description": "ISO code, or empty when unknown.",
            "example": "CN"
          }
        },
        "required": [
          "hs_code",
          "description",
          "quantity",
          "unit_price",
          "weight",
          "origin_country"
        ]
      },
      "ShipmentCreated": {
        "type": "object",
        "required": [
          "status",
          "shipment"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "type": "object",
            "required": [
              "reference",
              "shipper_reference",
              "weight",
              "pieces",
              "box_number",
              "destination_hub",
              "items"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "description": "LME reference — keep it: it identifies the shipment in every other call.",
                "example": "LME9100123"
              },
              "shipper_reference": {
                "type": "string",
                "description": "Your `reference_number`.",
                "example": "SHOP-ORDER-12345"
              },
              "weight": {
                "type": "number",
                "example": 0.7
              },
              "pieces": {
                "type": "integer",
                "example": 1
              },
              "box_number": {
                "type": "string",
                "description": "Carton the shipment was scanned into; empty at creation.",
                "example": ""
              },
              "destination_hub": {
                "type": "string",
                "description": "Destination hub code resolved from the consignee city; empty when the city is unknown (assigned later by LME).",
                "example": "CAS"
              },
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          }
        }
      },
      "Shipment": {
        "type": "object",
        "description": "A shipment as known to LME.",
        "required": [
          "reference",
          "shipper_reference",
          "state",
          "last_status_code",
          "customs",
          "incoterm",
          "weight",
          "pieces",
          "declared_value",
          "cod_flag",
          "cod_amount",
          "consignee_name",
          "consignee_city",
          "consignee_country",
          "box_number",
          "destination_hub",
          "items"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "example": "LME9100123"
          },
          "shipper_reference": {
            "type": "string",
            "example": "SHOP-ORDER-12345"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "registered",
              "in_customs",
              "cleared",
              "dispatched",
              "in_delivery",
              "delivered",
              "failed",
              "returned",
              "cancelled"
            ],
            "description": "Lifecycle state (see Tracking).",
            "example": "in_customs"
          },
          "last_status_code": {
            "type": "string",
            "description": "Code of the latest event visible to you (see Event codes). Internal codes are never returned.",
            "example": "IC"
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DDP",
              "DDU",
              ""
            ],
            "example": "DDP"
          },
          "weight": {
            "type": "number",
            "description": "Declared weight, kg.",
            "example": 0.7
          },
          "pieces": {
            "type": "integer",
            "example": 1
          },
          "declared_value": {
            "type": "number",
            "description": "USD.",
            "example": 45.0
          },
          "cod_flag": {
            "type": "boolean",
            "example": false
          },
          "cod_amount": {
            "type": "number",
            "description": "MAD.",
            "example": 0.0
          },
          "consignee_name": {
            "type": "string",
            "example": "Ahmed Benali"
          },
          "consignee_city": {
            "type": "string",
            "example": "Casablanca"
          },
          "consignee_country": {
            "type": "string",
            "description": "Country name.",
            "example": "Morocco"
          },
          "box_number": {
            "type": "string",
            "description": "Carton the shipment was scanned into at LME, if any.",
            "example": "CTN-042"
          },
          "destination_hub": {
            "type": "string",
            "description": "Destination hub code, if resolved.",
            "example": "CAS"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "customs": {
            "$ref": "#/components/schemas/Customs"
          }
        }
      },
      "ShipmentResponse": {
        "type": "object",
        "required": [
          "status",
          "shipment"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "$ref": "#/components/schemas/Shipment"
          }
        }
      },
      "ShipmentRefResponse": {
        "type": "object",
        "required": [
          "status",
          "shipment"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "type": "object",
            "required": [
              "reference"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "example": "LME9100123"
              }
            }
          }
        }
      },
      "TrackingEvent": {
        "type": "object",
        "description": "One tracking event. Date and time are UTC.",
        "required": [
          "code",
          "description",
          "date",
          "time",
          "location"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Event code (see the table in Tracking).",
            "example": "IC"
          },
          "description": {
            "type": "string",
            "description": "Official label of the event code.",
            "example": "Entrée en douane"
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-03-06"
          },
          "time": {
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}:\\d{2}$",
            "example": "08:15:05"
          },
          "location": {
            "type": "string",
            "example": "Under Customs - Morocco"
          }
        }
      },
      "TrackingResponse": {
        "type": "object",
        "required": [
          "status",
          "shipment",
          "events"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "type": "object",
            "required": [
              "consignment_number",
              "reference_number"
            ],
            "properties": {
              "consignment_number": {
                "type": "string",
                "description": "LME reference.",
                "example": "LME9100123"
              },
              "reference_number": {
                "type": "string",
                "description": "Your order reference.",
                "example": "SHOP-ORDER-12345"
              }
            }
          },
          "events": {
            "type": "array",
            "description": "Every event, oldest first.",
            "items": {
              "$ref": "#/components/schemas/TrackingEvent"
            }
          }
        }
      },
      "ChangeEvent": {
        "type": "object",
        "required": [
          "id",
          "code",
          "description",
          "datetime",
          "location",
          "agent_code"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier of the event. An event can be sent twice across consecutive calls (at-least-once delivery): use `id` to ignore duplicates.",
            "example": 184467
          },
          "code": {
            "type": "string",
            "example": "IC"
          },
          "description": {
            "type": "string",
            "example": "Entrée en douane",
            "description": "Official label of the event code."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "description": "UTC.",
            "example": "2026-03-19T14:30:00Z"
          },
          "location": {
            "type": "string",
            "example": "Under Customs - Morocco"
          },
          "agent_code": {
            "type": "string",
            "description": "Code of the LME agent who recorded the event, if any.",
            "example": "AG01"
          }
        }
      },
      "ChangedShipment": {
        "type": "object",
        "required": [
          "tracking_number",
          "shipper_reference",
          "current_status",
          "current_status_label",
          "state",
          "last_update",
          "destination_hub",
          "new_events",
          "customs"
        ],
        "properties": {
          "tracking_number": {
            "type": "string",
            "description": "LME reference.",
            "example": "LME9100123"
          },
          "shipper_reference": {
            "type": "string",
            "example": "SHOP-ORDER-12345"
          },
          "current_status": {
            "type": "string",
            "description": "Code of the latest event visible to you.",
            "example": "IC"
          },
          "current_status_label": {
            "type": "string",
            "description": "English label of `state`.",
            "example": "In Customs"
          },
          "state": {
            "type": "string",
            "enum": [
              "draft",
              "registered",
              "in_customs",
              "cleared",
              "dispatched",
              "in_delivery",
              "delivered",
              "failed",
              "returned",
              "cancelled"
            ],
            "example": "in_customs"
          },
          "last_update": {
            "type": "string",
            "format": "date-time",
            "description": "UTC time of the latest status change.",
            "example": "2026-03-19T14:30:00Z"
          },
          "destination_hub": {
            "type": "string",
            "example": "CAS"
          },
          "new_events": {
            "type": "array",
            "description": "Only the events after `since`, oldest first.",
            "items": {
              "$ref": "#/components/schemas/ChangeEvent"
            }
          },
          "customs": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Customs"
              },
              {
                "type": "null"
              }
            ],
            "description": "Customs situation; `null` for a pre-alert entry not yet received."
          }
        }
      },
      "TrackingChangesResponse": {
        "type": "object",
        "required": [
          "status",
          "since",
          "until",
          "total_changed",
          "has_more",
          "next_cursor",
          "shipments"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "since": {
            "type": "string",
            "format": "date-time",
            "description": "The `since` that was applied (UTC)."
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "description": "Latest status change in this page; equals `since` when nothing changed. Store it and use it as the next `since`."
          },
          "total_changed": {
            "type": "integer",
            "description": "Number of shipments in this page."
          },
          "has_more": {
            "type": "boolean",
            "description": "`true` when the page is full: call again with `cursor` = `next_cursor`."
          },
          "next_cursor": {
            "type": "string",
            "description": "Value to pass as `cursor` (or `since`) for the next page; empty when `has_more` is `false`."
          },
          "shipments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangedShipment"
            }
          }
        },
        "example": {
          "status": {
            "code": 1,
            "description": "Success"
          },
          "since": "2026-03-19T10:00:00Z",
          "until": "2026-03-19T14:30:00Z",
          "total_changed": 1,
          "has_more": false,
          "next_cursor": "",
          "shipments": [
            {
              "tracking_number": "LME9100123",
              "shipper_reference": "SHOP-ORDER-12345",
              "current_status": "IC",
              "current_status_label": "In Customs",
              "state": "in_customs",
              "last_update": "2026-03-19T14:30:00Z",
              "destination_hub": "CAS",
              "new_events": [
                {
                  "id": 184467,
                  "code": "AR",
                  "description": "Arrivée au facility",
                  "datetime": "2026-03-19T14:29:55Z",
                  "location": "Under Customs - Morocco",
                  "agent_code": "AG01"
                },
                {
                  "id": 184468,
                  "code": "IC",
                  "description": "Entrée en douane",
                  "datetime": "2026-03-19T14:30:00Z",
                  "location": "Under Customs - Morocco",
                  "agent_code": "AG01"
                }
              ],
              "customs": {
                "customs_flow": "simplified",
                "on_hold": false,
                "on_hold_since": "",
                "mead_arrival": "2026-11-16T08:42:10Z",
                "legal_deadline": "2026-12-31"
              }
            }
          ]
        }
      },
      "LabelResponse": {
        "type": "object",
        "required": [
          "status",
          "shipment",
          "label",
          "label_format",
          "label_encoding"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "type": "object",
            "required": [
              "reference"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "example": "LME9100123"
              }
            }
          },
          "label": {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": "application/pdf",
            "description": "The label as a base64-encoded PDF. **Empty string** if the PDF could not be generated: retry later, then contact LME."
          },
          "label_format": {
            "type": "string",
            "const": "PDF"
          },
          "label_encoding": {
            "type": "string",
            "const": "base64"
          }
        }
      },
      "PrealertInput": {
        "type": "object",
        "required": [
          "mawb"
        ],
        "description": "A flight carrying your shipments.",
        "properties": {
          "mawb": {
            "type": "string",
            "minLength": 3,
            "maxLength": 20,
            "pattern": "^[0-9A-Za-z][0-9A-Za-z-]{2,19}$",
            "description": "Master air waybill: airline prefix and number, letters, digits and dashes (3 to 20 characters).",
            "example": "999-12345678"
          },
          "flight_number": {
            "type": "string",
            "maxLength": 100,
            "description": "Flight number. Always send it.",
            "example": "XX1234"
          },
          "departure_airport": {
            "type": "string",
            "maxLength": 10,
            "description": "IATA code.",
            "example": "PVG"
          },
          "arrival_airport": {
            "type": "string",
            "maxLength": 10,
            "default": "CMN",
            "description": "IATA code.",
            "example": "CMN"
          },
          "departure_date": {
            "type": "string",
            "description": "Flight date, `YYYY-MM-DD` (a time part `YYYY-MM-DD HH:MM:SS` is accepted and ignored). `flight_date` is accepted as an alias.",
            "example": "2026-03-10"
          },
          "flight_date": {
            "type": "string",
            "description": "Alias of `departure_date`.",
            "example": "2026-03-10"
          },
          "arrival_date": {
            "type": "string",
            "description": "Arrival date, `YYYY-MM-DD`.",
            "example": "2026-03-11"
          }
        },
        "example": {
          "flight_number": "XX1234",
          "mawb": "999-12345678",
          "departure_airport": "PVG",
          "arrival_airport": "CMN",
          "departure_date": "2026-03-10",
          "arrival_date": "2026-03-11"
        }
      },
      "PrealertResponse": {
        "type": "object",
        "required": [
          "status",
          "prealert"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "prealert": {
            "type": "object",
            "required": [
              "flight",
              "mawb",
              "manifest"
            ],
            "properties": {
              "flight": {
                "type": "string",
                "example": "XX1234"
              },
              "mawb": {
                "type": "string",
                "example": "999-12345678"
              },
              "manifest": {
                "type": "string",
                "description": "Pre-alert manifest reference, used to delete it.",
                "example": "MAN-00007"
              }
            }
          }
        }
      },
      "ManifestEntry": {
        "type": "object",
        "required": [
          "reference"
        ],
        "description": "Verified data for one shipment. Only the fields you send are changed.",
        "properties": {
          "reference": {
            "type": "string",
            "maxLength": 100,
            "description": "LME reference or your `reference_number`. Must not start with `=`.",
            "example": "LME9100123"
          },
          "actual_weight": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 999999,
            "description": "Re-weighed weight in kg; printed on the label instead of the declared weight.",
            "example": 0.8
          },
          "declared_value": {
            "type": "number",
            "minimum": 0,
            "maximum": 9999999,
            "description": "Verified declared value, USD.",
            "example": 45.0
          },
          "box_number": {
            "type": "string",
            "description": "Your carton number. Must not start with `=`.",
            "maxLength": 100,
            "example": "CTN-001"
          },
          "pieces": {
            "type": "integer",
            "minimum": 0,
            "maximum": 99999,
            "description": "Verified number of pieces.",
            "example": 1
          },
          "description": {
            "type": "string",
            "description": "Updated description of the content. Must not start with `=`.",
            "maxLength": 2000
          },
          "items": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ItemInput"
            },
            "description": "Verified customs lines. When present and not empty, **replaces all** lines."
          }
        }
      },
      "ManifestRequest": {
        "type": "object",
        "required": [
          "shipments"
        ],
        "properties": {
          "shipments": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ManifestEntry"
            }
          }
        },
        "example": {
          "shipments": [
            {
              "reference": "LME9100123",
              "actual_weight": 0.8,
              "declared_value": 45.0,
              "box_number": "CTN-001",
              "pieces": 1,
              "items": [
                {
                  "hs_code": "8544429090",
                  "description": "USB cable, type C",
                  "quantity": 2,
                  "unit_price": 15.0,
                  "weight": 0.5,
                  "origin_country": "CN"
                },
                {
                  "hs_code": "3926909990",
                  "description": "Phone case, plastic",
                  "quantity": 1,
                  "unit_price": 15.0,
                  "weight": 0.2,
                  "origin_country": "CN"
                }
              ]
            },
            {
              "reference": "SHOP-ORDER-12399",
              "actual_weight": 1.2,
              "box_number": "CTN-001"
            }
          ]
        }
      },
      "ManifestShipmentResult": {
        "type": "object",
        "required": [
          "reference",
          "shipper_reference",
          "status",
          "actual_weight",
          "declared_value",
          "pieces",
          "box_number",
          "destination_hub"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "example": "LME9100123"
          },
          "shipper_reference": {
            "type": "string",
            "example": "SHOP-ORDER-12345"
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "updated"
            ],
            "description": "`created` the first time a reference is finalized, `updated` afterwards."
          },
          "actual_weight": {
            "type": "number",
            "description": "Re-weighed weight, or the declared weight when none was sent.",
            "example": 0.8
          },
          "declared_value": {
            "type": "number",
            "example": 45.0
          },
          "pieces": {
            "type": "integer",
            "example": 1
          },
          "box_number": {
            "type": "string",
            "example": "CTN-001"
          },
          "destination_hub": {
            "type": "string",
            "example": "CAS"
          }
        }
      },
      "ManifestError": {
        "type": "object",
        "required": [
          "reference",
          "error"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "example": "SHOP-ORDER-12399"
          },
          "error": {
            "type": "string",
            "example": "Shipment not found"
          }
        }
      },
      "ManifestResponse": {
        "type": "object",
        "required": [
          "status",
          "manifest"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "manifest": {
            "type": "object",
            "required": [
              "total_submitted",
              "total_updated",
              "total_errors",
              "shipments",
              "errors"
            ],
            "properties": {
              "total_submitted": {
                "type": "integer"
              },
              "total_updated": {
                "type": "integer",
                "description": "Entries processed (created or updated)."
              },
              "total_errors": {
                "type": "integer"
              },
              "shipments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ManifestShipmentResult"
                }
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ManifestError"
                }
              }
            }
          }
        }
      },
      "ShopItem": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Product title or description (only the first 500 characters are used).",
            "example": "USB cable, type C"
          },
          "hs_code": {
            "type": "string",
            "description": "HS code you already have, if any (first 20 characters used). Remapped to the Moroccan tariff.",
            "example": "854442"
          }
        }
      },
      "ShopQuoteItem": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Product title or description (first 500 characters used).",
            "example": "USB cable, type C"
          },
          "hs_code": {
            "type": "string",
            "description": "HS code you already have, if any.",
            "example": "854442"
          },
          "unit_value": {
            "type": "number",
            "minimum": 0,
            "description": "Unit price in the request currency. A negative value counts as 0.",
            "example": 15.0
          },
          "quantity": {
            "type": "number",
            "minimum": 1,
            "default": 1,
            "description": "Quantity; values below 1 count as 1.",
            "example": 2
          }
        }
      },
      "HsCodeRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ShopItem"
            }
          }
        },
        "example": {
          "items": [
            {
              "description": "USB cable, type C",
              "hs_code": "854442"
            },
            {
              "description": "Gift set"
            }
          ]
        }
      },
      "HsCodeResult": {
        "type": "object",
        "required": [
          "hs_code",
          "method",
          "designation",
          "duty_rate",
          "description"
        ],
        "properties": {
          "hs_code": {
            "type": "string",
            "description": "Moroccan tariff position (10 digits), or empty when it could not be determined with confidence.",
            "example": "8544429090"
          },
          "method": {
            "type": "string",
            "enum": [
              "historique",
              "declare",
              "adil",
              "adil_defaut",
              "non_resolu"
            ],
            "description": "How the position was found: `historique` = from earlier customs declarations of the same product; `declare` = the HS code you sent, confirmed; `adil` = your HS code remapped to a single tariff position; `adil_defaut` = remapped to a default position among several (to be checked); `non_resolu` = not found, never guessed.",
            "example": "adil"
          },
          "designation": {
            "type": "string",
            "description": "Official designation of the position (French)."
          },
          "duty_rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Import duty rate of the position, in %; `null` when unresolved.",
            "example": 17.5
          },
          "description": {
            "type": "string",
            "description": "Your description, echoed."
          }
        }
      },
      "HsCodeResponse": {
        "type": "object",
        "required": [
          "items"
        ],
        "description": "One result per item, in the order of the request. No `status` envelope.",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HsCodeResult"
            }
          }
        }
      },
      "QuoteRequest": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "ISO 4217 code of `unit_value` and of `total`. USD and MAD are always available.",
            "example": "USD"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ShopQuoteItem"
            }
          }
        },
        "example": {
          "currency": "USD",
          "items": [
            {
              "description": "USB cable, type C",
              "hs_code": "854442",
              "unit_value": 15.0,
              "quantity": 2
            }
          ]
        }
      },
      "QuoteTax": {
        "type": "object",
        "required": [
          "code",
          "label",
          "rate",
          "base_mad",
          "amount_mad"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Moroccan customs tax code: `000110` import duty, `007217` parafiscal tax, `004801` environment fund (plastics), `002109` VAT.",
            "example": "000110"
          },
          "label": {
            "type": "string",
            "example": "Droit d'importation"
          },
          "rate": {
            "type": "number",
            "description": "%.",
            "example": 17.5
          },
          "base_mad": {
            "type": "number",
            "description": "Taxable base in MAD.",
            "example": 276.0
          },
          "amount_mad": {
            "type": "integer",
            "description": "Amount in MAD, rounded up to the dirham (at least 1).",
            "example": 49
          }
        }
      },
      "QuoteLine": {
        "type": "object",
        "required": [
          "description",
          "quantity",
          "value_mad",
          "hs_code",
          "method",
          "designation",
          "taxes",
          "total_mad"
        ],
        "properties": {
          "description": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "value_mad": {
            "type": "number",
            "description": "Line value (unit value × quantity) in MAD."
          },
          "hs_code": {
            "type": "string",
            "description": "Resolved tariff position; empty when unresolved."
          },
          "method": {
            "type": "string",
            "enum": [
              "historique",
              "declare",
              "adil",
              "adil_defaut",
              "non_resolu"
            ]
          },
          "designation": {
            "type": "string"
          },
          "taxes": {
            "type": "array",
            "description": "Empty when the position is unresolved.",
            "items": {
              "$ref": "#/components/schemas/QuoteTax"
            }
          },
          "total_mad": {
            "type": "integer",
            "description": "Sum of the line taxes, MAD."
          }
        }
      },
      "QuoteResponse": {
        "type": "object",
        "description": "Duty and tax estimate. No `status` envelope.",
        "required": [
          "currency",
          "rate_to_mad",
          "complete",
          "items",
          "totals_mad",
          "total_mad",
          "total",
          "disclaimer"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "rate_to_mad": {
            "type": "number",
            "description": "Exchange rate applied (1 unit of `currency` in MAD)."
          },
          "complete": {
            "type": "boolean",
            "description": "`false` when at least one item could not be classified: its taxes are then missing from the totals."
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteLine"
            }
          },
          "totals_mad": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Total per tax code, MAD."
          },
          "total_mad": {
            "type": "integer",
            "description": "Total duties and taxes, MAD."
          },
          "total": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total duties and taxes converted to `currency`."
          },
          "disclaimer": {
            "type": "string",
            "description": "Legal notice (French) to show with the estimate: the final amount is the one assessed by customs."
          }
        }
      },
      "PublicTracking": {
        "type": "object",
        "required": [
          "reference",
          "status",
          "consignee_city",
          "events"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "example": "LME9100123"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "registered",
              "in_customs",
              "cleared",
              "dispatched",
              "in_delivery",
              "delivered",
              "failed",
              "returned",
              "cancelled"
            ],
            "description": "Shipment state.",
            "example": "in_customs"
          },
          "consignee_city": {
            "type": "string",
            "example": "Casablanca"
          },
          "events": {
            "type": "array",
            "description": "Consumer-visible events only, oldest first.",
            "items": {
              "type": "object",
              "required": [
                "code",
                "description",
                "datetime",
                "location"
              ],
              "properties": {
                "code": {
                  "type": "string",
                  "example": "AR"
                },
                "description": {
                  "type": "string",
                  "description": "French label of the event code.",
                  "example": "Arrivée au facility"
                },
                "datetime": {
                  "type": "string",
                  "description": "UTC, ISO 8601 without offset.",
                  "example": "2026-03-06T08:15:00"
                },
                "location": {
                  "type": "string",
                  "example": "Under Customs - Morocco"
                }
              }
            }
          }
        }
      },
      "PublicError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "Shipment not found"
          }
        }
      },
      "WebhookShipmentStatus": {
        "type": "object",
        "description": "Body of a `shipment.status` notification (JSON format).",
        "required": [
          "event",
          "version",
          "sent_at",
          "shipment",
          "status"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "shipment.status"
          },
          "version": {
            "type": "string",
            "const": "1",
            "description": "Payload version."
          },
          "sent_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC time the notification was built."
          },
          "shipment": {
            "type": "object",
            "required": [
              "reference",
              "shipper_reference",
              "booking_reference",
              "customer_account",
              "state",
              "last_status",
              "customs"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "description": "LME reference."
              },
              "shipper_reference": {
                "type": "string",
                "description": "Your `reference_number`."
              },
              "booking_reference": {
                "type": "string"
              },
              "customer_account": {
                "type": "string",
                "description": "Your LME account code."
              },
              "state": {
                "type": "string",
                "enum": [
                  "draft",
                  "registered",
                  "in_customs",
                  "cleared",
                  "dispatched",
                  "in_delivery",
                  "delivered",
                  "failed",
                  "returned",
                  "cancelled"
                ],
                "description": "Shipment state when the notification was built."
              },
              "last_status": {
                "type": "string",
                "description": "Code of the event this notification is about."
              },
              "customs": {
                "$ref": "#/components/schemas/Customs"
              }
            }
          },
          "status": {
            "type": "object",
            "description": "The event that triggered this notification.",
            "required": [
              "code",
              "name",
              "label_fr",
              "phase",
              "datetime",
              "location",
              "hub",
              "description",
              "source"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Event code (see Tracking)."
              },
              "name": {
                "type": "string",
                "description": "English name of the code."
              },
              "label_fr": {
                "type": "string",
                "description": "French label of the code."
              },
              "phase": {
                "type": "string",
                "enum": [
                  "ecommerce",
                  "preparation",
                  "pickup",
                  "warehouse",
                  "customs",
                  "delivery",
                  "exception",
                  ""
                ]
              },
              "datetime": {
                "type": "string",
                "format": "date-time",
                "description": "UTC time of the event — use it to order notifications."
              },
              "location": {
                "type": "string"
              },
              "hub": {
                "type": "string",
                "description": "LME hub or route code."
              },
              "description": {
                "type": "string",
                "description": "Free comment, often empty."
              },
              "source": {
                "type": "string",
                "description": "Where the event came from: `internal` (LME), `api`, or the last-mile carrier."
              }
            }
          }
        }
      },
      "WebhookPing": {
        "type": "object",
        "description": "Body of a `ping` notification, sent when LME tests your endpoint.",
        "required": [
          "event",
          "version",
          "sent_at",
          "customer_account"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ping"
          },
          "version": {
            "type": "string",
            "const": "1"
          },
          "sent_at": {
            "type": "string",
            "format": "date-time"
          },
          "customer_account": {
            "type": "string"
          }
        }
      },
      "Customs": {
        "type": "object",
        "description": "Customs situation of the shipment. A shipment on hold keeps the `in_customs` state: read `on_hold` here.",
        "required": [
          "customs_flow",
          "on_hold",
          "on_hold_since",
          "mead_arrival",
          "legal_deadline"
        ],
        "properties": {
          "customs_flow": {
            "type": "string",
            "enum": [
              "simplified",
              "blocked"
            ],
            "description": "`simplified`: normal e-commerce clearance. `blocked`: the shipment has been put on hold at least once and is cleared individually; it stays `blocked` after its release.",
            "example": "simplified"
          },
          "on_hold": {
            "type": "boolean",
            "description": "`true` while the shipment waits after being put on hold: notifying the consignee (`CN`) or waiting for the customer's clearance (`AX`) does not end the hold; payment and clearance (`CP`), release (`CR`) and later steps, or a final outcome (`CF`, `PG`, `DC`, `US`…) do.",
            "example": false
          },
          "on_hold_since": {
            "type": "string",
            "description": "UTC date-time of the latest hold, empty when not on hold.",
            "example": ""
          },
          "mead_arrival": {
            "type": "string",
            "description": "UTC date-time of the first scan in the bonded warehouse (MEAD), empty before arrival.",
            "example": "2026-11-16T08:42:10Z"
          },
          "legal_deadline": {
            "type": "string",
            "description": "Date (YYYY-MM-DD) after which unclaimed goods are transferred to customs: MEAD arrival + 45 days. Empty before arrival.",
            "example": "2026-12-31"
          }
        }
      },
      "SimulationScenario": {
        "type": "object",
        "required": [
          "name",
          "description",
          "steps"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Value to send as `scenario`.",
            "examples": [
              "delivered"
            ]
          },
          "description": {
            "type": "string"
          },
          "steps": {
            "type": "array",
            "description": "Steps in order. Each step is a list of status codes recorded together (for example `AR` and `IC`: arrival at the bonded warehouse and entry into customs). `OH` (customs hold) is internal: it is never sent by webhook, but the `customs` block of the following statuses shows it.",
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "examples": [
              [
                [
                  "AR",
                  "IC"
                ],
                [
                  "CR"
                ],
                [
                  "DF",
                  "HN"
                ],
                [
                  "LV",
                  "WC"
                ],
                [
                  "OK"
                ]
              ]
            ]
          }
        }
      },
      "SimulationScenariosResponse": {
        "type": "object",
        "required": [
          "status",
          "scenarios"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "scenarios": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SimulationScenario"
            }
          }
        }
      },
      "SimulationRequest": {
        "type": "object",
        "required": [
          "scenario"
        ],
        "additionalProperties": false,
        "properties": {
          "scenario": {
            "type": "string",
            "enum": [
              "delivered",
              "delivered_after_failed_attempt",
              "customs_hold_released",
              "customs_refused",
              "prohibited_goods",
              "refused_by_consignee"
            ],
            "description": "Scenario to follow. A shipment follows one scenario only: create another shipment to try another one."
          },
          "steps": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of steps to play now. Omit it to play every remaining step. Call again with the same scenario to continue."
          }
        }
      },
      "SimulationResponse": {
        "type": "object",
        "required": [
          "status",
          "shipment",
          "simulation"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/Status"
          },
          "shipment": {
            "type": "object",
            "required": [
              "reference",
              "state",
              "last_status",
              "customs"
            ],
            "properties": {
              "reference": {
                "type": "string"
              },
              "state": {
                "type": "string",
                "description": "Same values as `state` in the shipment and the webhook."
              },
              "last_status": {
                "type": "string",
                "description": "Last status code you can see (internal codes such as `OH` are not shown)."
              },
              "customs": {
                "$ref": "#/components/schemas/Customs"
              }
            }
          },
          "simulation": {
            "type": "object",
            "required": [
              "scenario",
              "applied",
              "remaining",
              "complete"
            ],
            "properties": {
              "scenario": {
                "type": "string"
              },
              "applied": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Status codes recorded by this call, in order."
              },
              "remaining": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "description": "Steps still to play."
              },
              "complete": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, invalid, revoked or expired token.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Window": {
            "$ref": "#/components/headers/X-RateLimit-Window"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "missing": {
                "value": {
                  "error": {
                    "code": 401,
                    "message": "Missing or invalid Authorization header — use \"Bearer <token>\" obtained from POST /api/v1/auth/token"
                  }
                },
                "summary": "No Bearer header"
              },
              "invalid": {
                "value": {
                  "error": {
                    "code": 401,
                    "message": "Invalid token"
                  }
                },
                "summary": "Unknown, revoked or replaced token"
              },
              "expired": {
                "value": {
                  "error": {
                    "code": 401,
                    "message": "Token expired — please re-authenticate"
                  }
                },
                "summary": "Token older than 24 hours"
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded, per IP address or per API account.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Window": {
            "$ref": "#/components/headers/X-RateLimit-Window"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "ip": {
                "value": {
                  "error": {
                    "code": 429,
                    "message": "Too many requests"
                  }
                },
                "summary": "Per-IP limit"
              },
              "account": {
                "value": {
                  "error": {
                    "code": 429,
                    "message": "Too many requests for this API account"
                  }
                },
                "summary": "Per-account quota"
              }
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "Request body larger than 1 MB.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Window": {
            "$ref": "#/components/headers/X-RateLimit-Window"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "too_large": {
                "value": {
                  "error": {
                    "code": 413,
                    "message": "Request body too large (max 1024KB)"
                  }
                }
              }
            }
          }
        }
      },
      "ShipmentNotFound": {
        "description": "No shipment with this reference **in your account**.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Window": {
            "$ref": "#/components/headers/X-RateLimit-Window"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "not_found": {
                "value": {
                  "error": {
                    "code": 404,
                    "message": "Shipment not found"
                  }
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected error. Quote the reference to LME support.",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "X-RateLimit-Window": {
            "$ref": "#/components/headers/X-RateLimit-Window"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "internal": {
                "value": {
                  "error": {
                    "code": 500,
                    "message": "Internal error (ref: a1b2c3d4e5f6)"
                  }
                }
              }
            }
          }
        }
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Requests allowed in the current window.",
        "schema": {
          "type": "integer",
          "example": 600
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer",
          "example": 599
        }
      },
      "X-RateLimit-Window": {
        "description": "Window length, in seconds.",
        "schema": {
          "type": "integer",
          "example": 60
        }
      }
    }
  }
}