Перейти к содержимому

Для разработчиков

HTTP API

Управление ассистентом из программы: база знаний, переписка, бронирования, ассистенты, расход, каталог продукции, оплата.

Быстрый старт

ПараметрЗначение
Базовый URLhttps://www.botai.ge/api/v1
АутентификацияAuthorization: Bearer <ключ>. Ключ создаётся в личном кабинете: Аутентификация
ФорматJSON, UTF-8; для запросов с телом — Content-Type: application/json
ОкружениеJavaScript — Node 18+ (fetch); Python — pip install requests
Базовый URL — только с www. botai.ge (без www) возвращает перенаправление (308), а большинство HTTP-клиентов при перенаправлении не передают Authorization.

1. Ключ в переменных окружения

shell
export CORPORATE_API_KEY="cxk_Jt7q2sN9xVb0Lp4rWc8yZa3mEh6kFd1gTu5nQi2oXvA"
export PRODUCTS_API_KEY="cxk_Hn3v8mRb1zXd6Kt0Pw5jLy9cSe4uGa7fQo2iYr8sZbN"

Ключи вымышленные — подставьте свои. Каждый пример читает две переменные: CORPORATE_API_KEY — корпоративный API, PRODUCTS_API_KEY — продукция и оплата.

2. Первый запрос — что знает ассистент

Запрос
curl
curl https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
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": "salon-vake",
  "description": "Салон красоты в Ваке, с 2011 года.",
  "services": [
    { "name": "Стрижка", "price": "40 ₾", "durationMinutes": 45 }
  ],
  "faq": [
    { "question": "У вас есть парковка?", "answer": "Да, во дворе." }
  ],
  "rules": ["Не придумывай цену — только из списка"],
  "documents": []
}
  • 401 unauthorized — ключ не передан или неизвестен; чаще всего переменная пуста.
  • 403 plan_required — ключ в порядке, но аккаунт не на корпоративном пакете: Два API.
  • Остальные отказы — Ошибки и лимиты.

Эндпоинты

Все эндпоинты находятся на https://www.botai.ge. Ссылка ведёт к описанию эндпоинта.

МетодЭндпоинтПравоAPIЧто делаетРаздел
Корпоративный API
GET /api/v1/knowledge knowledge:read Корпоративный Чтение базы знаний 1
POST /api/v1/knowledge knowledge:write Корпоративный Замена указанных разделов 1
PATCH /api/v1/knowledge knowledge:write Корпоративный Слияние указанных разделов; ничего не удаляется 1
GET /api/v1/conversations conversations:read Корпоративный Список переписок 2
GET /api/v1/conversations/{channel}/{userId} conversations:read Корпоративный Стенограмма одной переписки 2
GET /api/v1/contacts conversations:read Корпоративный База контактов 2
GET /api/v1/handoffs conversations:read Корпоративный Запросы оператора 2
GET /api/v1/bookings bookings:read Корпоративный Список бронирований 3
GET /api/v1/bookings/busy bookings:read Корпоративный Занятое время и рабочие часы, без данных клиентов 3
POST /api/v1/bookings bookings:write Корпоративный Новое бронирование 3
POST /api/v1/bookings/{bookingId}/cancel bookings:write Корпоративный Отмена бронирования; повтор безопасен 3
GET /api/v1/assistants assistants:read Корпоративный Список ассистентов аккаунта 4
POST /api/v1/assistants assistants:write Корпоративный Создание ассистента; создаётся выключенным 4
PATCH /api/v1/assistants/{clientId} assistants:write Корпоративный Изменение параметров ассистента 4
GET /api/v1/usage usage:read Корпоративный Сообщения и токены по ассистентам 5
API продукции
POST /api/v1/products products:write Продукции Полная замена каталога; всё, что вы не прислали, архивируется 6
PATCH /api/v1/products products:write Продукции Частичное обновление каталога; ничего не архивируется 6
POST /api/v1/payments payments:write Продукции Заказ и ссылка на оплату или QR 7
POST /api/v1/payments/quickpay/webhook/{clientId} Без ключа Продукции Обратный вызов банка; вы его не вызываете 7
От нас к вам — это не API
POST Ваш адрес Без ключа Вебхук События бронирований; «Бизнес» и выше Вебхук

Содержание

Два API

Корпоративный APIAPI продукции
Что открывает База знаний, переписка, бронирования, ассистенты, расход Каталог (/products) и оплата (/payments)
Пакет Корпоративный; «Старт» и «Бизнес» — отказ Любой платный пакет, с дополнением
Дополнение Не требуется Синхронизация продукции на том ассистенте, в который вы пишете; входит в «Корпоративный», для «Старт» и «Бизнес» покупается отдельно
Ключ cxk_…, со списком прав cxk_…
Где создаётся Ассистент → Параметры ассистента → Прочее → Доступ к API Ассистент → Продукция → API-ключ
Базовый URL https://www.botai.ge/api/v1 — для обоих
Отказ, если условие не выполнено 403 plan_required 403 addon_required
  • Ключ, выданный на экране продукции, не открывает корпоративные эндпоинты; что открывает ключ — в разделе Права.
  • Вебхук бронирований — не API: мы отправляем вам, ключ не нужен, пакет — «Бизнес» и выше. Вебхук.

Аутентификация

Заголовок — в каждом запросе
Authorization: Bearer cxk_Jt7q2sN9xVb0Lp4rWc8yZa3mEh6kFd1gTu5nQi2oXvA
КлючПравило
Форматcxk_…
ВиденОдин раз, при создании. У нас хранится только его SHA-256, поэтому никто не сможет показать его вам повторно.
АссистентОдин ключ — один ассистент. Три филиала — три ключа.
ПраваФиксируются при выдаче: Права.
Потеря или утечкаНовый ключ, отзыв старого. Отзыв действует начиная со следующего запроса.
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Закрыто
bookings:readУровень ассистентаGET /bookings, GET /bookings/busyЗакрыто
bookings:writeУровень ассистентаPOST /bookings, POST /bookings/{bookingId}/cancelЗакрыто
products:writeУровень ассистентаPOST / PATCH /products — API продукцииОткрыто
payments:writeУровень ассистентаPOST /payments — ОплатаОткрыто
assistants:readУровень аккаунтаGET /assistantsЗакрыто
assistants:writeУровень аккаунтаPOST /assistants, PATCH /assistants/{clientId}Закрыто
usage:readУровень аккаунтаGET /usageЗакрыто
  • Права фиксируются при выдаче. Если понадобилось больше — новый ключ с новыми правами, а старый отзовите.
  • Право уровня аккаунта личный кабинет выдаёт только тому аккаунту, которому принадлежит этот ассистент.

Два уровня

УровеньКлюч имеет доступ кАссистент в запросеЧужой ассистент
Уровень ассистента Только ассистенту ключа Не указывается; присланный clientId игнорируется Указать другого ассистента нельзя
Уровень аккаунта Всем ассистентам аккаунта clientId — в пути, в теле или в ?clientId= 404 assistant_not_found — тот же ответ, что и для несуществующего
  • Право уровня аккаунта ключу ассистента не выдаётся: создать второго ассистента и прочитать расход соседнего можно только с этим правом.
  • Если у ассистента нет аккаунта-владельца, эндпоинты уровня аккаунта отвечают 403 no_account.

Пагинация

Ответ любого списка содержит одни и те же три поля:

ПолеЧто означает
returnedСколько строк в этом ответе.
truncatedfalse = это всё. 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 — Ошибки и лимиты.

Разделы

РазделТипПоля записи и ограниченияPOSTPATCH
descriptionstring—ЗаменяетсяЗаменяется
servicesarrayНе более 200. name — обязательно; description, price, priceUnit, durationMinutes — нет. price — свободный текст («40 ₾», «от 50 ₾»); durationMinutes — положительное целое.Заменяется целикомСопоставляется по name без учёта регистра и пробельных символов в начале и в конце: совпадение обновляется, остальное добавляется
faqarrayНе более 300. question и answer — оба обязательны.Заменяется целикомСопоставляется по question по тому же правилу
rulesarray of stringНе более 100. Пустая строка не допускается.Заменяется целикомДобавляется, если ещё нет; ничего не удаляется
documentsarrayНе более 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; единицу мы сами не выбираем, потому что это было бы утверждением о вашей цене. Если цена — просто цена этой одной позиции, не присылайте поле: тогда ассистент назовёт только число.
GET /api/v1/knowledge knowledge:read

