# API

<figure><img src="/files/9a0d374ce0aaa4c899c14a8c5614e93e894202e7" alt=""><figcaption></figcaption></figure>

***

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

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

***

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

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

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

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

```
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 :** Указывает на идентификатор запроса, связанного с ошибкой.
* **прочее :** Могут быть включены дополнительные поля для предоставления дополнительной информации, такой как "*given*" в примере.

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

<table><thead><tr><th width="252">Тип</th><th>Описание</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Запрошенный ресурс не найден (например, товар с указанным ID не существует).</td></tr><tr><td>/errors/invalid-request</td><td>Неверные параметры в запросе.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Запрошенный запрос не может быть обработан в текущем режиме команды (например, использование API поиска по <em>location</em> местоположению в <em>Basic Mode</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 и запросам на новые функции.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/documentation/ru/integracii/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.