API

API BoxHero позволяет разработчикам интегрировать наши возможности управления запасами со сторонними приложениями для эффективного получения данных и взаимодействия с ними.

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

Справочник API

Для подробной документации по конечным точкам, пожалуйста, посетите: https://rest.boxhero-app.com/docs/api

---

Конечная точка

Все запросы API должны направляться на следующий базовый URL: https://rest.boxhero-app.com

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

Все запросы API должны включать Authorization заголовок с токеном Bearer:

Authorization: Bearer {API_TOKEN}

Чтобы получить API-токен:

1. Войдите в свою учетную запись BoxHero на Desktop (Web).

2. Перейдите к Настройки > Интеграции.

3. Сгенерируйте новый API-токен.

Выполнение запросов

Вот пример запроса API для получения товаров.

curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'

Ограничения частоты запросов

Чтобы обеспечить стабильность системы, мы вводим следующие ограничения частоты запросов:

• 5 запросов в секунду для каждой конечной точки.

Если вы достигнете лимита запросов, вы увидите сообщение об ошибке со следующим:

• X-Ratelimit-Limit - Максимальное количество запросов в минуту

• X-Ratelimit-Remaining - Осталось запросов

• X-Ratelimit-Reset - Время (в секундах), оставшееся до сброса счетчика запросов

---

Ответы

Успех

Ответы со статус-кодами HTTP в диапазоне 200 указывают на успешную обработку API.

Ошибка

Статус-коды в диапазоне 400 или 500 указывают на сбой запроса API:

• Диапазон 400: ошибка на стороне клиента из-за информации, предоставленной с запросом (например, отсутствуют обязательные параметры).

• Диапазон 500: ошибка на стороне сервера.

Пример ответа с ошибкой:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Токен аутентификации недействителен. Пожалуйста, предоставьте действительный токен.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}

• id : Уникальный идентификатор для определения ошибки.

• type : Код в виде URL, который идентифицирует тип ошибки.

• title : Предоставляет содержание ошибки в удобочитаемом виде.

• correlation_id : Указывает на ID запроса, связанного с ошибкой.

• others : Могут быть включены дополнительные поля для предоставления дополнительной информации, такой как "given" в примере.

Распространенные типы ошибок

Тип	Описание
/errors/not-found	Запрошенный ресурс не найден (например, товар с определенным ID не существует).
/errors/invalid-request	Недопустимые параметры в запросе.
/errors/invalid-team-mode	Запрошенный запрос не может быть обработан в текущем режиме команды (например, использование локации API поиска в Базовом режиме).
/errors/tokens/required	Отсутствует API-токен.
/errors/tokens/invalid	Недействительный API-токен (например, срок действия API-токена истек).
/errors/too-many-requests	Превышен лимит запросов.
/errors/unhandled	Необработанная ошибка на стороне сервера.
/errors/core/usage-limit-exceeded	Достигнут лимит использования. Требуется обновление плана.

Пагинация

Для конечных точек, возвращающих большие наборы данных (например, списки товаров, списки транзакций), API представления списка ограничивает количество элементов, возвращаемых в одном запросе, с помощью пагинации. Мы используем пагинацию на основе курсора:

Чтобы определить, требуется ли пагинация, проверьте, присутствуют ли в теле запроса конечной точки параметры, связанные с пагинацией, в документации API.

Параметры пагинации

• has_more : Булево значение, которое указывает, есть ли данные за пределами текущей страницы.

• cursor : Предоставляет значение курсора для получения следующей страницы.

Получение следующей страницы

• Проверьте, has_more является ли true. Это означает, что доступна еще одна страница.

• Если true, отправьте еще один запрос, включив cursor={received cursor value} в параметры. Это вернет последующие данные.

• Повторяйте, пока has_more является ли false не будет достигнуто, чтобы получить полный список.

---

Поддержка и обратная связь

Если вы столкнетесь с проблемами или вам потребуется дополнительная функциональность API, пожалуйста, свяжитесь с нашей службой поддержки. Мы будем рады вашим отзывам по улучшению API и запросам на новые функции.