База знаний целиком.

Запрос
curl
curl https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
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"
    }
  ]
}

Поля ответа

ПолеТипПримечание
clientIdstringАссистент ключа.
descriptionstringПустая строка, если не записано.
servicesarrayname, description, price, priceUnit, durationMinutes — то, что записано.
faqarrayquestion, answer.
rulesarray of string
documentsarrayТолько записанные через API: id, label, text, charCount, updatedAt (ISO 8601). Загруженные в личном кабинете не возвращаются.

Ошибки

СтатусerrorКогда
404assistant_not_foundАссистент ключа больше не существует.
POST /api/v1/knowledge knowledge: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())
Ответ
{
  "ok": true,
  "mode": "replace",
  "applied": ["description", "services", "documents"],
  "documents": {"written": 1, "removed": 2}
}

Поля ответа

ПолеТипПримечание
okbooleantrue — всё записано. При 502 — false или поле отсутствует.
modestringreplace.
appliedarray of stringКакие разделы записаны.
documents.writtenintegerЗаписанные документы. Поле присутствует, только если в теле был documents.
documents.removedintegerУдалённые API-документы: те, которые вы не указали в теле. Загруженные в личном кабинете никогда не затрагиваются.

Ошибки

СтатусerrorКогда
400invalid_bodyТело не является объектом, или раздел имеет неверный тип (field).
400nothing_to_writeВ теле не указан ни один раздел.
400invalid_service, invalid_extra_price, invalid_faq, invalid_rule, invalid_documentОдна запись искажена; index и field указывают, какая.
400duplicate_document_idОдин и тот же id дважды в одном запросе.
404assistant_not_foundАссистент ключа больше не существует.
409write_conflictКонфигурация ассистента изменилась между чтением и записью. Ничего не записано; повторите запрос.
413too_many_services, too_many_extra_prices, too_many_faq, too_many_rules, too_many_documentsПревышен лимит раздела (200 / 20 / 300 / 100 / 10), или источников знаний у ассистента всего больше 10.
413document_too_longtext документа длиннее 8 000 символов.
502write_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/knowledge knowledge: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())
Ответ
{"ok": true, "mode": "merge", "applied": ["faq", "rules"]}

Поля ответа

ПолеТипПримечание
ok, appliedboolean, array of stringКак для POST.
modestringmerge.
documents.writtenintegerТолько если в теле был documents. removed в ответе PATCH нет: PATCH ничего не удаляет.
  • Правило слияния разделов — в таблице выше.
  • Пустой массив в PATCH ничего не меняет. description и в PATCH заменяется целиком; "" его очищает.

2. Переписка и лиды

Переписка, контакты и запросы оператора · право conversations:read (на всех четырёх эндпоинтах) · уровень ассистента · пакет: корпоративный.

Для всех эндпоинтов также: 401, 403, 429, 500 — Ошибки и лимиты.

GET /api/v1/conversations conversations:read

Список переписок: одна строка на каждую пару (channel, userId), сначала с последней активностью.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
limitintegerНет100 · макс. 500Искажённое значение — значение по умолчанию, не ошибка.
offsetintegerНет0Искажённое значение — 0.
Запрос
curl
curl "https://www.botai.ge/api/v1/conversations?limit=50&offset=0" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 50, offset: 0 });
const res = await fetch(`https://www.botai.ge/api/v1/conversations?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 50, "offset": 0},
    timeout=30,
)
print(res.json())
Ответ
{
  "conversations": [
    {
      "channel": "website",
      "userId": "w_8fa2c41e",
      "lastMessage": "Спасибо!",
      "lastRole": "user",
      "lastTimestamp": "2026-08-22T09:14:02.000Z",
      "messageCount": 11
    }
  ],
  "returned": 1,
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": false,
  "countsComplete": true
}

Поля ответа

ПолеТипПримечание
conversations[]arraychannel, userId, lastMessage, lastRole (user или assistant), lastTimestamp (ISO 8601), messageCount.
returned, limit, offsetintegerСколько пришло; использованный размер страницы; откуда.
totalintegerДлина списка. При countsComplete: false — нижняя граница.
truncatedbooleantrue — существует больше, или countsComplete: false.
nextOffsetintegerТолько если существует следующая страница: повторите запрос с ?offset=, равным этому числу.
countsCompletebooleanfalse — сканирование остановилось на лимите (см. ниже).
  • countsComplete: false — единственный лимит, за который offset выйти не может. Список строится сканированием сохранённых сообщений ассистента, и сканирование останавливается на 20 000 строках. За его пределами total и каждый messageCount — нижняя граница, а самой старой переписки в списке нет.
  • Если вам нужна вся история — напишите нам.
GET /api/v1/conversations/{channel}/{userId} conversations:read

Стенограмма одной переписки, от старых сообщений к новым.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
channelstringДа (в пути)—Значение conversations[].channel.
userIdstringДа (в пути)—Значение conversations[].userId; кодируется в URL.
limitintegerНет100 · макс. 900Возвращается столько последних сообщений.
Запрос
curl
curl "https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e?limit=100" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 100 });
const res = await fetch(`https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 100},
    timeout=30,
)
print(res.json())
Ответ
{
  "channel": "website",
  "userId": "w_8fa2c41e",
  "messages": [
    {"role": "user", "text": "Когда вы открыты?", "timestamp": "2026-08-22T09:12:41.000Z"},
    {
      "role": "assistant",
      "text": "Каждый день 10:00-20:00.",
      "timestamp": "2026-08-22T09:12:43.000Z"
    }
  ],
  "returned": 2,
  "limit": 100,
  "truncated": false
}

Поля ответа

ПолеТипПримечание
channel, userIdstringКак было передано в пути.
messages[]arrayrole (user или assistant), text, timestamp (ISO 8601). От старых к новым.
returned, limitinteger
truncatedbooleantrue — у переписки отсутствует начало: возвращаются последние limit сообщений.
maxLimitintegerТолько при truncated: true: 900.
  • 900 — не случайное число: для одной переписки хранится ровно столько сообщений, поэтому ?limit=900 всегда возвращает всю переписку.
  • total нет; truncated: false означает, что returned — вся переписка.
  • Несуществующая пара — 200 с пустым messages, не 404.
GET /api/v1/contacts conversations:read

