# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **Справочник API**

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

***

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

Все запросы к API следует направлять на следующий базовый URL:\ <mark style="color:синий;"><https://rest.boxhero-app.com></mark>

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

Все запросы к API должны включать <mark style="color:синий;">**заголовок Authorization**</mark> с <mark style="color:синий;">**токеном Bearer**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

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

1. Войдите в свою учетную запись BoxHero на Desktop (Web).
2. Перейдите в <mark style="color:синий;">**`Настройки`**</mark> > <mark style="color:синий;">**`Интеграции`**</mark>.
3. Сгенерируйте новый токен API.

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

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

```bash
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: ошибка на стороне сервера.

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

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

* **id :** Уникальный идентификатор для определения ошибки.
* **type :** Код в виде URL, который определяет тип ошибки.
* **title :** Представляет содержимое ошибки в удобочитаемом виде.
* **correlation\_id :** Указывает на идентификатор запроса, связанного с ошибкой.
* **others :** Могут быть включены дополнительные поля для предоставления дополнительной информации, такой как "*given*" в примере.

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

<table><thead><tr><th width="252">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Запрошенный ресурс не найден (например, товар с указанным идентификатором не существует).</td></tr><tr><td>/errors/invalid-request</td><td>Недопустимые параметры в запросе.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Запрошенный запрос не может быть обработан в текущем режиме команды (например, использование API поиска <em>location</em> в <em>Базовом режиме</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Отсутствует токен API.</td></tr><tr><td>/errors/tokens/invalid</td><td>Недействительный токен API (например, срок действия токена API истёк).</td></tr><tr><td>/errors/too-many-requests</td><td>Превышен лимит запросов.</td></tr><tr><td>/errors/unhandled</td><td>Непредвиденная ошибка на стороне сервера.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Достигнут лимит использования. Требуется обновление тарифа.</td></tr></tbody></table>

## Пагинация

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

{% hint style="info" %}
Чтобы определить, требуется ли пагинация, проверьте, присутствуют ли в теле запроса конечной точки параметры, связанные с пагинацией, в документации API.
{% endhint %}

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

* `has_more` : Булево значение, указывающее, существуют ли данные за пределами текущей страницы.
* `cursor` : Предоставляет значение курсора для получения следующей страницы.

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

* Проверьте, `has_more` является ли `true`. Это означает, что доступна ещё одна страница.
* Если `true`, отправьте ещё один запрос, включая `cursor={received cursor value}` в параметрах. Это вернёт последующие данные.
* Повторяйте, пока `has_more` является ли `false` не будет достигнуто, чтобы получить полный список.

***

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

Если вы столкнётесь с проблемами или вам потребуется дополнительная функциональность API, пожалуйста, свяжитесь с нашей [службой поддержки](https://docs-en.boxhero.io/etc/contact). Мы будем рады вашим отзывам по улучшениям API и запросам на новые функции.