{"openapi":"3.1.0","info":{"title":"MekanBook Partner API","version":"1.0.0","description":"Venue-level REST API for MekanBook. Create a key in Panel › Geliştirici (shown once). Send it as `Authorization: Bearer mbp_…`.\n\nAmounts are integer minor units (kuruş). Times are ISO 8601 UTC. Lists use cursor pagination (`limit`, `cursor` → `next_cursor`).\n\nErrors: `{\"error\":{\"code\":\"…\",\"message\":\"…\"}}`. Rate limit: per key (default 120 req/min); `429` with `Retry-After`.","contact":{"name":"MekanBook","url":"https://www.mekanbook.com/gelistirici"}},"servers":[{"url":"https://www.mekanbook.com/api/partner/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"me"},{"name":"menu"},{"name":"orders"},{"name":"reservations"},{"name":"loyalty"},{"name":"customers"},{"name":"events"},{"name":"webhooks"},{"name":"ecommerce"}],"paths":{"/me":{"get":{"operationId":"getMe","summary":"Current key and venue","tags":["me"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"venue":{"$ref":"#/components/schemas/Venue"},"key":{"type":"object"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/menu":{"get":{"operationId":"getMenu","summary":"Full menu (menus › categories › items)","tags":["menu"],"x-required-scope":"menu:read","security":[{"apiKey":["menu:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/menu/items":{"patch":{"operationId":"bulkUpdateMenuItems","summary":"Bulk update prices/availability (max 500). Price changes are logged.","tags":["menu"],"x-required-scope":"menu:write","security":[{"apiKey":["menu:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"integer"},"not_found":{"type":"array","items":{}}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/MenuItemPatch"}}}}}}}}},"/menu/items/{id}":{"get":{"operationId":"getMenuItem","summary":"One menu item","tags":["menu"],"x-required-scope":"menu:read","security":[{"apiKey":["menu:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MenuItem"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]},"patch":{"operationId":"updateMenuItem","summary":"Update price and/or availability","tags":["menu"],"x-required-scope":"menu:write","security":[{"apiKey":["menu:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/MenuItem"}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price":{"type":"integer","minimum":0},"available":{"type":"boolean"}}}}}}}},"/orders":{"get":{"operationId":"listOrders","summary":"Table orders (newest first)","tags":["orders"],"x-required-scope":"orders:read","security":[{"apiKey":["orders:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/updated_since"},{"name":"status","in":"query","schema":{"type":"string","enum":["awaiting_acceptance","accepted","preparing","ready","served","rejected","cancelled"]}}]}},"/orders/{id}":{"get":{"operationId":"getOrder","summary":"One order","tags":["orders"],"x-required-scope":"orders:read","security":[{"apiKey":["orders:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/orders/{id}/status":{"post":{"operationId":"setOrderStatus","summary":"Move order lines to a new status (accepted → preparing → ready → served)","tags":["orders"],"x-required-scope":"orders:write","security":[{"apiKey":["orders:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"},"updated_lines":{"type":"array","items":{"type":"integer"}},"skipped_lines":{"type":"array","items":{"type":"object"}}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["accepted","preparing","ready","served","rejected","cancelled"]},"line_ids":{"type":"array","items":{"type":"integer"}},"reason":{"type":"string","maxLength":250}}}}}}}},"/reservations":{"get":{"operationId":"listReservations","summary":"Reservations","tags":["reservations"],"x-required-scope":"reservations:read","security":[{"apiKey":["reservations:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/updated_since"},{"name":"status","in":"query","schema":{"type":"string","enum":["requested","confirmed","declined","cancelled_by_guest","cancelled_by_venue","arrived","seated","completed","no_show","expired"]}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"Venue local time"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}]},"post":{"operationId":"createReservation","summary":"Create a confirmed reservation (staff channel; availability rules apply)","tags":["reservations"],"x-required-scope":"reservations:write","security":[{"apiKey":["reservations:write"]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Reservation"}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","time","party","name"],"properties":{"date":{"type":"string","format":"date"},"time":{"type":"string","pattern":"^\\d{2}:\\d{2}$"},"party":{"type":"integer","minimum":1,"maximum":50},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"note":{"type":"string"},"allergy_note":{"type":"string"},"area_preference":{"type":"string"}}}}}}}},"/reservations/{id}":{"get":{"operationId":"getReservation","summary":"One reservation","tags":["reservations"],"x-required-scope":"reservations:read","security":[{"apiKey":["reservations:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Reservation"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/reservations/{id}/status":{"post":{"operationId":"setReservationStatus","summary":"Change reservation status (declined/cancelled_by_venue require reason; deposits are refunded automatically)","tags":["reservations"],"x-required-scope":"reservations:write","security":[{"apiKey":["reservations:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Reservation"}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["confirmed","declined","cancelled_by_venue","arrived","seated","completed","no_show"]},"reason":{"type":"string"}}}}}}}},"/loyalty/accounts":{"get":{"operationId":"listLoyaltyAccounts","summary":"Loyalty accounts (customer masked)","tags":["loyalty"],"x-required-scope":"loyalty:read","security":[{"apiKey":["loyalty:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LoyaltyAccount"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/updated_since"}]}},"/loyalty/accounts/{id}":{"get":{"operationId":"getLoyaltyAccount","summary":"Loyalty account with last 50 transactions","tags":["loyalty"],"x-required-scope":"loyalty:read","security":[{"apiKey":["loyalty:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/LoyaltyAccount"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/loyalty/accounts/{id}/adjust":{"post":{"operationId":"adjustLoyalty","summary":"Add or remove points (audited)","tags":["loyalty"],"x-required-scope":"loyalty:write","security":[{"apiKey":["loyalty:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/LoyaltyAccount"}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["points","reason"],"properties":{"points":{"type":"integer"},"reason":{"type":"string","maxLength":190}}}}}}}},"/customers":{"get":{"operationId":"listCustomers","summary":"Guest book (masked; contact only with marketing consent)","tags":["customers"],"x-required-scope":"customers:read","security":[{"apiKey":["customers:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/updated_since"},{"name":"marketing_consent","in":"query","schema":{"type":"boolean"}}]}},"/events":{"get":{"operationId":"listEvents","summary":"Published events (upcoming by default)","tags":["events"],"x-required-scope":"events:read","security":[{"apiKey":["events:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next_cursor":{"type":["string","null"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/updated_since"},{"name":"include_past","in":"query","schema":{"type":"boolean"}}]}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"Webhook endpoints","tags":["webhooks"],"x-required-scope":"webhooks:manage","security":[{"apiKey":["webhooks:manage"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createWebhook","summary":"Create endpoint. The signing secret is returned once.","tags":["webhooks"],"x-required-scope":"webhooks:manage","security":[{"apiKey":["webhooks:manage"]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"422":{"$ref":"#/components/responses/Validation"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"events":{"type":"array","items":{"type":"string","enum":["*","order.created","order.updated","reservation.created","reservation.updated","reservation.cancelled","loyalty.earned","loyalty.redeemed","loyalty.adjusted","review.created","takeaway.created","takeaway.updated","menu.updated","ecommerce.link.created","ecommerce.link.revoked"]}}}}}}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Delete endpoint","tags":["webhooks"],"x-required-scope":"webhooks:manage","security":[{"apiKey":["webhooks:manage"]}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/ecommerce/ping":{"get":{"operationId":"ecommercePing","summary":"Online store connection test and rules","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/ecommerce/links":{"post":{"operationId":"ecommerceRequestLink","summary":"Ask the customer to link their MekanBook account (code + approval link e-mailed; response never reveals whether an account exists)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"expires_at":{"type":"string"}}}}}},"429":{"description":"Too many requests for this customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string"},"external_customer_id":{"type":"string"}}}}}}}},"/ecommerce/links/{id}":{"get":{"operationId":"ecommerceLinkStatus","summary":"Link request status (approved → customer_ref)","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/ecommerce/links/{id}/verify":{"post":{"operationId":"ecommerceVerifyLink","summary":"Verify the 6-digit code the customer typed (max 5 attempts)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"customer_ref":{"type":"string"},"balance":{"type":"object"}}}}}},"422":{"description":"invalid_code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}}}},"/ecommerce/customers/{ref}":{"get":{"operationId":"ecommerceCustomer","summary":"Balance (points, cashback, stamps, rewards) for a linked customer","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"customer_not_linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}]},"delete":{"operationId":"ecommerceUnlink","summary":"Unlink the customer (consent withdrawn at the store)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}]}},"/ecommerce/quote":{"post":{"operationId":"ecommerceQuote","summary":"Redeemable discount for a basket (respects max %, min order, min points)","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ref","order_total"],"properties":{"customer_ref":{"type":"string"},"order_total":{"type":"integer","description":"Basket total in kuruş (after coupons, before shipping)"},"unit":{"type":"string","enum":["points","cashback","reward"],"default":"points"},"points":{"type":"integer"}}}}}}}},"/ecommerce/redemptions":{"post":{"operationId":"ecommerceReserve","summary":"Reserve points (deducted now, held 30 minutes). Idempotency-Key required.","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"201":{"description":"Reserved","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["reserved","confirmed","cancelled","expired","restored"]},"unit":{"type":"string","enum":["points","cashback","reward"]},"points":{"type":"integer"},"amount":{"type":"integer"},"order_ref":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"}}}}}},"422":{"description":"Not redeemable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409.","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ref","order_total"],"properties":{"customer_ref":{"type":"string"},"order_total":{"type":"integer","description":"Basket total in kuruş (after coupons, before shipping)"},"unit":{"type":"string","enum":["points","cashback","reward"],"default":"points"},"points":{"type":"integer"}}}}}}}},"/ecommerce/redemptions/{id}":{"get":{"operationId":"ecommerceRedemption","summary":"Redemption","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["reserved","confirmed","cancelled","expired","restored"]},"unit":{"type":"string","enum":["points","cashback","reward"]},"points":{"type":"integer"},"amount":{"type":"integer"},"order_ref":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/ecommerce/redemptions/{id}/confirm":{"post":{"operationId":"ecommerceConfirm","summary":"Confirm when the order is paid (re-deducts if the hold expired and balance allows; else 409 redemption_expired)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["reserved","confirmed","cancelled","expired","restored"]},"unit":{"type":"string","enum":["points","cashback","reward"]},"points":{"type":"integer"},"amount":{"type":"integer"},"order_ref":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"}}}}}},"409":{"description":"Expired or cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"}}}}}}}},"/ecommerce/redemptions/{id}/cancel":{"post":{"operationId":"ecommerceCancelRedemption","summary":"Release a reserved redemption (points return to the same ledger rows)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["reserved","confirmed","cancelled","expired","restored"]},"unit":{"type":"string","enum":["points","cashback","reward"]},"points":{"type":"integer"},"amount":{"type":"integer"},"order_ref":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409."}]}},"/ecommerce/orders":{"post":{"operationId":"ecommerceOrder","summary":"Paid order: award points once per order_ref (amount = paid, excl. shipping)","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"},"status":{"type":"string","enum":["paid","partially_refunded","refunded","cancelled"]},"amount":{"type":"integer"},"refunded_amount":{"type":"integer"},"earned":{"type":"object"},"customer_ref":{"type":"string"}}}}}},"200":{"description":"Already recorded","content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"},"status":{"type":"string","enum":["paid","partially_refunded","refunded","cancelled"]},"amount":{"type":"integer"},"refunded_amount":{"type":"integer"},"earned":{"type":"object"},"customer_ref":{"type":"string"}}}}}},"409":{"description":"order_ref_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ref","order_ref","amount"],"properties":{"customer_ref":{"type":"string"},"order_ref":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"},"amount":{"type":"integer"},"redemption_id":{"type":"string"}}}}}}}},"/ecommerce/orders/{ref}":{"get":{"operationId":"ecommerceGetOrder","summary":"Order","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"},"status":{"type":"string","enum":["paid","partially_refunded","refunded","cancelled"]},"amount":{"type":"integer"},"refunded_amount":{"type":"integer"},"earned":{"type":"object"},"customer_ref":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}]}},"/ecommerce/orders/{ref}/refund":{"post":{"operationId":"ecommerceRefund","summary":"Refund: cumulative refunded_total; points/cashback reversed proportionally; full refund returns used points","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"},"status":{"type":"string","enum":["paid","partially_refunded","refunded","cancelled"]},"amount":{"type":"integer"},"refunded_amount":{"type":"integer"},"earned":{"type":"object"},"customer_ref":{"type":"string"}}}}}},"422":{"description":"refund_decrease","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refunded_total"],"properties":{"refunded_total":{"type":"integer"}}}}}}}},"/ecommerce/orders/{ref}/cancel":{"post":{"operationId":"ecommerceCancelOrder","summary":"Cancel: reverse all earned points and return used points","tags":["ecommerce"],"x-required-scope":"ecommerce:write","security":[{"apiKey":["ecommerce:write"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_ref":{"type":"string"},"status":{"type":"string","enum":["paid","partially_refunded","refunded","cancelled"]},"amount":{"type":"integer"},"refunded_amount":{"type":"integer"},"earned":{"type":"object"},"customer_ref":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":80},"description":"Same key + same body replays the first response; different body → 409."}]}},"/ecommerce/transactions":{"get":{"operationId":"ecommerceTransactions","summary":"Recent online ledger entries for this store","tags":["ecommerce"],"x-required-scope":"ecommerce:read","security":[{"apiKey":["ecommerce:read"]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}]}}},"webhooks":{"event":{"post":{"summary":"Event delivery","description":"Headers: X-MekanBook-Event, X-MekanBook-Delivery (event id; deduplicate on it), X-MekanBook-Timestamp, X-MekanBook-Signature: t={unix},v1={hex(HMAC-SHA256(secret, \"{t}.{raw body}\"))}. Reply 2xx within 10 s. Failed deliveries are retried 8 times (1 min … 24 h); 50 consecutive failures disable the endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"mbp_{prefix}_{secret}","description":"Scopes: menu:read, menu:write, orders:read, orders:write, reservations:read, reservations:write, loyalty:read, loyalty:write, customers:read, events:read, webhooks:manage, ecommerce:read, ecommerce:write"}},"parameters":{"limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"cursor":{"name":"cursor","in":"query","schema":{"type":"string"}},"updated_since":{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}}},"responses":{"Unauthorized":{"description":"Missing/invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Insufficient scope, IP not allowed or plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Validation":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object"}}}}},"Venue":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"timezone":{"type":"string"},"currency":{"type":"string"},"url":{"type":"string"}}},"MenuItem":{"type":"object","properties":{"id":{"type":"integer"},"category_id":{"type":"integer"},"name":{"type":"string"},"description":{"type":["string","null"]},"price":{"type":["integer","null"],"description":"kuruş"},"currency":{"type":"string"},"available":{"type":"boolean"},"external_id":{"type":["string","null"]},"price_updated_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MenuItemPatch":{"type":"object","properties":{"id":{"type":"integer"},"external_id":{"type":"string","description":"POS item id (alternative to id)"},"price":{"type":"integer","minimum":0},"available":{"type":"boolean"}}},"OrderLine":{"type":"object","properties":{"id":{"type":"integer"},"menu_item_id":{"type":["integer","null"]},"name":{"type":"string"},"unit_price":{"type":"integer"},"qty":{"type":"integer"},"options":{},"note":{"type":["string","null"]},"station":{"type":"string"},"status":{"type":"string"}}},"Order":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"table_session_id":{"type":"integer"},"table_id":{"type":["integer","null"]},"status":{"type":"string","description":"Common line status or \"mixed\""},"total":{"type":"integer"},"currency":{"type":"string"},"note":{"type":["string","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"placed_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Reservation":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["requested","confirmed","declined","cancelled_by_guest","cancelled_by_venue","arrived","seated","completed","no_show","expired"]},"party_size":{"type":"integer"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"note":{"type":"string"},"allergy_note":{"type":"string"},"table_id":{"type":"integer"},"source":{"type":"string"},"deposit_amount":{"type":"integer"},"deposit_status":{"type":"string"}}},"LoyaltyAccount":{"type":"object","properties":{"id":{"type":"integer"},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]}}},"balance":{"type":"integer"},"lifetime_points":{"type":"integer"},"transactions":{"type":"array","items":{"type":"object"}}}},"Customer":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","description":"First name + initial"},"phone":{"type":["string","null"],"description":"Masked; null without marketing consent"},"email":{"type":["string","null"]},"marketing_consent":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"visits":{"type":"integer"},"no_shows":{"type":"integer"},"last_visit_at":{"type":["string","null"]}}},"Event":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"},"occurrences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"starts_at":{"type":"string"},"ends_at":{"type":["string","null"]}}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"failure_count":{"type":"integer"},"secret":{"type":"string","description":"Only in the create response"}}},"WebhookEvent":{"type":"object","required":["id","type","created_at","venue_id","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["order.created","order.updated","reservation.created","reservation.updated","reservation.cancelled","loyalty.earned","loyalty.redeemed","loyalty.adjusted","review.created","takeaway.created","takeaway.updated","menu.updated","ecommerce.link.created","ecommerce.link.revoked"]},"created_at":{"type":"string","format":"date-time"},"venue_id":{"type":"integer"},"data":{"type":"object"}}}}}}