База контактов: одна строка на человека — с тем, что мы о нём знаем из переписки, бронирований, запросов оператора и оценок.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
limitintegerНет100 · макс. 500Искажённое значение — значение по умолчанию, не ошибка.
offsetintegerНет0Искажённое значение — 0.
Запрос
curl
curl "https://www.botai.ge/api/v1/contacts?limit=50&offset=0" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 50, offset: 0 });
const res = await fetch(`https://www.botai.ge/api/v1/contacts?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 50, "offset": 0},
    timeout=30,
)
print(res.json())
Ответ
{
  "contacts": [
    {
      "channel": "website",
      "userId": "w_8fa2c41e",
      "name": "Нино",
      "phone": "+995000123456",
      "email": null,
      "firstSeen": "2026-08-20T10:02:11.000Z",
      "lastSeen": "2026-08-22T09:14:02.000Z",
      "messageCount": 11,
      "inboundMessageCount": 6,
      "lastMessageAt": "2026-08-22T09:14:02.000Z",
      "bookingCount": 1,
      "cancelledCount": 0,
      "rejectedCount": 0,
      "pendingCount": 1,
      "attendedCount": 0,
      "noShowCount": 0,
      "unknownOutcomeCount": 0,
      "needsAttendanceCount": 0,
      "lastBookingAt": null,
      "nextBookingAt": "2026-09-01T08:00:00.000Z",
      "lastBookingMadeAt": "2026-08-22T09:00:00.000Z",
      "oldestPendingAt": "2026-08-22T09:00:00.000Z",
      "lastAttendedAt": null,
      "handoffCount": 0,
      "lastHandoffAt": null,
      "reviewCount": 0,
      "reviewRating": null,
      "reviewComment": null,
      "lastReviewAt": null,
      "manualStage": null,
      "manualStageSource": null,
      "manualNote": null,
      "manualUpdatedAt": null
    }
  ],
  "returned": 1,
  "offset": 0,
  "limit": 50,
  "truncated": false
}

Поля ответа

ПолеТипПримечание
contacts[]arrayОдин человек — поля ниже.
returned, offset, limitinteger
truncatedbooleantrue — существует больше.
nextOffsetintegerТолько при truncated: true: повторите запрос с ?offset=, равным этому числу.

Поля contacts[]

ПолеТипПримечание
channel, userIdstringКлюч человека. Та же пара, что и в /conversations.
name, phone, emailstring | nullПоследнее непустое значение из бронирований — другого источника нет.
firstSeen, lastSeenISO 8601 | nullПервый и последний контакт: сообщение, бронирование, запрос оператора, оценка.
messageCount, inboundMessageCountintegerВсе сообщения; только написанные им.
lastMessageAtISO 8601 | null
bookingCountintegerДействующие бронирования: не отменённые и не отклонённые.
pendingCountintegerЧасть bookingCount, ожидающая подтверждения.
cancelledCount, rejectedCountinteger
attendedCount, noShowCountintegerЧеловек отметил «пришёл» / «не пришёл».
unknownOutcomeCountintegerПрошедшие действующие бронирования, по которым никто ничего не отметил. Это не «не пришёл».
needsAttendanceCountintegerЧасть предыдущего поля, по которой личный кабинет всё ещё запрашивает ответ.
lastBookingAt, nextBookingAtISO 8601 | nullПоследний прошедший и ближайший будущий визит.
lastBookingMadeAt, oldestPendingAt, lastAttendedAtISO 8601 | nullКогда в последний раз запросил бронирование; самый старый неотвеченный запрос; последнее посещение.
handoffCount, lastHandoffAtinteger, ISO 8601 | nullЗапросы оператора.
reviewCount, reviewRating, reviewComment, lastReviewAtinteger, number | null, string | null, ISO 8601 | nullОценки; рейтинг и комментарий — последней оценки, а не лучшей.
manualStagestring | nullnew, qualified, booked, won, lost — этап CRM, установленный человеком или системой.
manualStageSourcestring | nullmanual — человеком; system — автоматически из-за бронирования.
manualNote, manualUpdatedAtstring | null, ISO 8601 | nullЗаметка и её время.

Ошибки

СтатусerrorКогда
500contacts_unreadableНам не удалось прочитать базу контактов. Это намеренно не пустой список: «контактов нет» и «не удалось прочитать» — разные факты. Если это продолжается — напишите нам.
GET /api/v1/handoffs conversations:read

Где клиент попросил человека. От новых к старым.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
limitintegerНет100 · макс. 500Искажённое значение — значение по умолчанию, не ошибка.
openstringНет—true — только неотвеченные (acknowledgedAt: null). Другое значение — все.
sincestringНет—ISO 8601; включительно.
beforestringНет—ISO 8601; включительно. Искажённое — 400.
Запрос
curl
curl "https://www.botai.ge/api/v1/handoffs?limit=100&open=true" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 100, open: "true" });
const res = await fetch(`https://www.botai.ge/api/v1/handoffs?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/handoffs",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 100, "open": "true"},
    timeout=30,
)
print(res.json())
Ответ
{
  "handoffs": [
    {
      "id": 4471,
      "channel": "whatsapp",
      "userId": "995000123456",
      "reason": "оператор",
      "createdAt": "2026-08-22T08:40:00.000Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null
    }
  ],
  "returned": 1,
  "limit": 100,
  "truncated": false
}

Поля ответа

ПолеТипПримечание
handoffs[]arrayid, channel, userId, reason, createdAt, acknowledgedAt, acknowledgedBy.
acknowledgedAt, acknowledgedByISO 8601 | null, string | nullnull — клиент всё ещё ждёт. «Уведомление отправлено» и «кто-то взял запрос» — два разных факта.
returned, limitinteger
truncatedbooleantrue — самые старые не поместились.
nextBeforestringТолько при truncated: true: повторите запрос с ?before=, равным этому времени.

Ошибки

СтатусerrorКогда
400invalid_requestbefore не является ISO 8601.
  • before включителен, поэтому граничная строка придёт повторно: отфильтруйте дубликаты по id. У двух запросов может быть один и тот же createdAt с точностью до миллисекунды, поэтому граница включительна.
  • truncated: true, а nextBefore нет — страницу заполнила одна отметка времени, курсор сдвинуться не может.

3. Бронирования

Чтение бронирований, занятое время, новое бронирование и отмена · права bookings:read, bookings:write · уровень ассистента · пакет: корпоративный.

Для всех эндпоинтов также: 401, 403, 429, 500 — Ошибки и лимиты.

Дата и время читаются по тбилисскому времени (Asia/Tbilisi).

GET /api/v1/bookings bookings:read

Список бронирований по дате и времени, в порядке течения дня.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
fromstringНет—YYYY-MM-DD, включительно.
tostringНет—YYYY-MM-DD, включительно.
limitintegerНет100 · макс. 500Искажённое значение — значение по умолчанию, не ошибка.
Запрос
curl
curl "https://www.botai.ge/api/v1/bookings?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-09-01", to: "2026-09-07" });
const res = await fetch(`https://www.botai.ge/api/v1/bookings?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-09-01", "to": "2026-09-07"},
    timeout=30,
)
print(res.json())
Ответ
{
  "bookings": [
    {
      "id": 91,
      "channel": "api",
      "userId": "crm-4471",
      "service": "Стрижка",
      "date": "2026-09-01",
      "time": "12:00",
      "customerName": "Нино",
      "customerPhone": "5xx xx xx xx",
      "customerEmail": null,
      "staffName": null,
      "cancelled": false,
      "pendingApproval": true,
      "rejectedReason": null,
      "attended": null,
      "createdAt": "2026-08-22T09:00:00.000Z"
    }
  ],
  "returned": 1,
  "limit": 100,
  "truncated": false
}

Поля ответа

ПолеТипПримечание
bookings[]arrayПоля ниже.
returned, limitinteger
truncatedbooleantrue — существует больше.
nextFromstringТолько при truncated: true: повторите запрос с ?from=, равным этой дате.

Поля bookings[]

ПолеТипПримечание
idintegerЕдинственный точный идентификатор бронирования; при отмене он указывается в пути.
channelstringapi — ваша запись; другое — канал клиента.
userIdstring
service, date, timestringdate — YYYY-MM-DD, time — HH:MM.
customerName, customerPhone, customerEmail, staffNamestring | null
cancelledbooleantrue — отменено; в списке всё равно остаётся.
pendingApprovalbooleantrue — ожидает подтверждения владельца.
rejectedReasonstring | nullСловами магазина; не-null — бронирование отклонено и также имеет cancelled: true.
attendedboolean | nulltrue — человек отметил «пришёл»; false — «не пришёл»; null — никто ничего не отметил.
createdAtstringISO 8601.

Ошибки

СтатусerrorКогда
400invalid_requestfrom или to не в формате YYYY-MM-DD.
  • attended: null — это не «не пришёл», и импортировать его так не следует.
  • Строки за дату из nextFrom придут повторно: отфильтруйте дубликаты по id. truncated: true, а nextFrom нет — страницу заполнил один день: запросите более узкий from / to.
GET /api/v1/bookings/busy bookings:read

Занятое время — и ничего о том, кто его занял. Для расписания, которое читает «когда я свободен». Блок hours возвращает также рабочие часы недели, чтобы два отказа POST /bookings — closed_day и outside_hours — можно было проверить заранее.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
fromstringНетСегодня (по тбилисскому времени)YYYY-MM-DD, включительно.
tostringНетfromYYYY-MM-DD, включительно.
Запрос
curl
curl "https://www.botai.ge/api/v1/bookings/busy?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-09-01", to: "2026-09-07" });
const res = await fetch(`https://www.botai.ge/api/v1/bookings/busy?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/bookings/busy",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-09-01", "to": "2026-09-07"},
    timeout=30,
)
print(res.json())
Ответ
{
  "from": "2026-09-01",
  "to": "2026-09-07",
  "busy": [
    {
      "date": "2026-09-01",
      "time": "12:00",
      "service": "Стрижка",
      "staffName": null,
      "pendingApproval": true
    }
  ],
  "returned": 1,
  "limit": 500,
  "truncated": false,
  "source": "bookings",
  "hours": {
    "timeZone": "Asia/Tbilisi",
    "mustFinishInside": true,
    "week": {
      "mon": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "tue": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "wed": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "thu": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "fri": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "sat": { "state": "unknown" },
      "sun": { "state": "closed" }
    }
  }
}

