LuckyFit Public Integration API

LuckyFit public integration API.

All endpoints are mounted under the /api prefix and require organization network-key authentication (Api-Key header). The key identifies the "network" (root organization) and may optionally restrict access to specific branches. Without a valid key the API returns 401 Unauthorized with a body of { "success": false, "session_expired": true, ... }.

Response format

Endpoints do not use HTTP status codes for business logic: on a validation error they typically return 200 OK with success: false and a message in error. There are two envelopes:

• data envelope (send_data_response): { success, data, error, total }.
• crud envelope (send_crud_response): { success, data, error, error_code, total, summary }.

The /terminal/* endpoints are the exception: they implement the external payment terminal protocol as-is, return a bare JSON body without any envelope, and do use HTTP status codes — 200 on success, 401 { "result": "userNotIdentified" } when the key is missing or invalid, and 403 { "result": "<code>", "description": "<text>" } on a business error.

Branch resolution (organization_id)

For create/update operations, if organization_id is omitted the branch is resolved automatically: if the Api-Key is restricted to exactly one branch, that branch is used; if the network has exactly one branch, that branch is used; otherwise an explicit organization_id is required.

Pagination

List (GET) endpoints accept start/limit query parameters and return a total in the response envelope:

• start — 1-based index of the first record to return, i.e. offset = start - 1. Defaults to 1.
• limit — page size. Defaults to 25; values above 100 are silently capped to 100.
• total — the total number of records matching the request's filters, across all pages (not just the current page's data length).

Exception: GET /classes/schedule already uses start/finish for the schedule period, so pagination there uses page_start/page_limit instead (same semantics and defaults).

Rate limiting

All API requests are limited to 5 requests per second per Api-Key (across every endpoint, including /terminal/*). Requests above that rate are rejected — the client should retry them after a short pause.

Practical consequences for integrations:

• Do not fan out parallel requests; a single sequential client stays within the limit.
• For bulk reads use the largest allowed page (limit=100) instead of many small pages, and pace the paging loop.
• Cache rarely-changing dictionaries (/info_sources, /organizations, /memberships) instead of re-fetching them per operation.