1-нұсқа. Кәсіпорынның жеке кілті арқылы қол жеткізу.

TGbot Cafe брондау журналының API-ы кәсіпорынның барлық қосылған залдарындағы бос емес уақыт аралықтарын қайтарады. Осы деректер арқылы сайт немесе басқа қолданба қолжетімділік күнтізбесін көрсете алады. Әдіс деректерді тек оқиды: бронь жасау, жазбаны өзгерту, төлем қабылдау және уақытты резервтеу қолдау таппайды. Жауапқа клиенттердің аттары мен телефондары, түсініктемелер, қызметтер, сомалар және құжаттардың ішкі нөмірлері кірмейді.

OpenAPI 3.0.3 келісімшартын жүктеу

Әдіс және қолжетімділік

Кілтті кәсіпорын қосылғаннан кейін API әкімшісі береді. Оның пішімі — мына префикс: arma_avail_ және 64 оналтылық таңба. Бұл — TGbot Cafe-нің бөлек кілті; AssistBot хабарлама жіберу API токендері бұл әдіске жарамайды. Бір кілт тек бекітілген кәсіпорынның күнтізбесін ашады және әкімшілік кабинетке немесе төлем операцияларына қолжетімділік бермейді.

Сұрауды қолданбаңыздың серверінен HTTPS арқылы орындаңыз. Кілтті жабық серверлік баптауда сақтаңыз; оны HTML-де, браузерлік JavaScript ішінде немесе сұрау мекенжайында орналастырмаңыз. Кілт жария болып кетсе, әкімшіден оны қайтарып алып, жаңасын беруді сұраңыз. Кәсіпорын кілтпен анықталады: оны сұрау параметрлерімен ауыстыруға болмайды.

Сұрау параметрлері

• Бүтін секундтары мен нақты уақыт белдеуі бар RFC3339 қажет: ығысу, мысалы, +03:00, немесе Z. Ең үлкен ығысу — ±14:00. Бөлшек секундтар, уақыты көрсетілмеген күн және белдеуі жоқ уақыт қабылданбайды.
• Аралықтың пішімі: [from, to): басы кіреді, соңы кірмейді. Соңы басынан кейін болуы керек, ұзақтығы 31 × 24 сағаттан, яғни 2 678 400 секундтан аспауы тиіс.
• Тек мыналарға рұқсат етіледі: from және to. Кәсіпорынды таңдау және залдар бойынша сүзу қолдау таппайды: жауапта кәсіпорынның барлық бапталған залдары болады.
• Таңбаны + мына түрде кодтаңыз: %2B. Ол үшін query құрастырушысын немесе мынаны пайдаланыңыз: --data-urlencode.

Қосылған кәсіпорынға арналған мысал. Айнымалы AVAILABILITY_KEY берілген кілтті қамтиды:

curl --fail-with-body --get 'https://tgbotcafe.assistbot.ru/api/v1/availability' \
  --header "Authorization: Bearer ${AVAILABILITY_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'from=2026-10-15T00:00:00+03:00' \
  --data-urlencode 'to=2026-10-17T00:00:00+03:00'

Жауап және мысал

Алты залы бар ойдан шығарылған кәсіпорынның мысалы. Басқа қосылымда залдар тізімі мен кодтары өзгеше болуы мүмкін. Бірінші жазба түн ортасынан өтеді:

{
  "version": 1,
  "source": "admin_calendar",
  "timezone": "Europe/Moscow",
  "from": "2026-10-15T00:00:00+03:00",
  "to": "2026-10-17T00:00:00+03:00",
  "generated_at": "2026-10-13T13:20:00+03:00",
  "data_updated_at": "2026-10-13T12:45:00+03:00",
  "freshness": "live",
  "complete": false,
  "incomplete_reasons": ["calendar_not_authoritative"],
  "halls": [
    {"hall_id": "armaloft", "name": "АрмаЛофт залы", "busy_intervals": [
      {"starts_at": "2026-10-15T22:00:00+03:00", "ends_at": "2026-10-16T02:00:00+03:00"}
    ]},
    {"hall_id": "mercury", "name": "Меркури залы", "busy_intervals": []},
    {"hall_id": "airplane", "name": "Самолет залы", "busy_intervals": []},
    {"hall_id": "rufer", "name": "Руфер залы", "busy_intervals": []},
    {"hall_id": "pulka", "name": "Пулька залы", "busy_intervals": []},
    {"hall_id": "boho", "name": "Бохо залы", "busy_intervals": []}
  ]
}

Бос уақытты қалай анықтау керек

Мәні complete=false болғанда, бос емес аралықтың жоқтығы залдың бос екенін білдірмейді: броньдардың бір бөлігі әлі сыртқы дереккөзде болуы мүмкін. Белгілі бос емес уақытты белгілеуге болады, бірақ қалған сағаттардың бос екенін растауға болмайды. Бұл жағдайда тіпті HTTP 200 және бос массив те растау болып саналмайды.

Бос уақытты көрсетпес бұрын HTTP 200 мәнін, version=1, source=admin_calendar, freshness=live, complete=true және күтілетін залдар тізімінің толықтығын тексеріңіз. Қате немесе толық емес күнтізбе болса, «Қолжетімділік уақытша расталмады» деп көрсетіңіз; мұндай жауапты бос күнтізбемен алмастырмаңыз.

• Бос емес аралықтар реттелген; қиылысатын және іргелес аралықтар біріктірілген. Жазба мына мәнге дейін басталса да, шекаралары бастапқы күйінде қалады: from немесе мына мәннен кейін аяқталса: to.
• Жазба мына шарт орындалғанда қосылады: starts_at < to және ends_at > from. Келесі жазба алдыңғысы аяқталған дәл сәтте басталуы мүмкін.
• Бас тартылған жазбалар есепке алынбайды. Клиенттің келмеуі, төлемнің болмауы және тегін көрудің өзі уақытты босатпайды. Минуттар мен түнгі аралықтар сағатқа дейін дөңгелектелмей сақталады.

Әдіс жауаптарында мына директива болады: no-store мына жерден: Cache-Control, мысалы, no-store, private; тақырыпта қосымша рұқсат етілген директивалар болуы мүмкін. Жауаптарды расталған қолжетімділік ретінде кэштемеңіз. Барлық залдар үшін бір сұрау жеткілікті. Күнтізбені оқу таңдалған уақытты резервтемейді: жауаптан кейін басқа пайдаланушы жаңа жазба жасай алады. Әдіс сыртқы күнтізбені синхрондамайды және бронь жасаудың қолданыстағы процесін автоматты түрде ауыстырмайды.

Қателер

Авторизация, параметрлер және күнтізбені оқу қателері үшін қысқа JSON қайтарылады:

{"error":{"code":"calendar_unavailable"}}

Кез келген басқа жауап, соның ішінде 500, бос уақытты растамайды. 405 және 429 стандартты жауаптары үшін күнтізбе қатесінің пішімі кепілдендірілмейді. Сол авторизациямен және тақырыптармен, денесіз HEAD сұрауына рұқсат етіледі; ол үшін бөлек екінші API әдісі жоқ.