Поля ответа

ПолеТипПримечание
from, tostringИспользованное окно.
busy[]arraydate, time, service, staffName (string | null), pendingApproval (boolean). Действующие бронирования: не отменённые и не отклонённые; ожидающие подтверждения тоже входят.
returned, limitintegerlimit всегда 500.
truncatedbooleantrue — в окне больше 500 бронирований.
nextFromstringТолько при truncated: true.
sourcestringbookings — только наша таблица.
hoursobjectРабочая неделя бизнеса: timeZone (всегда Asia/Tbilisi), mustFinishInside и week. Может вообще не прийти — см. ниже.
hours.weekobjectСемь ключей: mon…sun. У каждого есть state: open (тогда opens и closes, HH:MM), closed или unknown.
hours.mustFinishInsidebooleanВсегда true: бронирование должно закончиться в рабочие часы, а не только начаться.

Ошибки

СтатусerrorКогда
400invalid_requestfrom или 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/bookings bookings:write

Новое бронирование. Собственный параметр ассистента «Бронирование требует моего подтверждения» действует и для этого запроса.

Поля тела

ПараметрТипОбязательноПо умолчанию · лимитПримечание
userIdstringДа—Идентификатор клиента в вашей системе; по нему бронирование связывается с контактом и перепиской.
servicestringДа—
datestringДа—YYYY-MM-DD.
timestringДа—HH:MM, 24-часовой формат.
customerName, customerPhone, customerEmail, staffNamestringНет—
channelstringНетapiОставьте api: в продукте каждый подсчёт и экспорт группируется по каналу, а website засчитал бы бронирование в цифры виджета.
Запрос
curl
curl -X POST https://www.botai.ge/api/v1/bookings \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userId": "crm-4471",
      "service": "Стрижка",
      "date": "2026-09-01",
      "time": "12:00",
      "customerName": "Нино",
      "customerPhone": "5xx xx xx xx"
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "crm-4471",
    service: "Стрижка",
    date: "2026-09-01",
    time: "12:00",
    customerName: "Нино",
    customerPhone: "5xx xx xx xx",
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={
        "userId": "crm-4471",
        "service": "Стрижка",
        "date": "2026-09-01",
        "time": "12:00",
        "customerName": "Нино",
        "customerPhone": "5xx xx xx xx",
    },
    timeout=30,
)
print(res.status_code, res.json())
Ответ · 201 Created
{
  "ok": true,
  "date": "2026-09-01",
  "time": "12:00",
  "service": "Стрижка",
  "pendingApproval": true
}

Поля ответа

ПолеТипПримечание
okbooleantrue.
date, time, servicestringКак записано.
pendingApprovalbooleantrue — бронирование ожидает подтверждения владельца и в календаре пока не отображается. Значение берётся из параметра ассистента (по умолчанию включён) и запросом не меняется.

Ошибки

СтатусerrorКогда
400invalid_bodyТело не является объектом.
400invalid_bookinguserId, service, date или time отсутствует или искажён; field указывает, какой.
404assistant_not_foundАссистент ключа больше не существует.
409slot_takenВремя уже занято — в нашем расписании или в календаре. Ничего не забронировано; выберите другое.
409closed_dayВ этот день бизнес закрыт. Повторная попытка на ту же дату вернёт тот же ответ. Заранее: в hours.week у этого дня state равен closed.
409outside_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).
POST /api/v1/bookings/{bookingId}/cancel bookings:write

Отмена бронирования, когда клиент отменил его в вашей системе: бронирование помечается отменённым, запись в Google Calendar удаляется, напоминание останавливается, GET /bookings/busy больше не учитывает это время.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
bookingIdintegerДа (в пути)—id, который возвращает GET /bookings. Тела нет.
Запрос
curl
curl -X POST https://www.botai.ge/api/v1/bookings/91/cancel \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/bookings/91/cancel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/bookings/91/cancel",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.status_code, res.json())
Ответ
{
  "ok": true,
  "cancelled": true,
  "alreadyCancelled": false,
  "booking": {
    "id": 91,
    "channel": "api",
    "userId": "crm-4471",
    "service": "Стрижка",
    "date": "2026-09-01",
    "time": "12:00",
    "staffName": null
  }
}

Поля ответа

ПолеТипПримечание
ok, cancelledbooleanОба true.
alreadyCancelledbooleantrue — бронирование уже было отменено.
bookingobjectid, channel, userId, service, date, time, staffName.

Ошибки

СтатусerrorКогда
400invalid_requestbookingId не является положительным целым.
404booking_not_foundТакое бронирование не принадлежит этому ассистенту. Чужой и несуществующий id дают одинаковый ответ.
409ambiguous_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/assistants assistants:read

Все ассистенты, которыми владеет этот аккаунт. Без пагинации.

Запрос
curl
curl https://www.botai.ge/api/v1/assistants \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/assistants",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.json())
Ответ
{
  "assistants": [
    {
      "clientId": "demo-salon",
      "name": "Демо-салон",
      "active": true,
      "language": "ka",
      "tone": "friendly, concise",
      "requireBookingApproval": true
    }
  ],
  "returned": 1,
  "total": 1,
  "truncated": false
}

Поля ответа

ПолеТипПримечание
assistants[]arrayclientId, name, active (boolean), language, tone, requireBookingApproval (boolean).
returnedintegerСколько ассистентов возвращено.
totalintegerСколько указано в записи аккаунта.
truncatedbooleantrue — returned меньше total.
  • Разница между returned и total означает, что аккаунт указывает ассистента, которого больше не существует. Повторный запрос этого не изменит — напишите нам.
POST /api/v1/assistants assistants:write

Создание ассистента. Создаётся выключенным: сначала настройте его (знания и каналы — в личном кабинете), затем включите через PATCH.

Поля тела

ПараметрТипОбязательноПо умолчанию · лимитПримечание
clientIdstringДа—Строчные латинские буквы, цифры и одиночный дефис; заглавная буква приводится к строчной. Постоянный — позже не меняется.
namestringДа—Имя, которым представляется этот филиал.
activebooleanНетfalseЧтобы создать включённым, должно быть true; любое другое значение — выключен.
templateNamestringНет—Имя исходного шаблона; если не указано, используется шаблон по умолчанию. Неизвестное имя — create_failed.
Запрос
curl
curl -X POST https://www.botai.ge/api/v1/assistants \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "demo-salon-2", "name": "Демо-салон 2"}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ clientId: "demo-salon-2", name: "Демо-салон 2" }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/assistants",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={"clientId": "demo-salon-2", "name": "Демо-салон 2"},
    timeout=30,
)
print(res.status_code, res.json())
Ответ · 201 Created
{
  "assistant": {
    "clientId": "demo-salon-2",
    "name": "Демо-салон 2",
    "active": false,
    "language": "ka"
  },
  "botLimit": 5,
  "botCount": 4
}

Поля ответа

ПолеТипПримечание
assistantobjectclientId, name, active, language.
botLimitinteger | nullСогласованное для аккаунта количество ассистентов; до согласования — минимум пакета; null — без ограничения.
botCountintegerАссистенты на аккаунте, включая нового.

Ошибки

