{"openapi":"3.1.0","info":{"title":"Makseb Business API","version":"1.4.0","description":"Makseb Business API. Use scoped business credentials and verify integrations in the isolated sandbox before enabling live traffic."},"paths":{"/v1/branches":{"get":{"summary":"List authorized branches","description":"Required scope: branches:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Branch"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/products":{"get":{"summary":"List products","description":"Required scope: catalog:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/services":{"get":{"summary":"List services","description":"Required scope: catalog:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/inventory":{"get":{"summary":"Read inventory quantities","description":"Required scope: inventory:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/inventory/adjustments":{"post":{"summary":"Record a stock adjustment","description":"Required scope: inventory:write. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"inventory_item_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Generate once per operation and reuse unchanged for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["branch_id","inventory_item_id","quantity_delta","movement_type","reason"],"properties":{"branch_id":{"type":"string","format":"uuid"},"inventory_item_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"quantity_delta":{"type":"number","not":{"const":0}},"movement_type":{"enum":["adjust_expired","adjust_damaged","adjust_lost","adjust_found","adjust_internal_use","adjust_correction"]},"reason":{"type":"string","minLength":3}}}}}}}},"/v1/orders":{"get":{"summary":"List orders","description":"Required scope: orders:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]},"post":{"summary":"Create a customer order using server prices","description":"Required scope: orders:write. All results are restricted to the integration business and branches. For age-priced tickets, add one service line per visitor category using that price record's variant_id. Keep quantity at 1 and set booking.party_size to the number of visitors in that category. Each visitor receives a separate QR after payment.","security":[{"ApiKey":[]}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedOrder"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Generate once per operation and reuse unchanged for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}}}},"/v1/orders/{id}":{"get":{"summary":"Retrieve an order","description":"Required scope: orders:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/bookings":{"get":{"summary":"List bookings","description":"Required scope: bookings:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/customers":{"get":{"summary":"List minimal customer identities","description":"Required scope: customers:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/payments":{"get":{"summary":"List recorded payments and actual gateway fees","description":"Required scope: financials:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/tickets/{id}":{"get":{"summary":"Retrieve ticket entitlements","description":"Required scope: tickets:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ticket"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/services/{id}/availability":{"post":{"summary":"Check requested service times","description":"Required scope: catalog:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"booking_time":{"type":"string"},"remaining_capacity":{"type":"integer"},"resource_available":{"type":"boolean"}}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","times"],"properties":{"date":{"type":"string","format":"date","description":"Date in the branch time zone."},"times":{"type":"array","minItems":1,"maxItems":96,"items":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$"}},"days":{"type":"integer","minimum":1},"hours":{"type":"integer","minimum":1},"resource_id":{"type":"string","format":"uuid"}}}}}}}},"/v1/customer-tickets":{"post":{"summary":"Retrieve or fulfill tickets using a signed-receipt capability","description":"No business API key is needed. The receipt token authorizes only its own order. Paid fulfillment is idempotent; refunded orders require business assistance.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["receipt_token"],"properties":{"receipt_token":{"type":"string","pattern":"^[A-Za-z0-9_-]{32}$"},"offset":{"type":"integer","minimum":0,"default":0}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Ticket"},{"type":"object","properties":{"qr_code":{"type":"string"},"timezone":{"type":"string"}}}]}},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]},"total":{"type":"integer"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/customer-orders/status":{"post":{"summary":"Read current order and payment status using its capability","description":"Use branch_id and placement_key returned at creation. A browser redirect is not proof of payment.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCapability"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"payment_status":{"type":"string"},"is_paid":{"type":"boolean"},"total_minor":{"type":"integer"},"paid_minor":{"type":"integer"},"remaining_minor":{"type":"integer"},"currency_code":{"type":"string"},"receipt_token":{"type":["string","null"]},"items":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/customer-orders/checkout":{"post":{"summary":"Start hosted checkout for a customer order","description":"Available when the environment has an enabled payment gateway. The sandbox preview may report checkout_unavailable. No raw card details are accepted.","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Generate once per operation and reuse unchanged for retries."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/OrderCapability"},{"type":"object","properties":{"customer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}}}}]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":["string","null"],"format":"uri"},"status_url":{"type":["string","null"],"format":"uri"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ticket-validations":{"post":{"summary":"Check a QR without consuming entry","description":"Required scope: access:validate. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Scan"},{"required":["qr_code"]}]}}}}}},"/v1/access-attempts":{"post":{"summary":"Authorize and consume a zone entry","description":"Required scope: access:redeem. All results are restricted to the integration business and branches. Main entrances start visits, main exits end them, and zone scanners enforce the visitor ticket areas and remaining allowances. Configure each scanner role in API integrations. A new physical scan needs a new Idempotency-Key; retries reuse the original key. Actuate each access_attempt_id at most once and before actuation_expires_at.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessDecision"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Generate once for a physical scan. Reuse exactly for retries; never reuse for another scan."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Scan"},{"required":["qr_code","gate_id","date_time"]}]}}}}}},"/v1/access-attempts/{id}":{"get":{"summary":"Read historical decision; never actuate from this response","description":"Required scope: access:redeem. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"decision":{"$ref":"#/components/schemas/AccessDecision"},"actuation_allowed":{"const":false},"decided_at":{"type":"string","format":"date-time"},"passage_confirmed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/access-attempts/{id}/confirmation":{"post":{"summary":"Record gate opening or confirmed passage","description":"Required scope: access:confirm. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"access_attempt_id":{"type":"string","format":"uuid"},"gate_opened_at":{"type":["string","null"],"format":"date-time"},"passage_confirmed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"enum":["gate_opened","passage_confirmed"]}}}}}}}},"/v1/changes":{"get":{"summary":"Read authorized business changes","description":"Requires changes:read and the read scope of each resource. Captures catalog, inventory, orders, bookings, customers, financial records, tickets and access events. Results follow publication sequence; webhooks may arrive out of order. Rebuild mirrors after permissions change.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_sequence":{"type":"integer"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Cursor expired. Capture a new synchronization cursor and rebuild the snapshot. Changes are retained for 90 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"sequence","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"next_sequence from the last applied page, or the initial synchronization cursor."}]}},"/v1/branches/{id}":{"get":{"summary":"Read one branche","description":"Required scope: branches:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Branch"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/products/{id}":{"get":{"summary":"Read one product","description":"Required scope: catalog:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogItem"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/services/{id}":{"get":{"summary":"Read one service","description":"Required scope: catalog:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogItem"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/inventory/{id}":{"get":{"summary":"Read one inventory","description":"Required scope: inventory:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryItem"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/bookings/{id}":{"get":{"summary":"Read one booking","description":"Required scope: bookings:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/customers/{id}":{"get":{"summary":"Read one customer","description":"Required scope: customers:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/payments/{id}":{"get":{"summary":"Read one payment","description":"Required scope: financials:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/refunds/{id}":{"get":{"summary":"Read one refund","description":"Required scope: financials:read. Returns current state within the integration business and branch permissions. Unavailable or unauthorized identifiers return 404.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/refunds":{"get":{"summary":"List recorded refunds","description":"Required scope: financials:read. All results are restricted to the integration business and branches.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Maximum rows per page."},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The next_after value from the previous page."}]}},"/v1/sync/start":{"get":{"summary":"Capture a synchronization cursor","description":"Requires changes:read. Capture before reading snapshot pages, then apply changes after this sequence. This is not a transactionally frozen snapshot.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sequence":{"type":"integer"},"captured_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope, gate or branch not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 32 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"JSON required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service unavailable; do not open a gate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"A secret Makseb key. Server-to-server only; never embed in a browser or mobile app. Sandbox keys begin mk_test_."}},"schemas":{"CreatedOrder":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"placement_key":{"type":"string"},"booking_outcomes":{"type":"array","items":{"$ref":"#/components/schemas/BookingOutcome"}}}},"OrderCapability":{"type":"object","required":["branch_id","placement_key"],"properties":{"branch_id":{"type":"string","format":"uuid"},"placement_key":{"type":"string","minLength":32,"maxLength":200},"language":{"enum":["en","ar"]}}},"CreateOrder":{"type":"object","additionalProperties":false,"required":["branch_id","items"],"properties":{"branch_id":{"type":"string","format":"uuid"},"order_type":{"enum":["takeaway","dine_in","booking"]},"table_number":{"type":"integer"},"customer_phone":{"type":"string"},"note":{"type":"string"},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["product_id","quantity"],"properties":{"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":1000,"description":"Product units. For a booking line this must be 1; use booking.party_size for visitors or guests."},"booking":{"type":"object","description":"Required for services. Calendar values use the branch time zone. Review booking_outcomes before payment: unavailable lines can be refused.","required":["date","customer_name","customer_phone"],"properties":{"date":{"type":"string","format":"date"},"time":{"type":"string"},"party_size":{"type":"integer","minimum":1},"days":{"type":"integer","minimum":1},"hours":{"type":"integer","minimum":1,"description":"Required for hour-based services. Use booking_rules.duration_value for the standard duration, or another duration allowed by the service."},"resource_id":{"type":"string","format":"uuid"},"customer_name":{"type":"string"},"customer_phone":{"type":"string"}}},"ticket_variant_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":30,"uniqueItems":true,"description":"Optional combined ticket selection for one visitor category. Use one price variant per option. Fully covered standalone zones add no charge; partially overlapping bundles are refused. Set variant_id to the first effective option, with the widest zone coverage first and full-access options first when coverage is equal. A booking line produces one ticket per visitor with the union of zones."}},"allOf":[{"if":{"required":["booking"]},"then":{"properties":{"quantity":{"const":1}}}}]}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","request_id"],"properties":{"code":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"Page":{"type":"object","required":["data","has_more","next_after"],"properties":{"data":{"type":"array","items":{}},"has_more":{"type":"boolean"},"next_after":{"type":["string","null"],"format":"uuid"}}},"Branch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"currency_code":{"type":"string"},"timezone":{"type":"string"}}},"CatalogItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string"},"item_type":{"enum":["product","service"]},"unit_price_minor":{"type":["integer","null"]},"currency_code":{"type":"string"},"image_url":{"type":["string","null"]},"store_published":{"type":"boolean"},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"unit_price_minor":{"type":["integer","null"]},"image_url":{"type":["string","null"]}}}},"booking_rules":{"type":"object","properties":{"booking_type":{"type":["string","null"]},"pricing_basis":{"type":["string","null"]},"duration_value":{"type":["integer","null"]},"duration_unit":{"type":["string","null"]},"capacity":{"type":["integer","null"]},"requires_resource":{"type":["boolean","null"]}}},"ticket_access":{"type":"array","items":{"type":"object","properties":{"zone_id":{"type":"string","format":"uuid"},"zone_name":{"type":"string"},"entry_limit":{"type":"integer"},"description":{"type":"string"},"image_url":{"type":["string","null"],"format":"uri"},"unlimited_inside":{"type":"boolean"},"capacity":{"type":["integer","null"],"minimum":1,"description":"Maximum simultaneous visitors shared by all products using this zone. Null means no configured limit."}}},"description":"Service areas and default allowances. If ticket_options exist, the selected option determines which areas the purchased visitor ticket includes. Zone UUIDs survive renaming and photo changes."},"ticket_rules":{"type":["object","null"],"properties":{"park_entry_required":{"type":"boolean"},"park_entry_limit":{"type":["integer","null"],"minimum":1},"validity_mode":{"type":"string","description":"calendar_date for zoo and theme park visits; scheduled for other services."}},"description":"With entry tracking enabled, zone access requires an active visit. A limit of 1 blocks park re-entry after exit; null permits re-entry while the ticket is valid."},"ticket_options":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TicketOption"}}}},"InventoryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unit":{"type":"string"},"stock":{"type":"number","description":"Quantity of the unvaried item, not an aggregate of variant quantities."},"threshold":{"type":"number"},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"stock":{"type":"number"},"threshold":{"type":"number"}}}}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"payment_status":{"type":"string"},"refund_status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"currency_code":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"quantity":{"type":"number"},"unit_price_minor":{"type":"integer"}}}}}},"Booking":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"menu_item_id":{"type":"string","format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid"},"booking_date":{"type":"string","format":"date"},"booking_time":{"type":["string","null"]},"booking_end_at":{"type":"string","format":"date-time"},"status":{"type":"string"},"party_size":{"type":"integer"}}},"Customer":{"type":"object","description":"Minimal projection. Contact details and business-wide metrics are not granted by this scope.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"first_seen_at":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","description":"Amounts are recorded facts, not estimates. Null fees are unknown, not zero. This object is not a bank settlement statement.","properties":{"id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer"},"currency_code":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"gateway_transaction_id":{"type":["string","null"]},"gateway_fee_status":{"type":"string"},"gateway_fee_minor":{"type":["integer","null"]},"gateway_fee_vat_minor":{"type":["integer","null"]},"gateway_fee_vat_status":{"type":"string"},"currency_source":{"type":"string","enum":["order_snapshot","legacy_branch"],"description":"legacy_branch means the original currency was not recorded; the current branch currency is shown as an inference."}}},"Ticket":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"status":{"enum":["active","revoked","cancelled"]},"valid_from":{"type":"string","format":"date-time"},"valid_until":{"type":"string","format":"date-time"},"policy_revision":{"type":"integer"},"entitlements":{"type":"array","items":{"type":"object","properties":{"zone_id":{"type":"string","format":"uuid"},"entry_limit":{"type":"integer"},"remaining_entries":{"type":["integer","null"],"description":"Null for unlimited zone access. Finite allowances are consumed only on zone entry."},"unlimited_inside":{"type":"boolean"}}}},"ticket_choice":{"anyOf":[{"$ref":"#/components/schemas/TicketChoice"},{"type":"null"}]},"visit_state":{"type":"string","enum":["outside","inside","exited"]},"visit_sequence":{"type":"integer"},"park_entry_required":{"type":"boolean"},"park_entry_limit":{"type":["integer","null"]},"park_entries_used":{"type":"integer"}}},"Scan":{"type":"object","properties":{"qr_code":{"type":"string","minLength":16,"maxLength":512,"description":"The complete opaque QR payload; do not log it."},"gate_id":{"type":"string","description":"Registered gate UUID or its external identifier."},"date_time":{"type":"string","format":"date-time","description":"Device time with an explicit offset; eligibility uses server time."}}},"AccessDecision":{"type":"object","required":["valid","ticket_id","status","reason","access_attempt_id"],"properties":{"valid":{"type":"boolean"},"ticket_id":{"type":["string","null"],"format":"uuid"},"status":{"enum":["access_granted","access_failed","duplicate"]},"reason":{"type":["string","null"],"description":"Includes park_entry_required, already_inside_park, park_entries_exhausted, park_not_included, not_inside_park, visit_changed, zone_not_included, entries_exhausted and expiry/revocation reasons. Treat unknown denial reasons as denied."},"access_attempt_id":{"type":"string","format":"uuid"},"zone_id":{"type":"string","format":"uuid"},"remaining_entries":{"type":["integer","null"]},"actuation_expires_at":{"type":"string","format":"date-time"},"visit_state":{"type":["string","null"],"description":"Presence based on accepted entrance/exit scans, not GPS."},"ticket_choice":{"anyOf":[{"$ref":"#/components/schemas/TicketChoice"},{"type":"null"}]},"visit_sequence":{"type":["integer","null"]},"access_kind":{"type":"string","enum":["park","zone"]},"direction":{"type":"string","enum":["entry","exit"]},"unlimited_inside":{"type":"boolean"},"zone_capacity":{"type":["integer","null"],"minimum":0,"description":"Configured maximum people inside; null means unlimited."},"zone_available":{"type":["integer","null"],"minimum":0,"description":"Available places at decision time; null means unlimited."},"zone_occupied":{"type":"integer","minimum":0,"description":"Recorded entries that have not exited. Includes approved entry scans."},"inside_zone":{"type":"boolean","description":"Whether this visitor is recorded inside the scanned zone."},"zone_sequence":{"type":"integer","minimum":0,"description":"Presence generation. Old approvals cannot reopen after a later entry or exit."}}},"Validation":{"type":"object","required":["valid","ticket_id","status","gate_eligible","consumed"],"properties":{"valid":{"type":"boolean"},"ticket_id":{"type":["string","null"],"format":"uuid"},"status":{"enum":["active","access_granted","access_failed","duplicate"]},"reason":{"type":["string","null"]},"gate_eligible":{"type":["boolean","null"]},"consumed":{"const":false,"description":"Always false: a validation request does not consume an entry."},"valid_until":{"type":"string","format":"date-time"},"visit_state":{"type":["string","null"],"description":"Presence based on accepted entrance/exit scans, not GPS."},"ticket_choice":{"anyOf":[{"$ref":"#/components/schemas/TicketChoice"},{"type":"null"}]},"park_entry_required":{"type":"boolean"},"park_entries_remaining":{"type":["integer","null"]},"ticket_consumed":{"type":"boolean","description":"Whether a simple visitor ticket has exhausted its finite entry allowance. This is ticket state; consumed remains false because validation does not use an entry."},"zone_capacity":{"type":["integer","null"],"minimum":0,"description":"Configured maximum people inside; null means unlimited."},"zone_available":{"type":["integer","null"],"minimum":0,"description":"Available places at decision time; null means unlimited."},"zone_occupied":{"type":"integer","minimum":0,"description":"Recorded entries that have not exited. Includes approved entry scans."},"inside_zone":{"type":"boolean","description":"Whether this visitor is recorded inside the scanned zone."},"zone_sequence":{"type":"integer","minimum":0,"description":"Presence generation. Old approvals cannot reopen after a later entry or exit."}}},"Event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"event_type":{"type":"string"},"resource_id":{"type":"string","format":"uuid"},"resource_type":{"type":"string"},"branch_id":{"type":["string","null"],"format":"uuid"},"payload_version":{"const":"v1"},"data":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"BookingOutcome":{"type":"object","properties":{"item_index":{"type":"integer","minimum":0},"status":{"enum":["booked","refused"]},"booking_id":{"type":["string","null"],"format":"uuid"},"reason":{"type":["string","null"]}}},"Refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"branch_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer"},"recorded_fee_minor":{"type":["integer","null"],"description":"Recorded refund fee; not evidence of bank settlement."},"currency_code":{"type":"string"},"currency_source":{"type":"string","enum":["order_snapshot","legacy_branch"]},"created_at":{"type":"string","format":"date-time"}}},"TicketPrice":{"type":"object","required":["id","variant_id","name","min_age","max_age","price_minor","currency_code"],"properties":{"id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"min_age":{"type":"integer","minimum":0,"maximum":150},"max_age":{"type":["integer","null"],"minimum":0,"maximum":150},"price_minor":{"type":"integer","minimum":0},"currency_code":{"type":"string"}},"description":"A visitor age category. Use variant_id when ordering. Ages are inclusive completed years; null max_age means no upper age limit. Prices are per visitor in minor units."},"TicketOption":{"type":"object","required":["id","name","all_zones","zone_ids","prices"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"all_zones":{"type":"boolean"},"zone_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"prices":{"type":"array","items":{"$ref":"#/components/schemas/TicketPrice"}}},"description":"A ticket package with its own included zones and visitor prices. all_zones includes the areas configured for this service at purchase time."},"TicketChoice":{"type":"object","properties":{"option_id":{"type":"string","format":"uuid"},"option_name":{"type":"string"},"price_id":{"type":"string","format":"uuid"},"variant_id":{"type":"string","format":"uuid"},"visitor_type":{"type":"string"},"min_age":{"type":"integer"},"max_age":{"type":["integer","null"]},"option_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"All effective ticket options in a combined purchase. option_id remains the primary option for older clients."}},"description":"The immutable option and visitor category recorded for this ticket when sold."}}},"servers":[{"url":"https://api.makseb.io"}]}