Работа с API

Integration API — это поверхность, через которую ваша интеграция читает и изменяет данные клиента. Один базовый URL, один формат ответа и 464 эндпоинта.

Среда	Базовый URL
Продакшн	https://api.bito.uz/integration-api/integration/api/v2/
Дев	https://api.systematicdev.uz/integration-api/integration/api/v2/

Полный список методов со схемами запроса и ответа — в справочнике API.

Два способа авторизации

Оба ведут к одним и тем же эндпоинтам и данным. Выбор зависит от того, скольким клиентам вы служите.

	API-ключ	OAuth 2.0
Заголовок	api-key: <username>:<secret>	Authorization: Bearer <access_token>
Для скольких аккаунтов	Один — ваш	Много
Срок действия	Бессрочно	Access 24 ч, refresh 90 дней
Настройка	Скопировать из интеграции	Клиент устанавливает и подтверждает
Когда использовать	Свой бэкофис, скрипты, интеграция для одного клиента	Интеграции для маркетплейса

API-ключ

Отправляйте api_key в заголовке api-key. Ни обмена токенами, ни срока действия.

POST https://api.bito.uz/integration-api/integration/api/v2/product/get-paging
api-key: mycompany:9ad41c0e7b3f28d5610ac94e7f1b26d8
Content-Type: application/json

{ "page": 1, "limit": 20 }

OAuth 2.0

Каждая установка даёт свою пару токенов, и токен несёт контекст аккаунта — поэтому запрос автоматически ограничен данными нужного клиента, и идентификатор аккаунта передавать не нужно.

POST https://api.bito.uz/integration-api/integration/api/v2/product/get-paging
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{ "page": 1, "limit": 20 }

Как получить токен — в разделе OAuth 2.0: обзор.

Что нужно знать заранее

HTTP-методы

Метод — часть контракта каждого эндпоинта:

Метод	Для чего	Пример
POST	Создание записи и любой запрос списка или фильтрации	POST /product/create, POST /product/get-paging
PUT	Изменение записи или смена её статуса	PUT /product/update, PUT /production-operation/set-state
GET	Чтение одной записи по id и запросы без тела	GET /product/get-by-id/{id}, GET /product/get-deleted
DELETE	Удаление записи	DELETE /product/delete/{id}

Списки идут через POST, потому что фильтры передаются телом JSON, а не строкой запроса. Метод каждого эндпоинта указан на его странице в справочнике API.

WARNING

Админский API Bito — тот, с которым работает веб-панель, — принимает только POST. Integration API устроен иначе, не переносите это допущение.

Заголовки запроса

Заголовок	Обязателен	Описание
api-key или Authorization	Да	Один из двух способов авторизации выше
Content-Type	Да	application/json
Accept-Language	Нет	uz, uz_cyrillic, ru, en, kk, tg, ky. По умолчанию uz. Задаёт язык поля message.
organization_id	Нет	Организация внутри аккаунта. Используется, только если в настройках интеграции (fields) есть поле organization_id, — иначе заголовок игнорируется. Если заголовок не передан, берётся значение этого поля.
warehouse_id	Нет	Склад. Используется, только если в настройках интеграции (fields) есть поле warehouse_id, — иначе заголовок игнорируется. Если заголовок не передан, берётся значение этого поля.
price_id	Нет	Прайс-лист для цен. Используется, только если в настройках интеграции (fields) есть поле price_id, — иначе заголовок игнорируется. Если заголовок не передан, берётся значение этого поля.
role_id	Нет	Роль, от которой выполняется запрос. Используется, только если в настройках интеграции (fields) есть поле role_id, — иначе заголовок игнорируется. Если заголовок не передан, берётся значение этого поля.
user_id	Нет	Выполнить запрос от имени этого пользователя. Пользователь должен принадлежать этому аккаунту и не быть заблокирован, иначе запрос отклоняется. Если не передан — от имени владельца аккаунта.

Формат ответа

Любой ответ, успешный или нет, имеет одну и ту же структуру.

{
    "code": 0,
    "message": "Success",
    "status_code": 200,
    "messages": { "uz": "Muvaffaqiyatli", "ru": "Успешно", "en": "Successful" },
    "data": { },
    "time": "2025-05-01T12:00:00Z"
}

Поле	Значение
code	0 при успехе, иначе код ошибки. Ветвитесь по нему.
message	Текст на языке из Accept-Language. Не разбирайте его.
messages	Тот же текст на uz, ru и en.
status_code	HTTP-статус.
data	Полезная нагрузка. При ошибке отсутствует.
time	Время сервера, ISO 8601.

Постраничная выборка

Каждый эндпоинт get-paging принимает page и limit и возвращает общее количество рядом с записями.

Запрос

{ "page": 1, "limit": 50 }

Поле	Тип	По умолчанию	Ограничения
page	number	1	≥ 1
limit	number	20	от 1 до 200

Ответ

{
    "code": 0,
    "message": "Success",
    "status_code": 200,
    "data": {
        "total": 1043,
        "data": [ { "_id": "6712f0a9c4d1e87b3a0f9911", "name": "Эспрессо" } ]
    },
    "time": "2025-05-01T12:00:00Z"
}

Обратите внимание на вложенность: записи лежат в data.data, количество — в data.total. Листайте, пока page * limit >= total.

TIP

Большинство get-paging принимают фильтры рядом с page/limit — в частности updated_at позволяет забрать только то, что изменилось с прошлой синхронизации. Смотрите нужный метод в справочнике API.

Удаление всегда мягкое

Bito не удаляет записи физически: вызов delete помечает запись удалённой. Для вас это значит две вещи — у большинства ресурсов есть эндпоинт get-deleted, а сохранённый id может вернуться как удалённый, а не исчезнуть.

Идентификаторы

Любой _id — это 24-символьный MongoDB ObjectId, например 6712f0a9c4d1e87b3a0f9911. Считайте его непрозрачной строкой.

Ошибки

Ответ с ошибкой содержит ненулевой code и не содержит data.

{
    "code": 401,
    "message": "Unauthorized user",
    "status_code": 401,
    "messages": { "uz": "...", "ru": "...", "en": "Unauthorized user" },
    "time": "2025-05-01T12:00:00Z"
}

HTTP	Что произошло	Что делать
400	Не прошла валидация или указанной записи нет	Прочитайте message, исправьте тело запроса
401	Ключ отсутствует, некорректен или истёк	Проверьте заголовок, обновите токен
403	У интеграции нет прав на это действие	В сообщении указан нужный ключ права; добавьте его в required_permissions
404	Такого эндпоинта нет	Сверьте путь со справочником API
429	Слишком много запросов	Снизьте частоту и повторите
500	Сбой на стороне Bito	Повторите с задержкой; если повторяется — напишите в поддержку

WARNING

Не повторяйте 400 без изменений и не повторяйте запись вслепую: большинство методов записи не идемпотентны, поэтому повторный create создаст вторую запись.

Дальше

• Пользовательские виджеты — своё приложение внутри админ-панели Bito
• Вебхуки данных — узнавать об изменениях без опроса
• Справочник API — все 464 метода