Базовый URL — только с www.botai.ge (без www) возвращает перенаправление (308), а большинство HTTP-клиентов при перенаправлении не передают Authorization.
Ключи вымышленные — подставьте свои. Каждый пример читает две переменные: CORPORATE_API_KEY — корпоративный API, PRODUCTS_API_KEY — продукция и оплата.
Новый ключ, отзыв старого. Отзыв действует начиная со следующего запроса.
CORS
Отсутствует, намеренно: ключ даёт право записи, поэтому используется только с сервера, а не из браузера.
Отказ
401 unauthorized — ключ отсутствует, неизвестен, искажён или отозван.
Какой ключ
Где создаётся
Корпоративный API
Ассистент → Параметры ассистента → Прочее → Доступ к API
API продукции
Ассистент → Продукция → API-ключ
Права
Правило. Право записывается на ключ по имени; иерархии и звёздочки нет. Ключ без прав (выданный на экране продукции) открыт для /products и /payments, для корпоративных эндпоинтов — закрыт.
Право
Уровень
Что открывает (после /api/v1)
Ключ без списка
knowledge:read
Уровень ассистента
GET /knowledge
Закрыто
knowledge:write
Уровень ассистента
POST / PATCH /knowledge
Закрыто
conversations:read
Уровень ассистента
GET /conversations, /conversations/{channel}/{userId}, /contacts, /handoffs
Права фиксируются при выдаче. Если понадобилось больше — новый ключ с новыми правами, а старый отзовите.
Право уровня аккаунта личный кабинет выдаёт только тому аккаунту, которому принадлежит этот ассистент.
Два уровня
Уровень
Ключ имеет доступ к
Ассистент в запросе
Чужой ассистент
Уровень ассистента
Только ассистенту ключа
Не указывается; присланный clientId игнорируется
Указать другого ассистента нельзя
Уровень аккаунта
Всем ассистентам аккаунта
clientId — в пути, в теле или в ?clientId=
404 assistant_not_found — тот же ответ, что и для несуществующего
Право уровня аккаунта ключу ассистента не выдаётся: создать второго ассистента и прочитать расход соседнего можно только с этим правом.
Если у ассистента нет аккаунта-владельца, эндпоинты уровня аккаунта отвечают 403 no_account.
Пагинация
Ответ любого списка содержит одни и те же три поля:
Поле
Что означает
returned
Сколько строк в этом ответе.
truncated
false = это всё. true = существует больше, чем вы получили.
limit
Фактически использованный размер страницы, после усечения.
Чтобы запросить остальное, там, где это возможно, в ответе есть ещё одно поле:
Поле
Где
Что делать
nextOffset
/conversations, /contacts
Повторите запрос с ?offset=, равным этому числу.
nextFrom
/bookings, /bookings/busy
Повторите запрос с ?from=, равным этой дате. Строки за эту дату придут повторно — отфильтруйте дубликаты по id.
nextBefore
/handoffs
Повторите запрос с ?before=, равным этому времени. Эта секунда тоже придёт повторно — отфильтруйте дубликаты по id.
maxLimit
/conversations/{channel}/{userId}
Наибольший ?limit=, который принимает этот эндпоинт.
Лимит
Значение
?limit=
Максимум 500, по умолчанию 100
Стенограмма одной переписки
До 900
total
Только там, где это факт: /conversations, /assistants. В других местах его нет.
Опирайтесь только на truncated: false. Не выводите полноту из returned < limit.
1. База знаний
Чтение и запись базы знаний · права knowledge:read, knowledge:write · уровень ассистента · пакет: корпоративный.
Для всех эндпоинтов также: 401, 403, 429, 500 — Ошибки и лимиты.
Разделы
Раздел
Тип
Поля записи и ограничения
POST
PATCH
description
string
—
Заменяется
Заменяется
services
array
Не более 200. name — обязательно; description, price, priceUnit, durationMinutes — нет. price — свободный текст («40 ₾», «от 50 ₾»); durationMinutes — положительное целое.
Заменяется целиком
Сопоставляется по name без учёта регистра и пробельных символов в начале и в конце: совпадение обновляется, остальное добавляется
faq
array
Не более 300. question и answer — оба обязательны.
Заменяется целиком
Сопоставляется по question по тому же правилу
rules
array of string
Не более 100. Пустая строка не допускается.
Заменяется целиком
Добавляется, если ещё нет; ничего не удаляется
documents
array
Не более 10 в одном запросе; всего у ассистента 10 источников, включая загруженные в личном кабинете. id — обязательно, A-Za-z0-9_.:-, от 1 до 64 символов; label — по умолчанию id; text — string, не более 8 000 символов.
Заменяется; документ, записанный через API, но не указанный в запросе, удаляется
Обновляется по id; остальное не затрагивается
services[].description и services[].price — только string; значение другого типа молча пропускается, ошибка не возвращается.
services[].price никогда не считается числом: ассистент цитирует его дословно. Цена товара — в целых тетри — находится в API продукции.
services[].priceUnit — единица цены, из закрытого списка: visit, procedure, night, month, person, item, hour, from (начальная цена). Другое значение мы не сможем прочитать и вернём invalid_service; единицу мы сами не выбираем, потому что это было бы утверждением о вашей цене. Если цена — просто цена этой одной позиции, не присылайте поле: тогда ассистент назовёт только число.
import os
import requests
res = requests.get(
"https://www.botai.ge/api/v1/knowledge",
headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
timeout=30,
)
print(res.json())
Ответ
{
"clientId": "demo-salon",
"description": "Салон красоты в Ваке, с 2011 года.",
"services": [{"name": "Стрижка", "price": "40 ₾", "durationMinutes": 45}],
"faq": [{"question": "У вас есть парковка?", "answer": "Да, во дворе."}],
"rules": ["Не придумывай цену — только из списка"],
"documents": [
{
"id": "returns-policy",
"label": "Правила возврата",
"text": "Возврат возможен в течение 14 дней с момента покупки, при наличии чека.",
"charCount": 61,
"updatedAt": "2026-08-20T11:02:00.000Z"
}
]
}
Поля ответа
Поле
Тип
Примечание
clientId
string
Ассистент ключа.
description
string
Пустая строка, если не записано.
services
array
name, description, price, priceUnit, durationMinutes — то, что записано.
faq
array
question, answer.
rules
array of string
documents
array
Только записанные через API: id, label, text, charCount, updatedAt (ISO 8601). Загруженные в личном кабинете не возвращаются.
Ошибки
Статус
error
Когда
404
assistant_not_found
Ассистент ключа больше не существует.
POST/api/v1/knowledgeknowledge:write
Указанный раздел заменяется целиком; неуказанный остаётся как был.
Запрос
curl
curl -X POST https://www.botai.ge/api/v1/knowledge \
-H "Authorization: Bearer $CORPORATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Салон красоты в Ваке, с 2011 года.",
"services": [
{"name": "Стрижка", "price": "40 ₾", "durationMinutes": 45},
{"name": "Маникюр", "price": "30 ₾", "durationMinutes": 60}
],
"documents": [
{
"id": "returns-policy",
"label": "Правила возврата",
"text": "Возврат возможен в течение 14 дней с момента покупки, при наличии чека."
}
]
}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
description: "Салон красоты в Ваке, с 2011 года.",
services: [
{ name: "Стрижка", price: "40 ₾", durationMinutes: 45 },
{ name: "Маникюр", price: "30 ₾", durationMinutes: 60 },
],
documents: [
{
id: "returns-policy",
label: "Правила возврата",
text: "Возврат возможен в течение 14 дней с момента покупки, при наличии чека.",
},
],
}),
});
console.log(res.status, await res.json());
Python
import os
import requests
res = requests.post(
"https://www.botai.ge/api/v1/knowledge",
headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
json={
"description": "Салон красоты в Ваке, с 2011 года.",
"services": [
{"name": "Стрижка", "price": "40 ₾", "durationMinutes": 45},
{"name": "Маникюр", "price": "30 ₾", "durationMinutes": 60},
],
"documents": [
{
"id": "returns-policy",
"label": "Правила возврата",
"text": "Возврат возможен в течение 14 дней с момента покупки, при наличии чека.",
},
],
},
timeout=30,
)
print(res.status_code, res.json())
Превышен лимит раздела (200 / 20 / 300 / 100 / 10), или источников знаний у ассистента всего больше 10.
413
document_too_long
text документа длиннее 8 000 символов.
502
write_failed
Часть записи выполнена, часть — нет. В ответе: applied, failed.
Валидация проходит до записи: после 400 и 413 ничего не изменилось.
Пустое тело ({}) базу не очищает — 400 nothing_to_write. А пустой массив ("rules": []) выполняется и очищает раздел.
Документ длиннее 8 000 символов здесь отклоняется и не обрезается; разделите его на части. В личном кабинете иначе: там загруженный файл принимается, сохраняются первые 8 000 символов, и карточка источника показывает, сколько мы прочитали и сколько передаётся ассистенту. Здесь мы отклоняем, потому что этот эндпоинт вызывает программа, и она может разделить текст.
Из всех источников одного ассистента — записанных через API и загруженных в личном кабинете вместе — ассистенту передаётся в сумме 14 000 символов, начиная с самых новых. Документ сверх этого лимита хранится, но в ответах не участвует.
502 write_failed: конфигурация записывается одной операцией, документы — по отдельности. Ничего не удалено; тот же запрос можно безопасно повторить.
POST и PATCH — один эндпоинт: очистка базы происходит только выбором метода, флага в теле нет.
PATCH/api/v1/knowledgeknowledge:write
Указанный раздел сливается с существующим; ничего не удаляется. Тело и ошибки — как для POST.
Запрос
curl
curl -X PATCH https://www.botai.ge/api/v1/knowledge \
-H "Authorization: Bearer $CORPORATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"faq": [
{
"question": "Можно оплатить картой?",
"answer": "Да, и картой, и наличными."
}
],
"rules": ["Всегда обращайся к гостю по имени"]
}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
faq: [
{
question: "Можно оплатить картой?",
answer: "Да, и картой, и наличными.",
},
],
rules: ["Всегда обращайся к гостю по имени"],
}),
});
console.log(res.status, await res.json());
Python
import os
import requests
res = requests.patch(
"https://www.botai.ge/api/v1/knowledge",
headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
json={
"faq": [
{
"question": "Можно оплатить картой?",
"answer": "Да, и картой, и наличными.",
},
],
"rules": ["Всегда обращайся к гостю по имени"],
},
timeout=30,
)
print(res.status_code, res.json())
channel, userId, lastMessage, lastRole (user или assistant), lastTimestamp (ISO 8601), messageCount.
returned, limit, offset
integer
Сколько пришло; использованный размер страницы; откуда.
total
integer
Длина списка. При countsComplete: false — нижняя граница.
truncated
boolean
true — существует больше, или countsComplete: false.
nextOffset
integer
Только если существует следующая страница: повторите запрос с ?offset=, равным этому числу.
countsComplete
boolean
false — сканирование остановилось на лимите (см. ниже).
countsComplete: false — единственный лимит, за который offset выйти не может. Список строится сканированием сохранённых сообщений ассистента, и сканирование останавливается на 20 000 строках. За его пределами total и каждый messageCount — нижняя граница, а самой старой переписки в списке нет.
integer, number | null, string | null, ISO 8601 | null
Оценки; рейтинг и комментарий — последней оценки, а не лучшей.
manualStage
string | null
new, qualified, booked, won, lost — этап CRM, установленный человеком или системой.
manualStageSource
string | null
manual — человеком; system — автоматически из-за бронирования.
manualNote, manualUpdatedAt
string | null, ISO 8601 | null
Заметка и её время.
Ошибки
Статус
error
Когда
500
contacts_unreadable
Нам не удалось прочитать базу контактов. Это намеренно не пустой список: «контактов нет» и «не удалось прочитать» — разные факты. Если это продолжается — напишите нам.
GET/api/v1/handoffsconversations:read
Где клиент попросил человека. От новых к старым.
Параметры
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
limit
integer
Нет
100 · макс. 500
Искажённое значение — значение по умолчанию, не ошибка.
open
string
Нет
—
true — только неотвеченные (acknowledgedAt: null). Другое значение — все.
null — клиент всё ещё ждёт. «Уведомление отправлено» и «кто-то взял запрос» — два разных факта.
returned, limit
integer
truncated
boolean
true — самые старые не поместились.
nextBefore
string
Только при truncated: true: повторите запрос с ?before=, равным этому времени.
Ошибки
Статус
error
Когда
400
invalid_request
before не является ISO 8601.
before включителен, поэтому граничная строка придёт повторно: отфильтруйте дубликаты по id. У двух запросов может быть один и тот же createdAt с точностью до миллисекунды, поэтому граница включительна.
truncated: true, а nextBefore нет — страницу заполнила одна отметка времени, курсор сдвинуться не может.
3. Бронирования
Чтение бронирований, занятое время, новое бронирование и отмена · права bookings:read, bookings:write · уровень ассистента · пакет: корпоративный.
Для всех эндпоинтов также: 401, 403, 429, 500 — Ошибки и лимиты.
Дата и время читаются по тбилисскому времени (Asia/Tbilisi).
GET/api/v1/bookingsbookings:read
Список бронирований по дате и времени, в порядке течения дня.
Параметры
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
from
string
Нет
—
YYYY-MM-DD, включительно.
to
string
Нет
—
YYYY-MM-DD, включительно.
limit
integer
Нет
100 · макс. 500
Искажённое значение — значение по умолчанию, не ошибка.
Словами магазина; не-null — бронирование отклонено и также имеет cancelled: true.
attended
boolean | null
true — человек отметил «пришёл»; false — «не пришёл»; null — никто ничего не отметил.
createdAt
string
ISO 8601.
Ошибки
Статус
error
Когда
400
invalid_request
from или to не в формате YYYY-MM-DD.
attended: null — это не «не пришёл», и импортировать его так не следует.
Строки за дату из nextFrom придут повторно: отфильтруйте дубликаты по id. truncated: true, а nextFrom нет — страницу заполнил один день: запросите более узкий from / to.
GET/api/v1/bookings/busybookings:read
Занятое время — и ничего о том, кто его занял. Для расписания, которое читает «когда я свободен». Блок hours возвращает также рабочие часы недели, чтобы два отказа POST /bookings — closed_day и outside_hours — можно было проверить заранее.
date, time, service, staffName (string | null), pendingApproval (boolean). Действующие бронирования: не отменённые и не отклонённые; ожидающие подтверждения тоже входят.
returned, limit
integer
limit всегда 500.
truncated
boolean
true — в окне больше 500 бронирований.
nextFrom
string
Только при truncated: true.
source
string
bookings — только наша таблица.
hours
object
Рабочая неделя бизнеса: timeZone (всегда Asia/Tbilisi), mustFinishInside и week. Может вообще не прийти — см. ниже.
hours.week
object
Семь ключей: mon…sun. У каждого есть state: open (тогда opens и closes, HH:MM), closed или unknown.
hours.mustFinishInside
boolean
Всегда true: бронирование должно закончиться в рабочие часы, а не только начаться.
Ошибки
Статус
error
Когда
400
invalid_request
from или to не в формате YYYY-MM-DD.
Сначала проверьте truncated. Обрезанное время занято, а не свободно: бронирование в него — это двойное бронирование.
truncated: true — запросите более узкое окно: ?from= = nextFrom. nextFrom не пришёл — страницу заполнил один день, запрашивайте по дням.
source: "bookings" означает, что список отражает только нашу таблицу. Если к ассистенту подключён Google Calendar, источником истины является этот календарь, и в нём может быть запись, которую мы никогда не видели (например, внесённая вручную). Читайте это как «точно занято», но никогда как «точно свободно».
Если вы тоже подключаетесь к этому календарю, как распознать нашу запись — Google Calendar.
Часы — это неделя, а не список дат. Исключений для отдельных дней (праздник, разовое закрытие) в этом продукте нет, поэтому семь ключей — полный ответ, и от from/to он не растёт. Дата переводится в день недели по Asia/Tbilisi — opens и closes — местное время этого же пояса, а не UTC.
unknown не означает «закрыто». Это значит, что владелец ничего понятного для этого дня не указал. В такой день мы не отклоняем бронирование по причине часов: closed_day и outside_hours выдаются только по тому, что владелец действительно ввёл. Все три состояния различны и друг в друга не переводятся.
Если hours вообще не пришёл — нам не удалось прочитать параметры ассистента. Это не «часов нет»: отсутствие означает «мы вам не сказали», и в этом случае о дне ничего заключить нельзя. Расписание при этом корректно — ошибка чтения конфигурации его не ломает.
Источник часов тот же, что и у отказа при записи, — одна функция, один ответ. Поэтому запись в часы, опубликованные здесь, не может вернуть closed_day или outside_hours; а slot_taken может, потому что он касается времени, а не дня.
POST/api/v1/bookingsbookings:write
Новое бронирование. Собственный параметр ассистента «Бронирование требует моего подтверждения» действует и для этого запроса.
Поля тела
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
userId
string
Да
—
Идентификатор клиента в вашей системе; по нему бронирование связывается с контактом и перепиской.
true — бронирование ожидает подтверждения владельца и в календаре пока не отображается. Значение берётся из параметра ассистента (по умолчанию включён) и запросом не меняется.
Ошибки
Статус
error
Когда
400
invalid_body
Тело не является объектом.
400
invalid_booking
userId, service, date или time отсутствует или искажён; field указывает, какой.
404
assistant_not_found
Ассистент ключа больше не существует.
409
slot_taken
Время уже занято — в нашем расписании или в календаре. Ничего не забронировано; выберите другое.
409
closed_day
В этот день бизнес закрыт. Повторная попытка на ту же дату вернёт тот же ответ. Заранее: в hours.week у этого дня state равен closed.
409
outside_hours
Время выходит за рабочие часы, или бронирование не заканчивается до их окончания. Повторная попытка на то же время вернёт тот же ответ. Заранее: opens/closes в hours.week.
Занятость проверяется при каждой записи — до 2026-09-20 она проверялась только тогда, когда к ассистенту был подключён Google Calendar и pendingApproval был false, то есть самый нагруженный случай — очередь запросов, ожидающих подтверждения, — был именно тем, что никто не проверял. Теперь наши собственные бронирования и Google — единый набор занятого времени, и запрос, ожидающий подтверждения, тоже занимает час. GET /bookings/busy по-прежнему остаётся быстрой предварительной проверкой, но больше не обязателен.
Время сверяется с рабочими часами, и бронирование должно поместиться в них целиком: в закрытый день — closed_day, вне часов — outside_hours. Оба — 409, и оба устойчивы: повторный запрос на то же время вернёт тот же ответ. Услуга по-прежнему не сверяется со списком услуг ассистента, а дата — с прошлым.
Оба проверяются заранее, начиная с 2026-09-20: GET /bookings/busy вместе с расписанием возвращает блок hours — семь дней недели, каждый open / closed / unknown, по местному времени Asia/Tbilisi. День closed — это closed_day; бронирование вне границ дня open или не заканчивающееся в них — outside_hours. В день unknown мы не отказываем по причине часов. Раньше этот текст говорил, что предварительная проверка невозможна, — на тот день так и было.
Ответ не содержит id бронирования. Чтобы отменить, найдите его в GET /bookings (userId, date, time).
Отмена бронирования, когда клиент отменил его в вашей системе: бронирование помечается отменённым, запись в Google Calendar удаляется, напоминание останавливается, GET /bookings/busy больше не учитывает это время.
Параметры
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
bookingId
integer
Да (в пути)
—
id, который возвращает GET /bookings. Тела нет.
Запрос
curl
curl -X POST https://www.botai.ge/api/v1/bookings/91/cancel \
-H "Authorization: Bearer $CORPORATE_API_KEY"
id, channel, userId, service, date, time, staffName.
Ошибки
Статус
error
Когда
400
invalid_request
bookingId не является положительным целым.
404
booking_not_found
Такое бронирование не принадлежит этому ассистенту. Чужой и несуществующий id дают одинаковый ответ.
409
ambiguous_booking
Дата, время, услуга и — где есть — телефон описывают более одного действующего бронирования (например, два специалиста, одно время, без телефона), или в этот день больше 500 действующих бронирований. Ничего не отменено.
Ничего не удаляется, поэтому это не DELETE: бронирование остаётся с cancelled: true, и GET /bookings по-прежнему его возвращает — вопрос о посещении и недельный отчёт читают эту строку.
Повтор безопасен: для уже отменённого бронирования (отменили вы, вторая копия запроса или владелец в личном кабинете) ответ — 200 и alreadyCancelled: true, а не ошибка.
При ambiguous_booking отмените в личном кабинете или напишите нам. Указание телефона при создании бронирования позволит избежать такого совпадения.
4. Ассистенты — уровень аккаунта
Список ассистентов аккаунта, создание, изменение параметров · права assistants:read, assistants:write · уровень аккаунта: ключ имеет доступ ко всем ассистентам аккаунта (два уровня) · пакет: корпоративный.
Для всех эндпоинтов также: 401, 403 (включая no_account), 429, 500 — Ошибки и лимиты.
GET/api/v1/assistantsassistants:read
Все ассистенты, которыми владеет этот аккаунт. Без пагинации.
clientId, name, active (boolean), language, tone, requireBookingApproval (boolean).
returned
integer
Сколько ассистентов возвращено.
total
integer
Сколько указано в записи аккаунта.
truncated
boolean
true — returned меньше total.
Разница между returned и total означает, что аккаунт указывает ассистента, которого больше не существует. Повторный запрос этого не изменит — напишите нам.
POST/api/v1/assistantsassistants:write
Создание ассистента. Создаётся выключенным: сначала настройте его (знания и каналы — в личном кабинете), затем включите через PATCH.
Поля тела
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
clientId
string
Да
—
Строчные латинские буквы, цифры и одиночный дефис; заглавная буква приводится к строчной. Постоянный — позже не меняется.
name
string
Да
—
Имя, которым представляется этот филиал.
active
boolean
Нет
false
Чтобы создать включённым, должно быть true; любое другое значение — выключен.
templateName
string
Нет
—
Имя исходного шаблона; если не указано, используется шаблон по умолчанию. Неизвестное имя — create_failed.
После изменения: clientId, name, active, language, tone, requireBookingApproval.
Ошибки
Статус
error
Когда
400
unsupported_field
В теле есть поле, которое этот эндпоинт не меняет; в ответе fields их перечисляет. Данные каналов (токен бота Telegram, токен страницы Meta) намеренно здесь не меняются — они остаются в личном кабинете.
400
nothing_to_write
В теле не указано ни одно поле.
400
invalid_request
Значение поля неверного типа или пустое; field указывает, какое.
404
assistant_not_found
Такой ассистент не принадлежит этому аккаунту.
409
write_conflict
Конфигурация изменилась между чтением и записью. Ничего не записано; прочитайте и повторите.
5. Распределение расхода — уровень аккаунта
Сообщения и токены по ассистентам · право usage:read · уровень аккаунта · пакет: корпоративный.
Для всех эндпоинтов также: 401, 403 (включая no_account), 429, 500 — Ошибки и лимиты.
GET/api/v1/usageusage:read
Сообщения и токены по ассистентам.
Параметры
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
from
string
Нет
Первый день текущего месяца
YYYY-MM-DD, включительно.
to
string
Нет
Сегодня
YYYY-MM-DD, включительно. Один запрос охватывает не более 92 дней.
clientId
string
Нет
Все ассистенты аккаунта
Сужает до одного ассистента; расширить не может никогда.
Во что ответы обошлись нам. Сумма по измеренным вызовам.
unmeasuredCalls
integer
Часть calls, токены которой нам не удалось измерить. Это не бесплатные вызовы.
byModel[]
array
Те же цифры по моделям: provider, model, calls, четыре поля токенов, unmeasuredCalls. Пусто, если вызовов не было.
Ошибки
Статус
error
Когда
400
invalid_request
from или to не в формате YYYY-MM-DD, или from позже to.
400
window_too_long
Окно длиннее 92 дней. В ответе maxDays.
404
assistant_not_found
clientId не принадлежит этому аккаунту.
413
window_too_large
В этом окне больше вызовов, чем помещается в один запрос (читается до 40 000). Запросите более короткое окно; сумму, которая молча перестала бы считать в середине месяца, мы не возвращаем.
messages и токены никогда не смешиваются: первое — единица счёта, второе — наш расход. Ассистент с длинной базой знаний тратит на сообщение в несколько раз больше токенов, чем бот с однострочными вопросами и ответами.
Денежного поля (cost) нет ни в одной валюте: цену токена мы нигде не публикуем.
6. API продукции
Запись каталога: товар, вариант, цена, остаток · право products:write · уровень ассистента · дополнение «Синхронизация продукции» (без него — 403 addon_required).
Для всех эндпоинтов также: 401, 403 (addon_required, scope_required), 429, 500 — Ошибки и лимиты.
Условие
Значение
Базовый URL
https://www.botai.ge/api/v1/products
Дополнение
«Синхронизация продукции» на том ассистенте, в который вы пишете. Без неё каждый запрос — 403 addon_required. Входит в «Корпоративный»; для «Старт» и «Бизнес» покупается отдельно.
Право
products:write. Без этого имени в списке прав — 403 scope_required, из каталога ничего не удаляется. Ключ, выданный без списка прав (на экране продукции), по-прежнему пишет. Дополнение и право — две отдельные проверки: обе должны дать положительный ответ.
Тело
JSON, не более 1 000 000 байт (413 body_too_large).
Ограничения
Товаров в запросе — 500; вариантов на товар — 100, в запросе — 5 000.
Частота
60 запросов в минуту на ассистента; 120 — с одного IP.
Деньги
Целые тетри: 18999 = 189.99 ₾.
Поля тела
Параметр
Тип
Обязательно
По умолчанию · лимит
Примечание
products
array
Да
1–500
Товары. Пустой массив — 400 empty_catalogue.
sourceId
integer
Нет
—
Источник каталога ассистента. Если не указан, используется собственный источник этого ассистента «Каталог из API» (создаётся при первом запросе). Возвращается в ответе. Чужой — 404 source_not_found.
Поля products[]
Поле
Тип
Обязательно
Лимит
Примечание
id
string | integer
Да
—
id товара в вашей системе: по нему мы узнаём товар при следующей записи и обновляем его; вторая копия не создаётся. Синоним — externalId.
name
string
Да
500 символов
Обязательно и для PATCH.
description
string
Нет
20 000 символов
category
string
Нет
500 символов
imageUrl
string
Нет
2 000 символов
Синоним — image.
status
string
Нет
—
active (по умолчанию), hidden, archived. Статус товара вычисляется из вариантов: один активный вариант оставляет товар активным.
variants
array
Нет
100
Если у товара одна форма, опустите: sku, цена, остаток и attributes записываются на самом товаре.
Поля products[].variants[]
Поле
Тип
Обязательно
Лимит
Примечание
id
string | integer
При условии
—
id варианта; если его нет — sku. Товар с одним вариантом может использовать id товара; товар с несколькими вариантами — нет: id или sku обязательны. Синоним — externalId.
sku
string
Нет
200 символов
priceTetri
integer | string | null
Нет
2 147 483 647
Цена; правила — ниже. Синоним — price.
salePriceTetri
integer | string | null
Нет
2 147 483 647
Цена со скидкой; учитывается только вместе с основной ценой. Синоним — salePrice.
stock
integer | string | null
Нет
2 147 483 647
Остаток; правила — ниже.
status
string
Нет
—
Как у товара.
attributes
object
Нет
20 ключей
Значение — string или число: {"Размер": "42", "Цвет": "Чёрный"}.
Читается так же, как столбец цены в фиде: "189.99", "189,99", "1 899,00 GEL", "1,899.00".
Цена в другой валюте
"45 USD" — товар остаётся, цена отбрасывается, в ответе в warnings появляется foreign_currency. Валюта ни во что не пересчитывается.
stock: null или поле отсутствует
«Мы не считаем это поштучно»: ассистент считает товар доступным.
stock: 0
«Посчитали, больше нет»: ассистент говорит, что товар закончился.
stock, строка
"in stock", "out of stock" или число в виде строки.
POST/api/v1/productsproducts:write
Полная замена: тело — это весь каталог данного источника. Всё, что вы не указали, архивируется, а не удаляется. Подходит для ночного или ежечасного полного экспорта.
Архивированные товары — те, что были в этом источнике и не были указаны в запросе.
variants
integer
Записанные варианты.
warnings[]
array
code, message (на грузинском), index (номер товара, если применимо).
Ошибки
Статус
error
Когда
400
invalid_body
Тело не является объектом; products не является массивом; sourceId не является положительным целым (field).
400
empty_catalogue
products пуст.
400
invalid_product
Товар или вариант искажён. index — номер товара в массиве (начиная с 0), field — путь к полю, например variants[0].priceTetri.
400
duplicate_product_id, duplicate_variant_id
Один и тот же id дважды в одном запросе (внутри одного товара — у варианта).
400
too_many_variants
У одного товара больше 100 вариантов.
404
source_not_found
Такой источник не принадлежит этому ассистенту.
413
too_many_products
В одном запросе больше 500 товаров.
413
too_many_variants
В одном запросе больше 5 000 вариантов.
413
body_too_large
Тело больше 1 000 000 байт; в ответе maxBytes.
502
write_failed
Часть записана, часть — нет. В ответе видно, что записано (created, updated, variants); ничего не архивировано.
Пустой POST каталог не очищает (empty_catalogue): почти всегда это ошибка вашего экспорта. Товар, который нужно снять с продажи, отправьте с "status": "archived".
Каталог больше 500: отправляйте страницы через PATCH, а товары, снимаемые с продажи, — в конце, через PATCH с "status": "archived". POST на последней странице архивировал бы всё, кроме этой страницы.
502 write_failed: тот же запрос можно безопасно повторить — товар обновляется по id.
PATCH/api/v1/productsproducts:write
Частичное обновление: обновляется или добавляется только указанный товар; ничего не архивируется. Тело и ошибки — как для POST.
В ответе PATCH поля нет: PATCH ничего не архивирует.
Прочее
Как для POST.
7. Оплата
Один запрос открывает заказ и возвращает ссылку на оплату или её QR · право payments:write · уровень ассистента · условие доступа то же, что и у API продукции: дополнение «Синхронизация продукции».
Для всех эндпоинтов также: 401, 403 (addon_required, scope_required), 429, 500 — Ошибки и лимиты.
Условие
Значение
Эндпоинт
POST https://www.botai.ge/api/v1/payments
Дополнение
«Синхронизация продукции» на том ассистенте, через который вы продаёте, — то же, что и у API продукции; нового условия здесь нет. Без неё — 403 addon_required.
Право
payments:write. Без этого имени в списке прав — 403 scope_required, заказ не открывается и ссылка на оплату не создаётся. Ключ, выданный без списка прав, продаёт. Права фиксируются при выдаче.
Деньги
Целые тетри: 18999 = 189.99 ₾.
Валюта
Та, что указана в каталоге. Картой оплачиваются GEL, USD, EUR, GBP; пересчёт нигде не выполняется.
Частота
30 продаж в минуту на ассистента; 120 запросов в минуту с одного IP.
Поля тела
Поле
Тип
Обязательно
Лимит
Примечание
variantId
string | integer
Да
128 символов
id варианта в каталоге — id из API продукции (или sku).
productId
string | integer
Нет
128 символов
Только сужает: нужен, когда один variantId в этом магазине относится к двум товарам.
quantity
integer
Нет
1–1000 · по умолчанию 1
method
string
Нет
online (по умолчанию), cod
cod — оплата при доставке.
orderRef
string
Нет
A-Za-z0-9_-, от 4 до 64 символов
Номер заказа и ключ идемпотентности. Если не укажете — мы присвоим его сами.
customer
object
Нет
name 120, phone 40, email 160
Покупатель. Длинное значение обрезается.
description
string
Нет
200 символов
При оплате картой передаётся в Quickpay. Длинное обрезается.
note
string
Нет
500 символов
Сохраняется в заказе. Длинное обрезается.
amountTetri
integer
Нет
—
Только для проверки: должно совпадать с суммой по каталогу.
currency
string
Нет
—
Только для проверки: должно совпадать с валютой каталога.
POST/api/v1/paymentspayments:write
Открывает заказ и создаёт платёж на собственном аккаунте Quickpay магазина. При online возвращаются ссылка на оплату и её QR.
Одно поле искажено; field указывает, какое. amountTetri — целые тетри, 149.99 здесь — ошибка.
403
addon_required
У ассистента нет дополнения продукции.
403
scope_required
У ключа нет payments:write; scope его называет.
404
variant_not_found
В каталоге этого ассистента такого варианта нет. Для чужого варианта ответ тот же.
409
variant_ambiguous
По одному id в этом магазине найдено два варианта. Уточните через productId.
409
variant_not_for_sale, variant_unpriced
Вариант снят с продажи, или у него не указана цена.
409
amount_mismatch, currency_mismatch
Тело указало сумму или валюту, и она не совпала с каталогом. Ничего не создано.
409
amount_not_chargeable
Сумма (цена × количество) равна нулю или превышает 2 147 483 647 тетри.
409
currency_not_chargeable
В этой валюте оплата картой не создаётся. chargeableIn перечисляет, в каких создаётся.
409
cod_disabled
Магазин не принимает оплату при доставке. methods — что осталось: ["online"] или [], когда и оплата картой не настроена (тогда способ оплаты магазин подтверждает сам).
409
payment_account_missing, payment_key_unreadable
Quickpay ещё не подключён, или сохранённый ключ больше не читается. Это должен решить владелец.
409
order_ref_taken
По этому номеру уже открыта другая продажа. Выберите новый номер.
400, 404, 409, 429, 502
payment_provider
Quickpay отказал или не отвечает. failure называет причину, message написан на грузинском; currency — если отказ касается валюты.
502
order_not_saved
Платёж создан, но у нас его записать не удалось. Повторите с тем же orderRef.
201 — заказ только что создан. 200 — по тому же orderRef та же продажа уже открыта: вы получаете ту же ссылку, и второй платёж не создаётся. Тот же orderRef для другой продажи — 409 order_ref_taken.
cod ссылку не создаёт: заказ открывается с awaiting_offline, и деньги получает курьер магазина. Способ доступен, только если владелец включил его в личном кабинете; в противном случае — 409 cod_disabled.
Сумму определяет цена варианта, а не ваш запрос: другой цены нигде нет. Пустой amountTetri — предпочтительный способ использования этого эндпоинта.
502 order_not_saved: orderRef — ключ идемпотентности, поэтому повтор возвращает тот же платёж и второй не создаёт. Если вы не прислали orderRef, он есть в ответе: повторите с ним.
message этого эндпоинта — на грузинском (в остальном API — на английском).
POST/api/v1/payments/quickpay/webhook/{clientId}
Этот эндпоинт принадлежит банку: его вызывает Quickpay, вы — никогда. Ключ и дополнение здесь не проверяются, единственная дверь — подпись. Строить ничего не нужно.
Адрес мы сами передаём Quickpay при создании платежа. Результат оплаты виден в личном кабинете, на экране заказов.
error — устойчивый код; message — на английском (для оплаты — на грузинском); field, index — где проблема в конкретной записи. См. также: 7. Оплата, Обработка ошибок.
Статус
error
Что произошло
400
invalid_body
Тело не является объектом, или раздел неверного типа.
Одна запись искажена. index и field указывают, какая. Строке в extraPrices нужны и label, и price; наполовину заполненную мы не отбрасываем — отклоняем весь запрос.
400
duplicate_document_id
Один и тот же id пришёл дважды в одном запросе.
400
invalid_booking
Обязательное поле бронирования отсутствует или искажено.
400
invalid_request
Параметр, часть пути или обязательное поле искажены: id бронирования, не являющийся положительным целым; name, отсутствующий в POST /assistants.
400
invalid_product
API продукции: один товар или вариант искажён. index и field указывают, какой.
400
empty_catalogue
API продукции: products пуст. Пустой POST каталог не очищает — почти всегда это ошибка вашего экспорта. Снимаемое с продажи отправляйте с "status": "archived".
400
duplicate_product_id / duplicate_variant_id
API продукции: один и тот же id дважды в одном запросе.
400
invalid_client_id
clientId имеет недопустимый вид.
400
create_failed
Не удалось создать ассистента: clientId занят другим аккаунтом, или templateName с таким именем не существует. Ответ не называет причину.
400
unsupported_field
В PATCH /assistants передано поле, которое он не меняет.
400
window_too_long
Окно расхода длиннее 92 дней.
401
unauthorized
Ключ отсутствует, неизвестен, искажён или отозван.
403
plan_required
Аккаунт не на корпоративном пакете.
403
scope_required
У ключа нет права, которое требует этот эндпоинт. scope его называет.
403
addon_required
У ассистента нет дополнения продукции.
403
no_account
У ассистента ключа нет аккаунта-владельца, поэтому эндпоинты уровня аккаунта ему недоступны.
403
bot_limit_reached
Превышен лимит ассистентов аккаунта.
404
assistant_not_found
Такой ассистент не принадлежит этому аккаунту.
404
booking_not_found
Такое бронирование не принадлежит этому ассистенту.
404
source_not_found
Такой источник каталога не принадлежит этому ассистенту.
409
write_conflict
POST / PATCH /knowledge и PATCH /assistants/{clientId}: конфигурация ассистента изменилась между чтением и записью. Ничего не записано — ни конфигурация, ни документы. Прочитайте текущее состояние и отправьте заново.
409
client_id_taken
POST /assistants: у этого аккаунта уже есть ассистент с таким clientId.
409
slot_taken
Время занял кто-то другой между проверкой и записью. Ничего не забронировано.
409
closed_day
В этот день бизнес закрыт — это не гонка, и повторная попытка не поможет. Заранее видно в блоке hours ответа GET /bookings/busy.
409
outside_hours
Время выходит за рабочие часы — это не гонка, и повторная попытка не поможет. Заранее видно в блоке hours ответа GET /bookings/busy.
409
ambiguous_booking
Отмена затронула бы более одного бронирования. Ничего не отменено.
API продукции: в одном запросе больше 500 товаров.
400 / 413
too_many_variants
API продукции: превышен лимит вариантов на один товар или в одном запросе.
413
window_too_large
В этом окне больше вызовов, чем может прочитать один запрос.
429
rate_limited
Слишком много запросов в минуту для этого ассистента. retryAfterMs говорит, сколько ждать.
429
too_many_attempts
Слишком много запросов в минуту с этого IP, подсчитанных до того, как мы посмотрим на ключ.
500
internal_error
Наша ошибка. Повторите.
500
contacts_unreadable
GET /contacts: нам не удалось прочитать базу контактов. Это намеренно не пустой список — «контактов нет» и «не удалось прочитать» — разные факты. Если продолжается — напишите нам.
502
write_failed
Часть записи выполнена, часть — нет; ничего не удалено. Ответ говорит, что записано: applied и failed (база знаний), created и updated (каталог). Тот же запрос можно безопасно повторить.
502
attach_failed
Ассистент создан, но нам не удалось привязать его к аккаунту. Не повторяйте — напишите нам; повтор вернёт только create_failed.
Отклонённое тело ничего не записывает. Валидация выполняется до первой записи: после 400 всё остаётся как было — даже корректные разделы того же запроса не записаны.
Лимит
Корпоративный API
API продукции
Тело
512 000 байт
1 000 000 байт
Запросов в минуту, на ассистента
120
60
Запросов в минуту, с одного IP
120
120
Страница списка
500 строк
500 товаров
Два 429 — два независимых счётчика: too_many_attempts — на эндпоинт (до проверки ключа), rate_limited — на ассистента. Переполнение одного не расходует другой.
Обработка ошибок
Правило повтора зависит от кода, а не от статуса: один и тот же 502 иногда повторяется, иногда нет.
Статус и error
Повторять?
Действие
429rate_limited, too_many_attempts
Да
Подождите retryAfterMs миллисекунд из тела ответа и повторите тот же запрос.
500internal_error
Да
Повторяйте с экспоненциальной паузой (0,5 с, 1, 2, 4…), ограниченное число раз. В POST /payments всегда передавайте orderRef: тот же orderRef возвращает тот же платёж и второй не создаёт.
500contacts_unreadable
Позже
Сбой на нашей стороне. Не считайте ответ пустым списком. Если продолжается — напишите нам.
502write_failed
Да, без изменений
Запись выполнена частично, ничего не удалено. Ответ говорит, что записано; запрос идемпотентен.
502order_not_saved
Да, с тем же orderRef
Платёж создан, но у нас не записан. Повтор с тем же orderRef возвращает тот же платёж. Если вы не прислали orderRef, он есть в ответе: повторите с ним.
502attach_failed
Нет
Ассистент создан, но не привязан к аккаунту. Повтор вернёт create_failed. Напишите нам.
409write_conflict
После чтения
Ничего не записано. Выполните GET /knowledge или GET /assistants и отправьте заново.
409slot_taken
Нет, без изменений
Ничего не забронировано. Выберите другое время.
409closed_day
Нет, без изменений
Ничего не забронировано. Выберите другой день — попытка на ту же дату всегда вернёт то же самое. Какие дни закрыты, показывает hours в GET /bookings/busy.
409outside_hours
Нет, без изменений
Ничего не забронировано. Выберите время в рабочие часы — попытка на тот же час всегда вернёт то же самое. Часы — в hours ответа GET /bookings/busy.
409ambiguous_booking
Нет
Ничего не отменено. Отмените в личном кабинете или напишите нам.
400, 401, 403, 404, 413 и остальные 409
Нет, без изменений
Исправить нужно запрос, ключ, пакет или право; message, field, index говорят, что именно. 401 — ключ. 403 plan_required, addon_required, scope_required — нужен пакет, дополнение или новый ключ с нужным правом. 413 window_too_large — более узкое окно.
Функция, реализующая приведённое выше правило: повторяются только коды, отмеченные в таблице как «Да», для остальных ошибка возвращается сразу.
Функция повтора
JavaScript
// Repeated: 429 (after retryAfterMs), 500 internal_error, 502 write_failed
// and order_not_saved. Everything else is thrown at once, attach_failed included.
const RETRY = new Set(["rate_limited", "too_many_attempts", "internal_error", "write_failed", "order_not_saved"]);
async function callApi(url, init = {}, maxAttempts = 5) {
for (let attempt = 1; ; attempt++) {
const res = await fetch(url, init);
const body = await res.json().catch(() => ({}));
if (res.ok) return body;
if (attempt >= maxAttempts || !RETRY.has(body.error)) {
throw Object.assign(new Error(`${res.status} ${body.error}: ${body.message}`), { status: res.status, body });
}
const pause = body.retryAfterMs ?? Math.min(30_000, 500 * 2 ** (attempt - 1));
await new Promise((resolve) => setTimeout(resolve, pause));
}
}
// const usage = await callApi("https://www.botai.ge/api/v1/usage", {
// headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
// });
Python
import os
import time
import requests
# Repeated: 429 (after retryAfterMs), 500 internal_error, 502 write_failed
# and order_not_saved. Everything else raises at once, attach_failed included.
RETRY = {"rate_limited", "too_many_attempts", "internal_error", "write_failed", "order_not_saved"}
def call_api(method, url, max_attempts=5, **kwargs):
for attempt in range(1, max_attempts + 1):
res = requests.request(method, url, timeout=30, **kwargs)
try:
body = res.json()
except ValueError:
body = {}
if res.ok:
return body
if attempt == max_attempts or body.get("error") not in RETRY:
raise RuntimeError(f"{res.status_code} {body.get('error')}: {body.get('message')}")
pause_ms = body.get("retryAfterMs")
time.sleep(pause_ms / 1000 if pause_ms is not None else min(30, 0.5 * 2 ** (attempt - 1)))
# usage = call_api(
# "GET",
# "https://www.botai.ge/api/v1/usage",
# headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
# )
Версии и изменения
Версия указана в базовом пути: /api/v1.
В v1 мы добавляем новые endpoint-ы и необязательные поля. Изменения существующего мы избегаем. Если понадобится изменение, нарушающее совместимость, мы предупредим заранее.
На вашей стороне: игнорируйте неизвестное поле в ответе; неизвестный код error обрабатывайте по HTTP-статусу.
Дата
Изменение
2026-09-19
v1 — текущий контракт
Google Calendar — запись ассистента
Распознавание нашей записи и занятое время в Google Calendar владельца · пакет: «Бизнес» и выше · API-ключ не используется.
Поля записи
Поле
Тип
Примечание
summary
string
<услуга> — <имя клиента>. Без имени: უცნობი მომხმარებელი («неизвестный клиент»).
description
string
Строки: ტელეფონი: … (телефон; без телефона -), არხი: … (канал), მოთხოვნილი დრო: YYYY-MM-DD HH:MM (запрошенное время); если клиент просил специалиста, также მოთხოვნილი სპეციალისტი: … (запрошенный специалист).
start, end
object
dateTime в UTC (Z), timeZone — Asia/Tbilisi. end = start + длительность услуги; без длительности — 60 минут.
transparency
string
Всегда opaque. Запись transparent в ответе freebusy не видна вовсе — ни как занятая, ни как свободная.
extendedProperties.private
object
Четыре ключа, см. ниже.
extendedProperties.private
Ключ
Значение
Назначение
botaiSource
botai.ge/booking
Постоянная метка. Стройте фильтр на ней.
botaiClientId
Идентификатор ассистента, например demo-salon
В один календарь пишут несколько ассистентов — так вы их различите.
botaiChannel
telegram, website, whatsapp, …
То же, что строка канала («Arkhi:») в поле description.
botaiRequested
Запрошенное клиентом время текстом, например 2026-09-14 14:30
То же, что строка запрошенного времени («Motkhovnili dro:») в поле description, в машиночитаемом виде.
Запрос · Google Calendar API
GET /calendar/v3/calendars/{calendarId}/events
?privateExtendedProperty=botaiSource%3Dbotai.ge%2Fbooking
Не стройте фильтр на summary или description: введённое вручную «услуга — имя» выглядит идентично.
private означает «для этой копии календаря», а не «скрытое»: все, кто читает календарь, видят и эти поля. В них нет ничего, что уже не написано в summary и description.
Номера бронирования в записи нет: запись в календаре создаётся до того, как бронирование записывается в нашу базу. Связь обратная — у нас хранится id записи Google, в вебхуке это booking.calendarEventId.
Четыре ключа вместе не образуют уникального ключа.
Календарь, настроенный на другой часовой пояс, показывает тот же момент по времени своего пояса. Это параметр календаря, а не этого API.
Не стройте фильтр на записи на весь день [დასადასტურებელი დრო] («время к подтверждению»). Новые бронирования в такой форме больше не создаются; при подтверждении старого запроса она всё же может появиться.
Вебхук бронирований — мы отправляем вам
При создании, подтверждении, отклонении и отмене бронирования мы отправляем POST на адрес, указанный владельцем · пакет: «Бизнес» и выше · вместо API-ключа — подпись HMAC.
Проверяется при каждой отправке, а не только при сохранении адреса: для аккаунта, перешедшего на «Старт», отправка прекращается.
Запрос
POST, content-type: application/json; charset=utf-8.
Попытка
Одна, с ожиданием 5 секунд. Повторов и очереди нет.
Ваш ответ
Тело мы не читаем. Любой 2xx — успех; 3xx — неудача, перенаправлению мы не следуем.
Неудача
Событие теряется. Ни предупреждение не отправляется, ни журнала нет.
Вебхук — это скорость, а не полная картина. Встреча, внесённая вручную, и пропущенное событие в нём не видны; полную картину даёт Google Calendar.
События
event
Когда
booking.status
booking.created
Бронирование записано. На занятое время — никогда.
confirmed; pending, если ассистент оставляет бронирование на подтверждение
booking.approved
Магазин подтвердил запрос. С этого момента время — обязательство.
confirmed
booking.rejected
Магазин отклонил запрос. Освободите время.
rejected
booking.cancelled
Бронирование отменено — клиентом в ассистенте или через наш API.
cancelled
webhook.test
В личном кабинете нажмите Проверить. Это демонстрационные данные (სატესტო სერვისი — «тестовая услуга», 2030-01-01, 12:00, website), а не настоящее бронирование.
confirmed
Бронирование, требующее подтверждения, даёт два события: booking.created (pending), затем booking.approved или booking.rejected. Бронирование без подтверждения — одно: booking.created (confirmed).
Неизвестный event пропускайте, но всё равно отвечайте 2xx: список будет расти.
Идентификатор ассистента — тот, что в адресе личного кабинета. Никогда не идентификатор аккаунта.
booking.service
string
Точно так, как магазин написал в списке услуг.
booking.date
string
YYYY-MM-DD, в booking.timezone, а не в UTC.
booking.time
string
HH:MM, 24-часовой формат, в booking.timezone.
booking.timezone
string
Сейчас всегда Asia/Tbilisi. Читайте значение, а не предполагайте его.
booking.durationMinutes
number
Длительность услуги; 60, если не указана. То же, что у записи в Google Calendar.
booking.staff
string | null
Специалист, к которому сделано бронирование. null — у бизнеса нет списка специалистов.
booking.staffRequested
string | null
Специалист, которого клиент попросил в бизнесе без списка специалистов. В базе отдельно не хранится, поэтому есть только в booking.created; null в последующих событиях не означает отказ клиента.
booking.channel
string
website, telegram, whatsapp, instagram, messenger. Наш канал, а не клиент.
booking.status
string
confirmed | pending | cancelled | rejected. Статус после этого события.
booking.calendarEventId
string | null
id записи Google Calendar (не календаря). null — записи нет, например для бронирования, ожидающего подтверждения.
booking.rejectedReason
string | null
Собственные слова магазина, в booking.rejected.
booking.createdAt
string
ISO 8601, время первого создания бронирования. Одинаково во всех четырёх событиях и служит ключом последовательности.
Имя и телефон клиента не отправляются: адрес вебхука магазин вводит сам, и на ошибочно введённый адрес персональные данные ушли бы незаметно.
Сопоставить события с записью клиента нельзя. Друг с другом их можно сопоставить по естественному ключу assistantId + service + date + time; createdAt отличает бронирование, которое было создано, отменено и заново создано на то же время.
Тело отправляется в компактном виде, в форме JSON.stringify (без пробелов).
Подпись
Вопрос
Правило
Подписываемые данные
v1:<timestamp>:<сырое тело> — дословно, через двоеточия. <timestamp> — значение x-botai-timestamp.
Алгоритм
HMAC-SHA256, ключ — whsec_….
Заголовок
x-botai-signature: v1=<hex>.
Временное окно
x-botai-timestamp и ваши часы должны расходиться не более чем на 300 секунд, в обе стороны.
Сравнение
За постоянное время (timingSafeEqual, compare_digest).
Проверяйте сырое тело.JSON.parse, а затем JSON.stringify не возвращают байты без изменений: меняются пробелы и форма записи чисел. Берите байты до того, как веб-фреймворк обработает тело: в Express — express.raw({ type: "application/json" }), во Flask — request.get_data(), в FastAPI — await request.body().
Отметка времени входит в подпись: благодаря этому перехваченный запрос нельзя воспроизвести после окончания окна.
Отклоняйте в обе стороны: время отправки, опережающее ваши часы, создаёт тот же риск, что и устаревшее.
Функция проверки
JavaScript
const crypto = require("node:crypto");
// rawBody — Buffer или string, ровно в том виде, в каком пришло.
// headers — заголовки с именами в нижнем регистре (Node http, Express).
function verify(rawBody, headers, secret) {
const ts = headers["x-botai-timestamp"];
const got = headers["x-botai-signature"];
if (typeof ts !== "string" || typeof got !== "string") return false;
const seconds = Number(ts);
if (!Number.isFinite(seconds)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - seconds) > 300) return false;
const expected =
"v1=" +
crypto
.createHmac("sha256", secret)
.update(`v1:${ts}:`, "utf8")
.update(rawBody)
.digest("hex");
const a = Buffer.from(got, "utf8");
const b = Buffer.from(expected, "utf8");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Python
import hashlib
import hmac
import time
# raw_body — bytes, ровно в том виде, в каком пришло.
# headers — словарь заголовков с именами в нижнем регистре (headers во Flask и FastAPI подходят).
def verify(raw_body: bytes, headers, secret: str) -> bool:
ts = headers.get("x-botai-timestamp")
got = headers.get("x-botai-signature")
if not ts or not got:
return False
try:
seconds = int(ts)
except ValueError:
return False
if abs(time.time() - seconds) > 300:
return False
material = b"v1:" + ts.encode() + b":" + raw_body
expected = "v1=" + hmac.new(secret.encode(), material, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), got.encode())
body — пример тела, приведённый выше, в компактном виде, одной строкой. В примере заголовков — подпись именно этого тела.
Вектор не пройдёт проверку временного окна: timestamp устарел. Для проверки установите часы рядом с timestamp или отключите проверку окна.
При изменении одного символа body или timestamp сравнение должно вернуть false.
Ключ
Вопрос
Правило
Формат
whsec_…; создаётся при первом сохранении адреса.
Показ
Один раз. У нас хранится в зашифрованном виде и больше не показывается; личный кабинет показывает последние четыре символа.
Потеря
Новый ключ в личном кабинете. Старый сразу перестаёт проходить проверку — установите новый в тот же момент.
Смена адреса
Ключ не меняет.
Эндпоинт
Запрос
Правило
Схема
Только https://. При http подпись читается в пути и может быть воспроизведена в пределах окна.
Сеть
Только публично разрешаемые адреса. Loopback, link-local (включая 169.254.169.254) и частные диапазоны отклоняются. Проверяется при сохранении и перед каждой отправкой.
Данные в адресе
https://user:pass@… отклоняется. Поместите токен в путь или параметр запроса либо опирайтесь на подпись.
Перенаправление
Не следуем: 3xx — неудачная отправка. Укажите конечный адрес.
Длина
Максимум 500 символов.
Сторона получателя
Быстро возвращайте 2xx. Ставьте работу в очередь и не выполняйте её внутри запроса.
Будьте идемпотентны по x-botai-delivery. Порядок доставки не гарантирован — событие может прийти после более раннего.
Неизвестный event пропускайте, но всё равно возвращайте 2xx.
Не прекращайте периодическое чтение календаря.
Возник вопрос, или что-то на этой странице не совпадает с кодом? Свяжитесь с нами — и напишите, о каком эндпоинте речь.