СтатусerrorКогда
400invalid_client_idclientId отсутствует или имеет недопустимый вид.
400invalid_requestname отсутствует.
400create_failedНе удалось создать ассистента: clientId занят другим аккаунтом, или templateName с таким именем не существует. Ответ намеренно не называет причину.
403bot_limit_reachedПревышен лимит ассистентов. В ответе: plan, botLimit, botCount.
409client_id_takenУ этого аккаунта уже есть ассистент с таким clientId.
502attach_failedАссистент создан, но не удалось привязать его к аккаунту. Не повторяйте — повтор вернёт create_failed; напишите нам.
  • Лимит относится к аккаунту и действует так же, как в личном кабинете.
  • Запросы не атомарны по отношению друг к другу: два одновременных создания оба пройдут проверку лимита. Создавайте по очереди.
PATCH /api/v1/assistants/{clientId} assistants:write

Изменение параметров ассистента. В теле допускаются только перечисленные ниже поля.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
clientIdstringДа (в пути)—Ассистент, принадлежащий этому аккаунту.
namestringНет—Непустое.
descriptionstringНет—Пустая строка очищает.
activebooleanНет—true включает ассистента.
tone, languagestringНет—Непустое.
requireBookingApprovalbooleanНет—true — бронирование требует подтверждения владельца.
Запрос
curl
curl -X PATCH https://www.botai.ge/api/v1/assistants/demo-salon-2 \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants/demo-salon-2", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ active: true }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.patch(
    "https://www.botai.ge/api/v1/assistants/demo-salon-2",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={"active": True},
    timeout=30,
)
print(res.status_code, res.json())
Ответ
{
  "assistant": {
    "clientId": "demo-salon-2",
    "name": "Демо-салон 2",
    "active": true,
    "language": "ka",
    "tone": "friendly, concise",
    "requireBookingApproval": true
  }
}

Поля ответа

ПолеТипПримечание
assistantobjectПосле изменения: clientId, name, active, language, tone, requireBookingApproval.

Ошибки

СтатусerrorКогда
400unsupported_fieldВ теле есть поле, которое этот эндпоинт не меняет; в ответе fields их перечисляет. Данные каналов (токен бота Telegram, токен страницы Meta) намеренно здесь не меняются — они остаются в личном кабинете.
400nothing_to_writeВ теле не указано ни одно поле.
400invalid_requestЗначение поля неверного типа или пустое; field указывает, какое.
404assistant_not_foundТакой ассистент не принадлежит этому аккаунту.
409write_conflictКонфигурация изменилась между чтением и записью. Ничего не записано; прочитайте и повторите.

5. Распределение расхода — уровень аккаунта

Сообщения и токены по ассистентам · право usage:read · уровень аккаунта · пакет: корпоративный.

Для всех эндпоинтов также: 401, 403 (включая no_account), 429, 500 — Ошибки и лимиты.

GET /api/v1/usage usage:read

Сообщения и токены по ассистентам.

Параметры

