# GoCheckin Gateway API

> The API for apps built outside the GoCheckin core team: booking sites, partner integrations, e-commerce sync and AI tools. Every call goes through the gateway, which picks the store from `client_id` and forwards the request.

## Conventions (apply to every endpoint)

- Base URL: the gateway host in openapi.yaml `servers`.
- Auth: HTTP Basic with your gateway username and password. Each user may call only the routes it was granted (HTTP 401 otherwise). Keep the password on a server, never in a browser or mobile app.
- Store: send `client_id=<store id>` on every call (query string for GET, body for POST). Without it: `{ "status": "FAIL", "error": "Missing client_id" }`; unknown store: `error: "Client not found"`.
- Requests: POST bodies are JSON (`Content-Type: application/json`), with arrays and objects as plain JSON. Only the few upload routes that say so also accept `multipart/form-data`; multipart to any other route gets HTTP 403.
- Response envelope (usually HTTP 200 even on errors):
  - success: `{ "status": "OK", "result": { "status": "OK", "data": <payload> } }`
  - soft failure: `status: "OK"` but `result.status: "FAIL"` with `result.error` / `result.message`
  - failure: `{ "status": "FAIL", "error": "<CODE or message>", "message": "..." }`
  - lists: `result.data = { "items": [...], "_meta": { totalCount, pageCount, currentPage, perPage } }`; paginate with `page` and `per-page`
- Some GET routes are cached by the gateway for a few minutes per store; add `cache=0` for fresh data.
- Times are in the store's timezone.

## Flows

- [Customer online booking](llms/flows/online-booking.md): Build a booking site: load the store, show open times, verify the customer, hold the slot, take a card or deposit, create the appointment, and let the customer view or cancel it.

## Reference

- [All endpoints](llms/gateway.md) (207 endpoints)
- [OpenAPI spec](openapi.yaml)