Ordering website or app

You are building an online ordering storefront on top of the **Ewity Platform Orders API** (base URL https://api.ewitypos.com/platform-v1). Implement it end-to-end.

IMPORTANT — the docs are authoritative. Before implementing each call, open the exact reference page linked below and follow its request/response schema precisely; the summaries here are a guide, not the source of truth. Start at https://ewity-api.readme.io/docs/getting-started and refer back to the docs whenever you're unsure — do not guess field names, enums, or shapes.

AUTH
- Every request sends header `Authorization: Bearer <EWITY_PLATFORM_TOKEN>`. It is ONE token per platform (not per merchant); keep it server-side only. The merchant/store is selected by the `online_location_id` you pass in each call. Auth overview: https://ewity-api.readme.io/docs/getting-started

STEP 1 — CONNECT (onboarding) — docs: https://ewity-api.readme.io/docs/implementing-connect
- Expose ONE HTTPS endpoint (your "Connect URL"). Ewity calls it two ways, both with the Bearer token — reject any other caller with 401:
  - GET  -> respond 200 { "instructions": "<=4 lines>", "code_label"?: "Connection code" }
  - POST -> body { "connect_code": string }. Verify the code is single-use, account-bound, unexpired; consume it; respond 200 { "external_account_id": string, "display_name"?: string }. On failure respond 4xx { "error": "invalid_code|expired_code|code_already_consumed", "error_description": "<shown to merchant>" }.
- Also build a small authenticated screen in YOUR app where a signed-in merchant mints that single-use ~10-min code.

STEP 2 — CATALOGUE
- GET /stores (ref: https://ewity-api.readme.io/reference/liststores) -> persist online_locations[].id (this routes everything).
- Initial sync per location: GET /locations/{locationId}/catalogue (ref: https://ewity-api.readme.io/reference/getfullcatalogue) OR BFS via GET /locations/{locationId}/categories (ref: https://ewity-api.readme.io/reference/listrootcategories) then GET /locations/{locationId}/categories/{categoryId} (ref: https://ewity-api.readme.io/reference/getcategorydetails).
- Prices are TAX-INCLUSIVE. A product with no variants[] IS the variant. Buyable = available && !out_of_stock, evaluated per location. Currency: read it from the merchant (typically MVR) — never hard-code. Confirm every field name against https://ewity-api.readme.io/reference/getfullcatalogue.

STEP 3 — CART + ORDER
- POST /validate (ref: https://ewity-api.readme.io/reference/validatecart) { online_location_id, fulfilment_type: "delivery"|"pickup", lines:[{ variant_id, unit_quantity, modifiers:[modifier_id] }], fees?:[{name, amount}] } -> returns 200 ALWAYS; render data.total/total_tax/fees/total_components and BLOCK checkout if data.errors[] or any data.lines[].error is set.
- POST /orders (ref: https://ewity-api.readme.io/reference/createorder) { online_location_id, fulfilment_type, customer:{ mobile(required), name?, email?, address?:{ type, text } (text required when delivery) }, lines:[...], customer_notes? } -> returns Order (status "pending", payment_method null, no bill yet). Show "awaiting confirmation".

STEP 4 — STATUS, PAYMENTS, WEBHOOKS — docs: https://ewity-api.readme.io/docs/webhooks
- Expose webhook_url. Ewity POSTs event bodies (NO data: envelope) with Authorization: Bearer <token> and an X-Event header. Validate the token, dedupe by the documented keys (deliveries are at-least-once), respond 2xx within ~5s, process async. Event list + payloads: https://ewity-api.readme.io/docs/webhooks
- On X-Event OrderStatusChanged with status "accepted", the bill now exists -> POST /orders/{id}/payment (ref: https://ewity-api.readme.io/reference/addorderpayment) { amount, ref? } to record what you collected (partial payments allowed; not idempotent). For bank transfer, POST /orders/{id}/payment/bank-transfer (ref: https://ewity-api.readme.io/reference/paybanktransfer) (multipart file + payment_key from GET /orders/{id} — ref: https://ewity-api.readme.io/reference/getorder).
- Forward OrderNotification {title,message} to the customer. Let the customer cancel/confirm via POST /orders/{id}/status-change/{cancelled|pending} (ref: https://ewity-api.readme.io/reference/changeorderstatus) only when data.extra.customer_next_states allows it.

DELIVERABLES
- A storefront (menu browse -> cart -> checkout -> order tracking), a server that holds the token + implements Connect + the webhook receiver, and a periodic catalogue sync. Handle: out-of-stock lines, validate-before-order, and idempotent webhook processing. Keep the token out of the browser. When any detail is ambiguous, consult the linked ReadMe reference page rather than assuming.