ПараметрТипОбязательноПо умолчанию · лимитПримечание
fromstringНетПервый день текущего месяцаYYYY-MM-DD, включительно.
tostringНетСегодняYYYY-MM-DD, включительно. Один запрос охватывает не более 92 дней.
clientIdstringНетВсе ассистенты аккаунтаСужает до одного ассистента; расширить не может никогда.
Запрос
curl
curl "https://www.botai.ge/api/v1/usage?from=2026-08-01&to=2026-08-22" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-08-01", to: "2026-08-22" });
const res = await fetch(`https://www.botai.ge/api/v1/usage?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-08-01", "to": "2026-08-22"},
    timeout=30,
)
print(res.json())
Ответ
{
  "from": "2026-08-01",
  "to": "2026-08-22",
  "assistants": [
    {
      "clientId": "demo-salon",
      "messages": 4120,
      "calls": 4408,
      "inputTokens": 5203991,
      "outputTokens": 412884,
      "cacheWriteTokens": 74110,
      "cacheReadTokens": 4711002,
      "unmeasuredCalls": 3,
      "byModel": [
        {
          "provider": "anthropic",
          "model": "claude-haiku-4-5",
          "calls": 4408,
          "inputTokens": 5203991,
          "outputTokens": 412884,
          "cacheWriteTokens": 74110,
          "cacheReadTokens": 4711002,
          "unmeasuredCalls": 3
        }
      ]
    }
  ]
}

Поля ответа

ПолеТипПримечание
from, tostringИспользованное окно.
assistants[]arrayПо одной строке на каждого ассистента аккаунта (или выбранного через clientId), включая нулевые.
messagesintegerСообщения, написанные клиентом, — единица, в которой продаётся пакет и к которой применяется лимит.
callsintegerВсего вызовов модели, включая неизмеренные.
inputTokens, outputTokens, cacheWriteTokens, cacheReadTokensintegerВо что ответы обошлись нам. Сумма по измеренным вызовам.
unmeasuredCallsintegerЧасть calls, токены которой нам не удалось измерить. Это не бесплатные вызовы.
byModel[]arrayТе же цифры по моделям: provider, model, calls, четыре поля токенов, unmeasuredCalls. Пусто, если вызовов не было.

Ошибки

СтатусerrorКогда
400invalid_requestfrom или to не в формате YYYY-MM-DD, или from позже to.
400window_too_longОкно длиннее 92 дней. В ответе maxDays.
404assistant_not_foundclientId не принадлежит этому аккаунту.
413window_too_largeВ этом окне больше вызовов, чем помещается в один запрос (читается до 40 000). Запросите более короткое окно; сумму, которая молча перестала бы считать в середине месяца, мы не возвращаем.
  • messages и токены никогда не смешиваются: первое — единица счёта, второе — наш расход. Ассистент с длинной базой знаний тратит на сообщение в несколько раз больше токенов, чем бот с однострочными вопросами и ответами.
  • Денежного поля (cost) нет ни в одной валюте: цену токена мы нигде не публикуем.

6. API продукции

Запись каталога: товар, вариант, цена, остаток · право products:write · уровень ассистента · дополнение «Синхронизация продукции» (без него — 403 addon_required).

Для всех эндпоинтов также: 401, 403 (addon_required, scope_required), 429, 500 — Ошибки и лимиты.

УсловиеЗначение
Базовый URLhttps://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 ₾.

Поля тела

ПараметрТипОбязательноПо умолчанию · лимитПримечание
productsarrayДа1–500Товары. Пустой массив — 400 empty_catalogue.
sourceIdintegerНет—Источник каталога ассистента. Если не указан, используется собственный источник этого ассистента «Каталог из API» (создаётся при первом запросе). Возвращается в ответе. Чужой — 404 source_not_found.

Поля products[]

ПолеТипОбязательноЛимитПримечание
idstring | integerДа—id товара в вашей системе: по нему мы узнаём товар при следующей записи и обновляем его; вторая копия не создаётся. Синоним — externalId.
namestringДа500 символовОбязательно и для PATCH.
descriptionstringНет20 000 символов
categorystringНет500 символов
imageUrlstringНет2 000 символовСиноним — image.
statusstringНет—active (по умолчанию), hidden, archived. Статус товара вычисляется из вариантов: один активный вариант оставляет товар активным.
variantsarrayНет100Если у товара одна форма, опустите: sku, цена, остаток и attributes записываются на самом товаре.

Поля products[].variants[]

ПолеТипОбязательноЛимитПримечание
idstring | integerПри условии—id варианта; если его нет — sku. Товар с одним вариантом может использовать id товара; товар с несколькими вариантами — нет: id или sku обязательны. Синоним — externalId.
skustringНет200 символов
priceTetriinteger | string | nullНет2 147 483 647Цена; правила — ниже. Синоним — price.
salePriceTetriinteger | string | nullНет2 147 483 647Цена со скидкой; учитывается только вместе с основной ценой. Синоним — salePrice.
stockinteger | string | nullНет2 147 483 647Остаток; правила — ниже.
statusstringНет—Как у товара.
attributesobjectНет20 ключейЗначение — string или число: {"Размер": "42", "Цвет": "Чёрный"}.

Цена и остаток

ЗначениеКак читается
Цена, JSON-число18999 = 18999 тетри. Дробное (189.99) — 400 invalid_product, в ошибке указано 18999. Отрицательное — 400.
Цена, JSON-строкаЧитается так же, как столбец цены в фиде: "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/products products:write

Полная замена: тело — это весь каталог данного источника. Всё, что вы не указали, архивируется, а не удаляется. Подходит для ночного или ежечасного полного экспорта.

Запрос
curl
curl -X POST https://www.botai.ge/api/v1/products \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "products": [
        {
          "id": "SKU-1041",
          "name": "Кожаный сапог",
          "category": "Обувь",
          "variants": [
            {
              "id": "1041-42",
              "sku": "1041-42",
              "attributes": {"Размер": "42", "Цвет": "Чёрный"},
              "priceTetri": 18999,
              "stock": 3
            },
            {
              "id": "1041-43",
              "sku": "1041-43",
              "attributes": {"Размер": "43", "Цвет": "Чёрный"},
              "priceTetri": 18999,
              "stock": 0
            }
          ]
        },
        {
          "id": "SKU-2007",
          "name": "Кожаный ремень",
          "category": "Аксессуар",
          "priceTetri": 4500,
          "stock": null
        }
      ]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/products", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    products: [
      {
        id: "SKU-1041",
        name: "Кожаный сапог",
        category: "Обувь",
        variants: [
          {
            id: "1041-42",
            sku: "1041-42",
            attributes: { "Размер": "42", "Цвет": "Чёрный" },
            priceTetri: 18999,
            stock: 3,
          },
          {
            id: "1041-43",
            sku: "1041-43",
            attributes: { "Размер": "43", "Цвет": "Чёрный" },
            priceTetri: 18999,
            stock: 0,
          },
        ],
      },
      {
        id: "SKU-2007",
        name: "Кожаный ремень",
        category: "Аксессуар",
        priceTetri: 4500,
        stock: null,
      },
    ],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/products",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "products": [
            {
                "id": "SKU-1041",
                "name": "Кожаный сапог",
                "category": "Обувь",
                "variants": [
                    {
                        "id": "1041-42",
                        "sku": "1041-42",
                        "attributes": {"Размер": "42", "Цвет": "Чёрный"},
                        "priceTetri": 18999,
                        "stock": 3,
                    },
                    {
                        "id": "1041-43",
                        "sku": "1041-43",
                        "attributes": {"Размер": "43", "Цвет": "Чёрный"},
                        "priceTetri": 18999,
                        "stock": 0,
                    },
                ],
            },
            {
                "id": "SKU-2007",
                "name": "Кожаный ремень",
                "category": "Аксессуар",
                "priceTetri": 4500,
                "stock": None,
            },
        ],
    },
    timeout=30,
)
print(res.status_code, res.json())
Ответ
{
  "ok": true,
  "mode": "replace",
  "sourceId": 7,
  "created": 2,
  "updated": 0,
  "archived": 5,
  "variants": 3,
  "warnings": []
}

Поля ответа

ПолеТипПримечание
okbooleantrue. При 502 write_failed — false.
modestringreplace.
sourceIdintegerИсточник, в который выполнена запись.
created, updatedintegerНовые и обновлённые товары.
archivedintegerАрхивированные товары — те, что были в этом источнике и не были указаны в запросе.
variantsintegerЗаписанные варианты.
warnings[]arraycode, message (на грузинском), index (номер товара, если применимо).

Ошибки

СтатусerrorКогда
400invalid_bodyТело не является объектом; products не является массивом; sourceId не является положительным целым (field).
400empty_catalogueproducts пуст.
400invalid_productТовар или вариант искажён. index — номер товара в массиве (начиная с 0), field — путь к полю, например variants[0].priceTetri.
400duplicate_product_id, duplicate_variant_idОдин и тот же id дважды в одном запросе (внутри одного товара — у варианта).
400too_many_variantsУ одного товара больше 100 вариантов.
404source_not_foundТакой источник не принадлежит этому ассистенту.
413too_many_productsВ одном запросе больше 500 товаров.
413too_many_variantsВ одном запросе больше 5 000 вариантов.
413body_too_largeТело больше 1 000 000 байт; в ответе maxBytes.
502write_failedЧасть записана, часть — нет. В ответе видно, что записано (created, updated, variants); ничего не архивировано.
  • Пустой POST каталог не очищает (empty_catalogue): почти всегда это ошибка вашего экспорта. Товар, который нужно снять с продажи, отправьте с "status": "archived".
  • Каталог больше 500: отправляйте страницы через PATCH, а товары, снимаемые с продажи, — в конце, через PATCH с "status": "archived". POST на последней странице архивировал бы всё, кроме этой страницы.
  • 502 write_failed: тот же запрос можно безопасно повторить — товар обновляется по id.
PATCH /api/v1/products products:write

Частичное обновление: обновляется или добавляется только указанный товар; ничего не архивируется. Тело и ошибки — как для POST.

Запрос
curl
curl -X PATCH https://www.botai.ge/api/v1/products \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "products": [
        {
          "id": "SKU-1041",
          "name": "Кожаный сапог",
          "variants": [{"id": "1041-42", "priceTetri": 16999, "stock": 2}]
        }
      ]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/products", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    products: [
      {
        id: "SKU-1041",
        name: "Кожаный сапог",
        variants: [{ id: "1041-42", priceTetri: 16999, stock: 2 }],
      },
    ],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.patch(
    "https://www.botai.ge/api/v1/products",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "products": [
            {
                "id": "SKU-1041",
                "name": "Кожаный сапог",
                "variants": [{"id": "1041-42", "priceTetri": 16999, "stock": 2}],
            },
        ],
    },
    timeout=30,
)
print(res.status_code, res.json())
Ответ
{
  "ok": true,
  "mode": "upsert",
  "sourceId": 7,
  "created": 0,
  "updated": 1,
  "variants": 1,
  "warnings": []
}

Поля ответа

ПолеТипПримечание
modestringupsert.
archived—В ответе 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.

Поля тела

ПолеТипОбязательноЛимитПримечание
variantIdstring | integerДа128 символовid варианта в каталоге — id из API продукции (или sku).
productIdstring | integerНет128 символовТолько сужает: нужен, когда один variantId в этом магазине относится к двум товарам.
quantityintegerНет1–1000 · по умолчанию 1
methodstringНетonline (по умолчанию), codcod — оплата при доставке.
orderRefstringНетA-Za-z0-9_-, от 4 до 64 символовНомер заказа и ключ идемпотентности. Если не укажете — мы присвоим его сами.
customerobjectНетname 120, phone 40, email 160Покупатель. Длинное значение обрезается.
descriptionstringНет200 символовПри оплате картой передаётся в Quickpay. Длинное обрезается.
notestringНет500 символовСохраняется в заказе. Длинное обрезается.
amountTetriintegerНет—Только для проверки: должно совпадать с суммой по каталогу.
currencystringНет—Только для проверки: должно совпадать с валютой каталога.
POST /api/v1/payments payments:write

Открывает заказ и создаёт платёж на собственном аккаунте Quickpay магазина. При online возвращаются ссылка на оплату и её QR.

Запрос
curl
curl -X POST https://www.botai.ge/api/v1/payments \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "variantId": "1041-42",
      "quantity": 1,
      "method": "online",
      "orderRef": "ORD-10482",
      "customer": {"name": "Нино", "phone": "+995555100200"}
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    variantId: "1041-42",
    quantity: 1,
    method: "online",
    orderRef: "ORD-10482",
    customer: { name: "Нино", phone: "+995555100200" },
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "variantId": "1041-42",
        "quantity": 1,
        "method": "online",
        "orderRef": "ORD-10482",
        "customer": {"name": "Нино", "phone": "+995555100200"},
    },
    timeout=30,
)
print(res.status_code, res.json())
Ответ · 201 Created
{
  "ok": true,
  "orderId": 812,
  "orderRef": "ORD-10482",
  "method": "online",
  "outcome": "pending",
  "amountTetri": 18999,
  "amountLabel": "189.99 ₾",
  "currency": "GEL",
  "message": "გადახდის ბმული მზადაა — გახსენით და გადაიხადეთ.",
  "checkoutUrl": "https://pay.example.com/checkout/3b1f9c1e",
  "qrSvg": "<svg …>",
  "paymentUuid": "3b1f9c1e-7a52-4d0e-9a41-5f6a2c8d0b17",
  "variantId": "1041-42",
  "quantity": 1,
  "unitAmountTetri": 18999,
  "replayed": false
}
Ответ · method: cod · 201 Created
{
  "ok": true,
  "orderId": 813,
  "orderRef": "ORD-10483",
  "method": "cod",
  "outcome": "awaiting_offline",
  "amountTetri": 18999,
  "amountLabel": "189.99 ₾",
  "currency": "GEL",
  "message": "შეკვეთა მიღებულია — თანხას მიტანისას გადაიხდით.",
  "variantId": "1041-42",
  "quantity": 1,
  "unitAmountTetri": 18999
}

Поля ответа

ПолеТипПримечание
okbooleantrue.
orderId, orderRefinteger, stringЗаказ у нас и его номер.
methodstringonline или cod.
outcomestringpending — при открытии online; awaiting_offline — при cod. При 200 (повтор) — текущее состояние заказа, например paid.
amountTetri, amountLabel, currencyinteger, string, stringСумма по каталогу: цена × количество.
messagestringНа грузинском; готовый текст для покупателя.
checkoutUrl, qrSvg, paymentUuidstringТолько при online. qrSvg — QR той же ссылки; null, если его не удалось построить.
testKeyNoticestringТолько если у магазина тестовый ключ Quickpay: деньги не списываются.
variantId, quantity, unitAmountTetristring, integer, integerЧто и по какой цене оценено.
replayedbooleantrue — Quickpay вернул платёж, уже открытый по тому же orderRef. При 201 для cod поля нет.

Ошибки

СтатусerrorКогда
400bad_requestТело не является объектом.
400variant_requiredvariantId не передан или не читается.
400bad_method, bad_quantity, bad_amount, bad_currency, bad_order_ref, bad_product_idОдно поле искажено; field указывает, какое. amountTetri — целые тетри, 149.99 здесь — ошибка.
403addon_requiredУ ассистента нет дополнения продукции.
403scope_requiredУ ключа нет payments:write; scope его называет.
404variant_not_foundВ каталоге этого ассистента такого варианта нет. Для чужого варианта ответ тот же.
409variant_ambiguousПо одному id в этом магазине найдено два варианта. Уточните через productId.
409variant_not_for_sale, variant_unpricedВариант снят с продажи, или у него не указана цена.
409amount_mismatch, currency_mismatchТело указало сумму или валюту, и она не совпала с каталогом. Ничего не создано.
409amount_not_chargeableСумма (цена × количество) равна нулю или превышает 2 147 483 647 тетри.
409currency_not_chargeableВ этой валюте оплата картой не создаётся. chargeableIn перечисляет, в каких создаётся.
409cod_disabledМагазин не принимает оплату при доставке. methods — что осталось: ["online"] или [], когда и оплата картой не настроена (тогда способ оплаты магазин подтверждает сам).
409payment_account_missing, payment_key_unreadableQuickpay ещё не подключён, или сохранённый ключ больше не читается. Это должен решить владелец.
409order_ref_takenПо этому номеру уже открыта другая продажа. Выберите новый номер.
400, 404, 409, 429, 502payment_providerQuickpay отказал или не отвечает. failure называет причину, message написан на грузинском; currency — если отказ касается валюты.
502order_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Что произошло
400invalid_bodyТело не является объектом, или раздел неверного типа.
400nothing_to_writeВ теле не указан ни один раздел.
400invalid_service / invalid_extra_price / invalid_faq / invalid_rule / invalid_documentОдна запись искажена. index и field указывают, какая. Строке в extraPrices нужны и label, и price; наполовину заполненную мы не отбрасываем — отклоняем весь запрос.
400duplicate_document_idОдин и тот же id пришёл дважды в одном запросе.
400invalid_bookingОбязательное поле бронирования отсутствует или искажено.
400invalid_requestПараметр, часть пути или обязательное поле искажены: id бронирования, не являющийся положительным целым; name, отсутствующий в POST /assistants.
400invalid_productAPI продукции: один товар или вариант искажён. index и field указывают, какой.
400empty_catalogueAPI продукции: products пуст. Пустой POST каталог не очищает — почти всегда это ошибка вашего экспорта. Снимаемое с продажи отправляйте с "status": "archived".
400duplicate_product_id / duplicate_variant_idAPI продукции: один и тот же id дважды в одном запросе.
400invalid_client_idclientId имеет недопустимый вид.
400create_failedНе удалось создать ассистента: clientId занят другим аккаунтом, или templateName с таким именем не существует. Ответ не называет причину.
400unsupported_fieldВ PATCH /assistants передано поле, которое он не меняет.
400window_too_longОкно расхода длиннее 92 дней.
401unauthorizedКлюч отсутствует, неизвестен, искажён или отозван.
403plan_requiredАккаунт не на корпоративном пакете.
403scope_requiredУ ключа нет права, которое требует этот эндпоинт. scope его называет.
403addon_requiredУ ассистента нет дополнения продукции.
403no_accountУ ассистента ключа нет аккаунта-владельца, поэтому эндпоинты уровня аккаунта ему недоступны.
403bot_limit_reachedПревышен лимит ассистентов аккаунта.
404assistant_not_foundТакой ассистент не принадлежит этому аккаунту.
404booking_not_foundТакое бронирование не принадлежит этому ассистенту.
404source_not_foundТакой источник каталога не принадлежит этому ассистенту.
409write_conflictPOST / PATCH /knowledge и PATCH /assistants/{clientId}: конфигурация ассистента изменилась между чтением и записью. Ничего не записано — ни конфигурация, ни документы. Прочитайте текущее состояние и отправьте заново.
409client_id_takenPOST /assistants: у этого аккаунта уже есть ассистент с таким clientId.
409slot_takenВремя занял кто-то другой между проверкой и записью. Ничего не забронировано.
409closed_dayВ этот день бизнес закрыт — это не гонка, и повторная попытка не поможет. Заранее видно в блоке hours ответа GET /bookings/busy.
409outside_hoursВремя выходит за рабочие часы — это не гонка, и повторная попытка не поможет. Заранее видно в блоке hours ответа GET /bookings/busy.
409ambiguous_bookingОтмена затронула бы более одного бронирования. Ничего не отменено.
413body_too_largeТело превышает лимит.
413too_many_services / too_many_extra_prices / too_many_faq / too_many_rules / too_many_documentsПревышен лимит раздела (200 / 20 / 300 / 100 / 10).
413document_too_longДокумент знаний длиннее 8 000 символов.
413too_many_productsAPI продукции: в одном запросе больше 500 товаров.
400 / 413too_many_variantsAPI продукции: превышен лимит вариантов на один товар или в одном запросе.
413window_too_largeВ этом окне больше вызовов, чем может прочитать один запрос.
429rate_limitedСлишком много запросов в минуту для этого ассистента. retryAfterMs говорит, сколько ждать.
429too_many_attemptsСлишком много запросов в минуту с этого IP, подсчитанных до того, как мы посмотрим на ключ.
500internal_errorНаша ошибка. Повторите.
500contacts_unreadableGET /contacts: нам не удалось прочитать базу контактов. Это намеренно не пустой список — «контактов нет» и «не удалось прочитать» — разные факты. Если продолжается — напишите нам.
502write_failedЧасть записи выполнена, часть — нет; ничего не удалено. Ответ говорит, что записано: applied и failed (база знаний), created и updated (каталог). Тот же запрос можно безопасно повторить.
502attach_failedАссистент создан, но нам не удалось привязать его к аккаунту. Не повторяйте — напишите нам; повтор вернёт только create_failed.
Отклонённое тело ничего не записывает. Валидация выполняется до первой записи: после 400 всё остаётся как было — даже корректные разделы того же запроса не записаны.
ЛимитКорпоративный APIAPI продукции
Тело512 000 байт1 000 000 байт
Запросов в минуту, на ассистента12060
Запросов в минуту, с одного IP120120
Страница списка500 строк500 товаров

Два 429 — два независимых счётчика: too_many_attempts — на эндпоинт (до проверки ключа), rate_limited — на ассистента. Переполнение одного не расходует другой.

Обработка ошибок

Правило повтора зависит от кода, а не от статуса: один и тот же 502 иногда повторяется, иногда нет.

Статус и errorПовторять?Действие
429 rate_limited, too_many_attempts Да Подождите retryAfterMs миллисекунд из тела ответа и повторите тот же запрос.
500 internal_error Да Повторяйте с экспоненциальной паузой (0,5 с, 1, 2, 4…), ограниченное число раз. В POST /payments всегда передавайте orderRef: тот же orderRef возвращает тот же платёж и второй не создаёт.
500 contacts_unreadable Позже Сбой на нашей стороне. Не считайте ответ пустым списком. Если продолжается — напишите нам.
502 write_failed Да, без изменений Запись выполнена частично, ничего не удалено. Ответ говорит, что записано; запрос идемпотентен.
502 order_not_saved Да, с тем же orderRef Платёж создан, но у нас не записан. Повтор с тем же orderRef возвращает тот же платёж. Если вы не прислали orderRef, он есть в ответе: повторите с ним.
502 attach_failed Нет Ассистент создан, но не привязан к аккаунту. Повтор вернёт create_failed. Напишите нам.
409 write_conflict После чтения Ничего не записано. Выполните GET /knowledge или GET /assistants и отправьте заново.
409 slot_taken Нет, без изменений Ничего не забронировано. Выберите другое время.
409 closed_day Нет, без изменений Ничего не забронировано. Выберите другой день — попытка на ту же дату всегда вернёт то же самое. Какие дни закрыты, показывает hours в GET /bookings/busy.
409 outside_hours Нет, без изменений Ничего не забронировано. Выберите время в рабочие часы — попытка на тот же час всегда вернёт то же самое. Часы — в hours ответа GET /bookings/busy.
409 ambiguous_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-19v1 — текущий контракт

Google Calendar — запись ассистента

Распознавание нашей записи и занятое время в Google Calendar владельца · пакет: «Бизнес» и выше · API-ключ не используется.

Поля записи

ПолеТипПримечание
summarystring<услуга> — <имя клиента>. Без имени: უცნობი მომხმარებელი («неизвестный клиент»).
descriptionstringСтроки: ტელეფონი: … (телефон; без телефона -), არხი: … (канал), მოთხოვნილი დრო: YYYY-MM-DD HH:MM (запрошенное время); если клиент просил специалиста, также მოთხოვნილი სპეციალისტი: … (запрошенный специалист).
start, endobjectdateTime в UTC (Z), timeZone — Asia/Tbilisi. end = start + длительность услуги; без длительности — 60 минут.
transparencystringВсегда opaque. Запись transparent в ответе freebusy не видна вовсе — ни как занятая, ни как свободная.
extendedProperties.privateobjectЧетыре ключа, см. ниже.

extendedProperties.private

КлючЗначениеНазначение
botaiSourcebotai.ge/bookingПостоянная метка. Стройте фильтр на ней.
botaiClientIdИдентификатор ассистента, например demo-salonВ один календарь пишут несколько ассистентов — так вы их различите.
botaiChanneltelegram, 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": "ტელეფონი: +995555000000\nარხი: telegram\nმოთხოვნილი დრო: 2026-09-14 14:30",
  "transparency": "opaque",
  "start": {"dateTime": "2026-09-14T10:30:00.000Z", "timeZone": "Asia/Tbilisi"},
  "end": {"dateTime": "2026-09-14T11:15:00.000Z", "timeZone": "Asia/Tbilisi"},
  "extendedProperties": {
    "private": {
      "botaiSource": "botai.ge/booking",
      "botaiClientId": "demo-salon",
      "botaiChannel": "telegram",
      "botaiRequested": "2026-09-14 14:30"
    }
  }
}
  • Не стройте фильтр на 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: список будет расти.
Заголовки запроса
POST /hooks/botai HTTP/1.1
Host: example.ge
content-type: application/json; charset=utf-8
user-agent: BotAI-Webhooks/1.0 (+https://botai.ge)
x-botai-event: booking.created
x-botai-delivery: 0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31
x-botai-timestamp: 1789000000
x-botai-signature: v1=66d7ff203a2cb9f512441e6fbbce1f43d8724346f421ff786cacd925ce067d73
ЗаголовокЗначение
x-botai-eventИмя события, то же, что event в теле. Для маршрутизации до чтения тела.
x-botai-deliveryUUID, уникальный для попытки; попытка одна, поэтому он уникален и для события. Сохраняйте для идемпотентности.
x-botai-timestampUnix-секунды в момент подписи. Входит в подписываемые данные.
x-botai-signaturev1= и 64 строчных шестнадцатеричных символов.
Тело запроса
{
  "event": "booking.created",
  "deliveryId": "0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31",
  "sentAt": "2026-09-10T00:26:40.480Z",
  "assistantId": "demo-salon",
  "booking": {
    "service": "თმის შეჭრა",
    "date": "2026-09-14",
    "time": "14:30",
    "timezone": "Asia/Tbilisi",
    "durationMinutes": 45,
    "staff": "ნინო",
    "staffRequested": null,
    "channel": "telegram",
    "status": "confirmed",
    "calendarEventId": "6k3q1m0p9r7s2t4u",
    "rejectedReason": null,
    "createdAt": "2026-09-10T00:26:39.000Z"
  }
}

Поля тела

ПолеТипПримечание
eventstringОдно из пяти перечисленных выше.
deliveryIdstringUUID v4; то же, что x-botai-delivery.
sentAtstringISO 8601, UTC. Когда мы его сформировали.
assistantIdstringИдентификатор ассистента — тот, что в адресе личного кабинета. Никогда не идентификатор аккаунта.
booking.servicestringТочно так, как магазин написал в списке услуг.
booking.datestringYYYY-MM-DD, в booking.timezone, а не в UTC.
booking.timestringHH:MM, 24-часовой формат, в booking.timezone.
booking.timezonestringСейчас всегда Asia/Tbilisi. Читайте значение, а не предполагайте его.
booking.durationMinutesnumberДлительность услуги; 60, если не указана. То же, что у записи в Google Calendar.
booking.staffstring | nullСпециалист, к которому сделано бронирование. null — у бизнеса нет списка специалистов.
booking.staffRequestedstring | nullСпециалист, которого клиент попросил в бизнесе без списка специалистов. В базе отдельно не хранится, поэтому есть только в booking.created; null в последующих событиях не означает отказ клиента.
booking.channelstringwebsite, telegram, whatsapp, instagram, messenger. Наш канал, а не клиент.
booking.statusstringconfirmed | pending | cancelled | rejected. Статус после этого события.
booking.calendarEventIdstring | nullid записи Google Calendar (не календаря). null — записи нет, например для бронирования, ожидающего подтверждения.
booking.rejectedReasonstring | nullСобственные слова магазина, в booking.rejected.
booking.createdAtstringISO 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())
Тестовый вектор
secret:    whsec_demo_only_not_a_real_secret
timestamp: 1789000000
body:      {"event":"booking.created","deliveryId":"0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31","sentAt":"2026-09-10T00:26:40.480Z","assistantId":"demo-salon","booking":{"service":"თმის შეჭრა","date":"2026-09-14","time":"14:30","timezone":"Asia/Tbilisi","durationMinutes":45,"staff":"ნინო","staffRequested":null,"channel":"telegram","status":"confirmed","calendarEventId":"6k3q1m0p9r7s2t4u","rejectedReason":null,"createdAt":"2026-09-10T00:26:39.000Z"}}
signature: v1=66d7ff203a2cb9f512441e6fbbce1f43d8724346f421ff786cacd925ce067d73
  • 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.
  • Не прекращайте периодическое чтение календаря.

Возник вопрос, или что-то на этой странице не совпадает с кодом? Свяжитесь с нами — и напишите, о каком эндпоинте речь.