# Экспорт отчётов в Excel

> Как получить готовый файл отчёта одним запросом и какие колонки доступны в каждом отчёте.

Методы раздела «Экспорт отчётов» отдают ссылку на готовый файл `.xlsx` — тот же отчёт, что и на страницах отчётов в BILLZ, и те же данные, что у [отчётов](/reference/api/) с постраничным чтением. Разница в нагрузке: вместо десятков страниц `GET` — один `POST` и ссылка на файл.

Все методы принимают `POST` с телом JSON и отвечают одинаково.

## Как получить файл

Файл готовится не мгновенно — сборка идёт в фоне. Есть два режима.

### Дождаться файла в ответе

Передайте заголовок:

```plaintext
Billz-Response-Channel: HTTP
```

Запрос будет ждать готовности файла — до 100 секунд — и вернёт ответ со ссылкой. Для интеграции это единственный режим, в котором ссылку на файл вообще можно получить.

```bash
curl -X POST 'https://api-admin.billz.ai/v1/stock-report-excel' \
  -H 'Authorization: Bearer ТОКЕН' \
  -H 'Billz-Response-Channel: HTTP' \
  -H 'Content-Type: application/json' \
  -d '{
    "shop_ids": ["6f244db4-75d6-4fac-9841-14867d45e36a"],
    "report_date": "2026-08-31",
    "currency": "UZS",
    "fields": ["product_name", "measurement_value", "supply_price", "retail_price"]
  }'
```

### Не ждать

Без заголовка метод отвечает сразу:

```json
{ "message": "7c1e2f3a-9b21-4e2a-8c31-3f4a2b1c9d0e" }
```

Это `correlation_id` запроса.

> **Без заголовка файл через API не получить**
>
> В этом режиме ссылка на файл не возвращается **никогда**: готовый файл уходит уведомлением в интерфейс BILLZ, а метода «забрать файл по `correlation_id`» в API нет. Для интеграции `Billz-Response-Channel: HTTP` обязателен.

## Ответ

```json
{
  "status_code": 200,
  "data": {
    "filename": "Отчет по остаткам за 2026-08-31_7c1e2f3a-9b21-4e2a-8c31-3f4a2b1c9d0e",
    "url": "https://minio.billz.ai/report-excel/Отчет по остаткам за 2026-08-31_7c1e2f3a-9b21-4e2a-8c31-3f4a2b1c9d0e"
  }
}
```

Имя файла собирается по шаблону `<Название отчёта> за <период>_<уникальный id>`; шаблон каждого отчёта указан ниже, в его разделе. Сервис формирует имя **по-русски** независимо от `lang` и языка интеграции — в переводах этой страницы шаблоны приведены по смыслу, а придёт русское имя.

> **В ссылке нет расширения**
>
> Ссылка оканчивается идентификатором, а не на `.xlsx`. Содержимое при этом — обычный `.xlsx`: при сохранении расширение добавляется вручную.

Ошибки — в [общем формате](/reference/errors/). Если файл не успел собраться за 100 секунд, запрос завершится `408` с `error.code = TIMEOUT`, а сборка продолжится. Ожидание в 100 секунд — только у экспорта отчётов; у остальных асинхронных методов оно длиннее.

> **Ограничитель частоты: 5 запросов в секунду**
>
> На десяти методах раздела стоит собственный ограничитель — **5 запросов в секунду** (всплеск 10), общий для всех клиентов платформы: `general-report-excel`, `product-general-report-excel`, `seller-general-report-excel`, `customer-general-report-excel`, `customer-purchases-report-excel`, `sells-supplier-report-excel`, `transaction-report-excel`, `import-report-excel`, `stock-report-excel`, `transfer-report-excel-export`. При превышении — `429`, разбор в [кодах ответов](/reference/errors/). У остальных шести методов раздела собственного ограничителя нет.

## Колонки: параметр `fields`

`fields` — список колонок, которые попадут в файл, в том порядке, в каком они перечислены. Допустимые значения — в таблице «Колонки» каждого отчёта.

> **Без `fields` файл будет пустым**
>
> Метод вернёт файл, но без колонок с данными.

### Колонки по атрибутам и кастомным полям товара

В отчётах по товарам вместо названия колонки в `fields` можно передать **UUID атрибута или кастомного поля** товара, настроенного в каталоге компании («Размер», «Цвет»):

```json
{
  "fields": ["product_name", "measurement_value", "9f1c2e3a-5b7d-4c1e-8a2f-3d6b0e4c7a91"]
}
```

Колонка получит название атрибута из каталога, а в строках будут его значения у каждого товара. Нет значения у товара — ячейка пустая. Отчёты, где это работает, отмечены ниже.

## Реестр отчётов

| Раздел     | Отчёт                       | Метод                                                                                                                          |
| ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Магазин    | Сводный отчёт по магазину   | [`POST /v1/general-report-excel`](/reference/api/operations/post_v1_general_report_excel/)                                     |
| Транзакции | Транзакции                  | [`POST /v1/transaction-report-excel`](/reference/api/operations/post_v1_transaction_report_excel/)                             |
| Продавцы   | Сводка по продавцам         | [`POST /v1/seller-general-report-excel`](/reference/api/operations/post_v1_seller_general_report_excel/)                       |
| Клиенты    | Сводка по клиентам          | [`POST /v1/customer-general-report-excel`](/reference/api/operations/post_v1_customer_general_report_excel/)                   |
| Клиенты    | Покупки клиентов            | [`POST /v1/customer-purchases-report-excel`](/reference/api/operations/post_v1_customer_purchases_report_excel/)               |
| Финансы    | Прибыли и убытки            | [`POST /v1/report-profit-and-lose-excel`](/reference/api/operations/post_v1_report_profit_and_lose_excel/)                     |
| Финансы    | Финансовые транзакции (ДДС) | [`POST /v1/cashflow-excel`](/reference/api/operations/post_v1_cashflow_excel/)                                                 |
| Товары     | Продажи по товарам          | [`POST /v1/product-general-report-excel`](/reference/api/operations/post_v1_product_general_report_excel/)                     |
| Товары     | Эффективность товаров       | [`POST /v1/report-product-performance-excel`](/reference/api/operations/post_v1_report_product_performance_excel/)             |
| Товары     | Импорты                     | [`POST /v1/import-report-excel`](/reference/api/operations/post_v1_import_report_excel/)                                       |
| Товары     | Продажи по поставщикам      | [`POST /v1/sells-supplier-report-excel`](/reference/api/operations/post_v1_sells_supplier_report_excel/)                       |
| Товары     | Возвраты заказов            | [`POST /v1/supplier-order-returned-export`](/reference/api/operations/post_v1_supplier_order_returned_export/)                 |
| Товары     | Результаты инвентаризации   | [`POST /v1/stocktaking-summary-table-excel-export`](/reference/api/operations/post_v1_stocktaking_summary_table_excel_export/) |
| Товары     | Остатки по товарам          | [`POST /v1/stock-report-excel`](/reference/api/operations/post_v1_stock_report_excel/)                                         |
| Товары     | Списания                    | [`POST /v1/write-off-report-table-export`](/reference/api/operations/post_v1_write_off_report_table_export/)                   |
| Товары     | Перемещения                 | [`POST /v1/transfer-report-excel-export`](/reference/api/operations/post_v1_transfer_report_excel_export/)                     |

## Магазин

### Сводный отчёт по магазину

[`POST /v1/general-report-excel`](/reference/api/operations/post_v1_general_report_excel/) · файл `Сводный отчет за <start_date> - <end_date>_<id>`

Выручка, прибыль, средний чек и количество транзакций за период.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "detalization": "day",
  "fields": ["date", "shop_name", "gross_sales", "net_gross_sales", "average_cheque"]
}
```

Колонки:

| Значение `fields`           | Колонка в файле                   |
| --------------------------- | --------------------------------- |
| `date`                      | Дата                              |
| `shop_name`                 | Магазин                           |
| `gross_sales`               | Выручка                           |
| `discount_sum`              | Сумма скидки                      |
| `discount_percent`          | Процент скидки                    |
| `products_returned`         | Количество возвращённых товаров   |
| `returned_supply_price`     | Возвраты по цене закупки          |
| `returned_discount_price`   | Возвраты по цене со скидкой       |
| `returned_retail_price`     | Возвраты по цене продажи          |
| `sales_supply_price`        | Продажи по цене закупки           |
| `net_gross_sales`           | Чистая выручка                    |
| `gross_profit`              | Валовая прибыль                   |
| `average_cheque`            | Средний чек                       |
| `average_price`             | Средняя цена товара в чеке        |
| `average_measurement_value` | Среднее количество товаров в чеке |
| `average_extra_charge`      | Средняя наценка                   |
| `products_sold`             | Количество проданных товаров      |
| `transactions_count`        | Общее количество транзакций       |
| `orders_count`              | Количество транзакций продаж      |
| `returns_count`             | Количество транзакций возвратов   |
| `exchanges_count`           | Количество транзакций обменов     |
| `sales_per_square`          | Продажи на квадратный метр        |

## Транзакции

### Транзакции

[`POST /v1/transaction-report-excel`](/reference/api/operations/post_v1_transaction_report_excel/) · файл `Отчет по транзакциям за <start_date> - <end_date>_<id>`

Продажи, возвраты и обмены за период — строка на транзакцию.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "order_types": ["SALE"],
  "fields": ["date", "order_type", "total_price", "seller_names"]
}
```

Колонки:

| Значение `fields`            | Колонка в файле                         |
| ---------------------------- | --------------------------------------- |
| `date`                       | Дата                                    |
| `external_id`                | ID транзакции                           |
| `shop_name`                  | Магазин                                 |
| `customer_name`              | ФИО клиента                             |
| `cashier_name`               | ФИО кассира                             |
| `seller_names`               | ФИО продавца                            |
| `order_type`                 | Тип транзакции                          |
| `sold_measurement_value`     | Количество проданных товаров и услуг    |
| `returned_measurement_value` | Количество возвращённых товаров         |
| `total_price`                | Сумма транзакции                        |
| `discount_percent`           | Скидка                                  |
| `average_product_price`      | Средняя цена за товар или услугу в чеке |
| `gross_sales`                | Сумма оплаты без скидки                 |
| `comment`                    | Комментарий к транзакции                |
| `is_modified`                | История редактирования                  |

## Продавцы

### Сводка по продавцам

[`POST /v1/seller-general-report-excel`](/reference/api/operations/post_v1_seller_general_report_excel/) · файл `Отчет по продавцам за <start_date> - <end_date>_<id>`

Продажи в разрезе продавцов компании.

> **Отбор по продавцам недоступен**
>
> Отчёт всегда строится по всем продавцам компании. Сузить его можно только магазинами (`shop_ids`) и флагом `hide_sellers_without_sales`.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "price_type": 1,
  "hide_sellers_without_sales": true,
  "detalization": "day",
  "fields": ["date", "seller_name", "gross_sales", "net_gross_profit", "transaction_count"]
}
```

Колонки:

| Значение `fields`            | Колонка в файле                         |
| ---------------------------- | --------------------------------------- |
| `date`                       | Дата                                    |
| `shop_name`                  | Магазин                                 |
| `seller_name`                | Продавец                                |
| `gross_sales`                | Выручка                                 |
| `discount_sum`               | Сумма скидки                            |
| `discount_percent`           | Процент скидки                          |
| `net_gross_sales`            | Чистая выручка                          |
| `net_gross_profit`           | Валовая прибыль                         |
| `sum_returned`               | Сумма возвратов                         |
| `sold_measurement_value`     | Количество проданных товаров            |
| `returned_measurement_value` | Количество возвращённых товаров         |
| `sold_without_return`        | Количество проданных с учётом возвратов |
| `transaction_count`          | Количество транзакций                   |
| `orders_count`               | Количество транзакций продаж            |
| `average_cheque`             | Средний чек                             |
| `average_measurement_value`  | Среднее количество товаров              |
| `average_price`              | Средняя цена товара                     |
| `net_sold_supply_sum`        | Продажи по цене поставки                |
| `rounding_amount`            | Сумма округления                        |

## Клиенты

### Сводка по клиентам

[`POST /v1/customer-general-report-excel`](/reference/api/operations/post_v1_customer_general_report_excel/) · файл `Отчет по клиентам за <start_date> - <end_date>_<id>`

Покупки, возвраты и средний чек по каждому клиенту — за всё время и за выбранный период.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "price_type": 1,
  "fields": ["customer_name", "customer_phones", "total_purchase_sum", "total_sale_count"]
}
```

Колонки:

| Значение `fields`                   | Колонка в файле                             |
| ----------------------------------- | ------------------------------------------- |
| `registration_date`                 | Дата регистрации                            |
| `registration_shop_name`            | Магазин регистрации                         |
| `customer_name`                     | ФИО клиента                                 |
| `birth_date`                        | Дата рождения                               |
| `customer_id`                       | ID клиента                                  |
| `customer_phones`                   | Телефон                                     |
| `customer_groups`                   | Группы и теги                               |
| `is_new_client`                     | Новый клиент                                |
| `is_returned_client`                | Возвращающийся клиент                       |
| `total_sale_count`                  | Продажи (всего)                             |
| `total_exchange_count`              | Обмены (всего)                              |
| `total_return_count`                | Возвраты (всего)                            |
| `total_measurement_value`           | Количество купленных товаров (всего)        |
| `total_purchase_sum`                | Общая сумма покупок (всего)                 |
| `total_average_measurement_value`   | Среднее количество товаров в чеке (всего)   |
| `total_average_purchase_sum`        | Средний чек (всего)                         |
| `total_average_purchase_discount`   | Средняя скидка (всего)                      |
| `total_returned_measurement_value`  | Количество возвращённых товаров (всего)     |
| `total_returned_sum`                | Сумма возвращённых товаров (всего)          |
| `period_sale_count`                 | Продажи за период                           |
| `period_exchange_count`             | Обмены за период                            |
| `period_return_count`               | Возвраты за период                          |
| `period_measurement_value`          | Количество купленных товаров за период      |
| `period_purchase_sum`               | Общая сумма покупок за период               |
| `period_average_measurement_value`  | Среднее количество товаров в чеке за период |
| `period_average_purchase_sum`       | Средний чек за период                       |
| `period_average_purchase_discount`  | Средняя скидка за период                    |
| `period_returned_measurement_value` | Количество возвращённых товаров за период   |
| `period_returned_sum`               | Сумма возвращённых товаров за период        |

### Покупки клиентов

[`POST /v1/customer-purchases-report-excel`](/reference/api/operations/post_v1_customer_purchases_report_excel/) · файл `Отчет по покупкам клиентов за <start_date> - <end_date>_<id>`

Построчный список покупок: что, кто и когда купил.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "with_customers": true,
  "currency": "UZS",
  "fields": ["created_at", "customer_name", "product_name", "gross_sales"]
}
```

Колонки:

| Значение `fields`            | Колонка в файле                 |
| ---------------------------- | ------------------------------- |
| `created_at`                 | Дата покупки                    |
| `shop_name`                  | Магазин                         |
| `order_type`                 | Тип транзакции                  |
| `order_number`               | ID транзакции                   |
| `seller_name`                | Продавец                        |
| `customer_number`            | ID клиента                      |
| `customer_name`              | ФИО клиента                     |
| `phone_numbers`              | Телефон                         |
| `tags`                       | Тег                             |
| `groups`                     | Группа                          |
| `product_name`               | Наименование                    |
| `product_brand_name`         | Бренд                           |
| `product_barcode`            | Штрихкод                        |
| `product_sku`                | Артикул                         |
| `categories_path`            | Категория                       |
| `level_1` … `level_5`        | Категория и подкатегории 1–4    |
| `free_price`                 | Свободная цена                  |
| `used_wholesale_price`       | Оптовая цена                    |
| `gross_sales`                | Выручка                         |
| `net_sales`                  | Чистая выручка                  |
| `net_sold_supply_sum`        | Продажи по себестоимости        |
| `net_profit`                 | Валовая прибыль                 |
| `discount_percent`           | Средняя скидка                  |
| `sold_measurement_value`     | Количество проданных товаров    |
| `returned_measurement_value` | Количество возвращённых товаров |

## Финансы

### Прибыли и убытки

[`POST /v1/report-profit-and-lose-excel`](/reference/api/operations/post_v1_report_profit_and_lose_excel/) · файл `Отчет прибыли и убытки за <start_date> - <end_date>_<id>`

Доходы, расходы и чистая прибыль компании за период.

> **У отчёта нет `fields`**
>
> Набор строк фиксированный: доходы по категориям, «Выручка», «Скидки», «Возвраты», «Чистая выручка», «Сумма округления», «ИТОГО ДОХОДОВ», расходы по категориям, «СЕБЕСТОИМОСТЬ ТОВАРОВ», «МАРЖИНАЛЬНАЯ ПРИБЫЛЬ», «РЕНТАБЕЛЬНОСТЬ МАРЖИНАЛЬНОЙ ПРИБЫЛИ», «Списание по себестоимости», «ИТОГО РАСХОДОВ», «ЧИСТАЯ ПРИБЫЛЬ».
>
> Подписи строк приходят заполненными только при `lang: "ru"`; с другими значениями они будут пустыми.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "detalization": "day",
  "price_type": 1,
  "lang": "ru"
}
```

### Финансовые транзакции (ДДС)

[`POST /v1/cashflow-excel`](/reference/api/operations/post_v1_cashflow_excel/) · файл `ДДС за <start_date> - <end_date>_<id>`

Движение денежных средств: приходы, расходы, инкассации, конвертации.

Типы операций для `operation` перечисляются через запятую, например `1,2`:

| Значение | Операция                                                                                                               |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `1`      | Доход                                                                                                                  |
| `2`      | Расход                                                                                                                 |
| `3`      | Закрытие смены — движение денег, которое система создаёт сама при закрытии смены кассы для безналичных способов оплаты |
| `4`      | Перемещение — ручной перевод денег между кассами и счетами, который инициирует пользователь                            |
| `5`      | Конвертация                                                                                                            |
| `6`      | Инкассация                                                                                                             |
| `7`      | Сумма открытия                                                                                                         |

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "operation": "1,2",
  "fields": ["created_at", "cashbox", "operation", "amount_from_retail_currency", "user"]
}
```

Колонки:

| Значение `fields`             | Колонка в файле              |
| ----------------------------- | ---------------------------- |
| `created_at`                  | Дата и время                 |
| `cashbox`                     | Касса                        |
| `payment_type`                | Тип денежной операции        |
| `operation`                   | Тип транзакции               |
| `from_account`                | Откуда                       |
| `to_account`                  | Куда                         |
| `amount_from_retail_currency` | Сумма ИЗ (в валюте компании) |
| `amount_to_retail_currency`   | Сумма В (в валюте компании)  |
| `amount_from_usd`             | Сумма ИЗ (USD)               |
| `amount_to_usd`               | Сумма В (USD)                |
| `user`                        | Пользователь                 |

## Товары

### Продажи по товарам

[`POST /v1/product-general-report-excel`](/reference/api/operations/post_v1_product_general_report_excel/) · файл `Отчет по продажам за <start_date> - <end_date>_<id>`

Статистика продаж в разрезе товаров. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "detalization": "day",
  "fields": ["product_name", "sold_measurement_value", "gross_sales", "net_profit"]
}
```

Колонки:

| Значение `fields`                     | Колонка в файле                       |
| ------------------------------------- | ------------------------------------- |
| `date`                                | Дата                                  |
| `product_name`                        | Наименование                          |
| `product_sku`                         | Артикул                               |
| `product_barcode`                     | Баркод                                |
| `product_brand_name`                  | Бренд                                 |
| `shop_name`                           | Название магазина                     |
| `categories_path`                     | Категория                             |
| `level_1` … `level_5`                 | Категория и подкатегории 1–4          |
| `product_measurement_unit_short_name` | Единица измерения                     |
| `product_suppliers`                   | Поставщик                             |
| `sold_measurement_value`              | Количество проданных                  |
| `returned_measurement_value`          | Количество возвращённых               |
| `net_sold_measurement_value`          | Продано за вычетом возвратов          |
| `gross_sales`                         | Продажи без учёта скидки              |
| `returned_sales_sum`                  | Сумма возвратов                       |
| `net_sales`                           | Продажи со скидкой с учётом возвратов |
| `net_profit`                          | Валовая прибыль                       |
| `sold_supply_sum`                     | Продажи по цене закупки               |
| `average_margin`                      | Средняя наценка                       |
| `discount`                            | Скидка                                |
| `sold_with_discount`                  | Продано со скидкой                    |
| `sold_without_discount`               | Продано без скидки                    |
| `product_is_archived`                 | Архивирован                           |

### Эффективность товаров

[`POST /v1/report-product-performance-excel`](/reference/api/operations/post_v1_report_product_performance_excel/) · файл `Отчет Эффективность Товаров за <start_date> - <end_date>_<id>`

Все движения по каждому товару за период: остатки на начало и конец, импорт, продажи, списания, перемещения, скорость продажи и оборачиваемость. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "grouping_fields": "attribute.color",
  "group_id": "9f1c2e3a-5b7d-4c1e-8a2f-3d6b0e4c7a91",
  "filter": { "skus": ["SKU-001"] },
  "order_by": "+product_name",
  "currency": "UZS",
  "fields": ["name", "sold_amount", "sold_retail_sum"]
}
```

Колонки о товаре:

| Значение `fields`     | Колонка в файле              |
| --------------------- | ---------------------------- |
| `shop_name`           | Магазин                      |
| `supplier_name`       | Поставщик                    |
| `name`                | Наименование                 |
| `sku`                 | Артикул                      |
| `bar_code`            | Баркод                       |
| `is_archived`         | Архивирован                  |
| `brand_name`          | Бренд                        |
| `categories_path`     | Категория                    |
| `level_1` … `level_5` | Категория и подкатегории 1–4 |

Колонки-показатели, каждая группа — за выбранный период:

| Группа                         | Значения `fields`                                                                                      | Что в колонках                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Остаток на начало периода      | `stock_amount_begin`, `stock_supply_sum_begin`, `stock_retail_sum_begin`                               | количество, сумма по цене поставки, сумма продажи                                             |
| Импорт товара                  | `import_amount`, `import_supply_sum`, `import_retail_sum`                                              | количество, сумма по цене поставки, сумма продажи                                             |
| Заказы товара                  | `order_amount`, `order_supply_sum`, `order_retail_sum`                                                 | количество, сумма по цене поставки, сумма продажи                                             |
| Возврат заказа                 | `supplier_order_return_amount`, `supplier_order_return_supply_sum`, `supplier_order_return_retail_sum` | количество, сумма по цене поставки, сумма продажи                                             |
| Входящее перемещение           | `inc_transfer_amount`, `inc_transfer_supply_sum`, `inc_transfer_retail_sum`                            | количество, сумма по цене поставки, сумма продажи                                             |
| Возвраты товаров               | `returned_amount`, `returned_supply_sum`, `returned_retail_sum`, `returned_sales_sum`                  | количество, сумма по цене поставки, сумма продажи, сумма по цене со скидкой                   |
| Продажи товаров                | `sold_amount`, `sold_supply_sum`, `sold_retail_sum`, `sold_sales_sum`, `rounding_amount`               | количество, сумма по цене поставки, сумма продажи, сумма по цене со скидкой, сумма округления |
| Списания товаров               | `write_off_amount`, `write_off_supply_sum`, `write_off_retail_sum`                                     | количество, сумма по цене поставки, сумма продажи                                             |
| Исходящее перемещение          | `out_transfer_amount`, `out_transfer_supply_sum`, `out_transfer_retail_sum`                            | количество, сумма по цене поставки, сумма продажи                                             |
| Переоценка                     | `repricing_amount`, `repricing_supply_sum`, `repricing_retail_sum`                                     | количество, сумма по цене поставки, сумма продажи                                             |
| Остаток на конец периода       | `stock_amount_end`, `stock_supply_sum_end`, `stock_retail_sum_end`                                     | количество, сумма по цене поставки, сумма продажи                                             |
| Скорость продажи               | `qty_sellout`, `sum_sellout`                                                                           | по количеству, по сумме продажи                                                               |
| Оборачиваемость остатка в днях | `day_difference`, `sellout_in_number`, `sellout_by_days`                                               | количество дней, скорость продажи, оборачиваемость                                            |

### Импорты

[`POST /v1/import-report-excel`](/reference/api/operations/post_v1_import_report_excel/) · файл `Отчет по импортам за <start_date> - <end_date>_<id>`

Что завезли по импортам и заказам поставщикам и что с этим дальше произошло: продажи, списания, перемещения, остаток. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "import_type": "supplier_order",
  "fields": ["date", "shop_name", "imported_qty", "sold_qty"]
}
```

Колонки:

| Значение `fields`                  | Колонка в файле                                 |
| ---------------------------------- | ----------------------------------------------- |
| `date`                             | Дата импорта                                    |
| `external_import_id`               | ID импорта                                      |
| `external_supplier_order_id`       | ID заказа                                       |
| `supplier_name`                    | Поставщик                                       |
| `import_type`                      | Тип импорта                                     |
| `shop_name`                        | Магазин                                         |
| `product_name`                     | Наименование                                    |
| `product_brand_name`               | Бренд                                           |
| `product_barcode`                  | Штрихкод                                        |
| `product_sku`                      | Артикул                                         |
| `is_archived`                      | Архивирован                                     |
| `categories_path`                  | Категория                                       |
| `level_1` … `level_5`              | Категория и подкатегории 1–4                    |
| `imported_qty`                     | Количество импортированных                      |
| `imported_retail_sum`              | Сумма импорта по цене продажи                   |
| `imported_supply_sum`              | Сумма импорта по цене поставки                  |
| `sold_qty`                         | Продажи, количество                             |
| `sold_retail_sum`                  | Сумма продаж по цене продажи                    |
| `sold_supply_sum`                  | Сумма продаж по цене поставки                   |
| `sold_sale_sum`                    | Сумма продаж по цене со скидкой                 |
| `written_off_qty`                  | Списания, количество                            |
| `written_off_retail_sum`           | Сумма списаний по цене продажи                  |
| `written_off_supply_sum`           | Сумма списаний по цене поставки                 |
| `transfer_finished_qty`            | Отправленные перемещения, количество            |
| `transfer_finished_retail_sum`     | Сумма отправленных перемещений по цене продажи  |
| `transfer_finished_supply_sum`     | Сумма отправленных перемещений по цене поставки |
| `transfer_arrived_qty`             | Принятые перемещения, количество                |
| `transfer_arrived_retail_price`    | Сумма принятых перемещений по цене продажи      |
| `transfer_arrived_supply_sum`      | Сумма принятых перемещений по цене поставки     |
| `repricing_qty`                    | Переоценка, количество                          |
| `repricing_retail_sum`             | Сумма переоценок по цене продажи                |
| `repricing_supply_sum`             | Сумма переоценок по цене поставки               |
| `returned`                         | Возвраты, количество                            |
| `returned_retail_sum`              | Сумма возвратов по цене продажи                 |
| `returned_supply_sum`              | Сумма возвратов по цене поставки                |
| `left_qty`                         | Остаток, количество                             |
| `left_retail_sum`                  | Сумма остатков по цене продажи                  |
| `left_supply_sum`                  | Сумма остатков по цене поставки                 |
| `return_supplier_order_qty`        | Возвраты заказа, количество                     |
| `return_supplier_order_retail_sum` | Сумма возвратов заказа по цене продажи          |
| `return_supplier_order_supply_sum` | Сумма возвратов заказа по цене поставки         |

### Продажи по поставщикам

[`POST /v1/sells-supplier-report-excel`](/reference/api/operations/post_v1_sells_supplier_report_excel/) · файл `Отчет продажи по поставщикам за <start_date> - <end_date>_<id>`

Продажи товаров в разрезе поставщиков. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "supplier_ids": ["8c1a25e0-4f7b-4c6a-9d2e-1b0f5a3c7d94"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "price_type": 1,
  "all_suppliers": 0,
  "detalization": "day",
  "fields": ["date", "supplier_name", "gross_sales", "net_profit"]
}
```

Колонки:

| Значение `fields`                     | Колонка в файле                       |
| ------------------------------------- | ------------------------------------- |
| `date`                                | Дата                                  |
| `supplier_name`                       | Поставщик                             |
| `product_name`                        | Наименование                          |
| `product_sku`                         | Артикул                               |
| `product_barcode`                     | Баркод                                |
| `product_brand_name`                  | Бренд                                 |
| `shop_name`                           | Название магазина                     |
| `categories_path`                     | Категория                             |
| `level_1` … `level_5`                 | Категория и подкатегории 1–4          |
| `free_price`                          | Свободная цена                        |
| `used_wholesale_price`                | Оптовая цена                          |
| `product_measurement_unit_short_name` | Единица измерения                     |
| `product_suppliers`                   | Поставщики                            |
| `sold_measurement_value`              | Количество проданных                  |
| `returned_measurement_value`          | Количество возвращённых               |
| `net_sold_measurement_value`          | Продано за вычетом возвратов          |
| `gross_sales`                         | Продажи без учёта скидки              |
| `returned_sales_sum`                  | Сумма возвратов                       |
| `net_sales`                           | Продажи со скидкой с учётом возвратов |
| `net_profit`                          | Валовая прибыль                       |
| `sold_supply_sum`                     | Продажи по цене закупки               |
| `average_margin`                      | Средняя наценка                       |
| `discount`                            | Скидка                                |
| `sold_with_discount`                  | Продано со скидкой                    |
| `sold_without_discount`               | Продано без скидки                    |

### Возвраты заказов

[`POST /v1/supplier-order-returned-export`](/reference/api/operations/post_v1_supplier_order_returned_export/) · файл `Отчет по возвращенным заказам за <start_date> - <end_date>_<id>`

Возвраты товаров поставщикам по заказам. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "display_currency": "UZS",
  "fields": ["created_at", "product_name", "total_return_price"]
}
```

Колонки:

| Значение `fields`     | Колонка в файле              |
| --------------------- | ---------------------------- |
| `return_operation_id` | ID операции возврата         |
| `order_operation_id`  | ID операции заказа           |
| `shop_name`           | Магазин                      |
| `created_at`          | Дата и время                 |
| `created_by_name`     | Пользователь                 |
| `product_name`        | Наименование                 |
| `product_sku`         | Артикул                      |
| `product_barcode`     | Баркод                       |
| `product_brand`       | Бренд                        |
| `categories_path`     | Категория                    |
| `level_1` … `level_5` | Категория и подкатегории 1–4 |
| `measurement_value`   | Количество                   |
| `supply_price`        | Цена поставки                |
| `retail_price`        | Цена продажи                 |
| `supplier_order_name` | Заказ                        |
| `total_return_price`  | Сумма возврата               |
| `supplier_name`       | Поставщик                    |

### Результаты инвентаризации

[`POST /v1/stocktaking-summary-table-excel-export`](/reference/api/operations/post_v1_stocktaking_summary_table_excel_export/) · файл `Отчет итоги инвентаризации - <id>`

Итоги одной инвентаризации: заявлено, проверено, что списано и доимпортировано по её результатам. Периода у отчёта нет — это снимок. `stocktaking_guid` берётся из [`GET /v2/stocktaking`](/reference/api/operations/get_v2_stocktaking/). В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "stocktaking_guid": "eeeeaf2b-1360-4f03-aa74-87ad7cc2edd7",
  "currency": "UZS",
  "fields": ["product_name", "expected_measurement_value", "scanned_measurement_value"]
}
```

Колонки:

| Значение `fields`                   | Колонка в файле                            |
| ----------------------------------- | ------------------------------------------ |
| `stocktaking_external_id`           | ID                                         |
| `stocktaking_name`                  | Название инвентаризации                    |
| `shop_name`                         | Магазин                                    |
| `product_name`                      | Название                                   |
| `product_sku`                       | Артикул                                    |
| `product_barcode`                   | Баркод                                     |
| `product_brand`                     | Бренд                                      |
| `product_is_archived`               | Архивирован                                |
| `product_measurement_unit`          | Единица измерения                          |
| `product_categories`                | Категории                                  |
| `level_1`                           | Категория                                  |
| `level_2` … `level_5`               | Уровень 1–4                                |
| `expected_measurement_value`        | Заявлено                                   |
| `scanned_measurement_value`         | Проверено                                  |
| `sold_measurement_value`            | Продано во время инвентаризации            |
| `postponed_measurement_value`       | Отложено во время инвентаризации           |
| `written_off_measurement_value`     | Списано во время инвентаризации            |
| `in_transfer_measurement_value`     | В перемещении во время инвентаризации      |
| `transferred_measurement_value`     | Перемещено во время инвентаризации         |
| `imported_after_stocktaking_finish` | Автоимпорт по результатам инвентаризации   |
| `imported_supply_price_sum`         | Сумма излишков по цене поставки            |
| `imported_retail_price_sum`         | Сумма излишков по цене продажи             |
| `written_off_after_stocktaking`     | Автосписание по результатам инвентаризации |
| `written_off_supply_price_sum`      | Сумма недостач по цене поставки            |
| `written_off_retail_price_sum`      | Сумма недостач по цене продажи             |

### Остатки по товарам

[`POST /v1/stock-report-excel`](/reference/api/operations/post_v1_stock_report_excel/) · файл `Отчет по остаткам за <report_date>_<id>`

Остатки товаров по магазинам на выбранную дату. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["6f244db4-75d6-4fac-9841-14867d45e36a"],
  "report_date": "2026-08-31",
  "currency": "UZS",
  "fields": ["product_name", "measurement_value", "supply_price", "retail_price"]
}
```

Колонки:

| Значение `fields`                     | Колонка в файле        |
| ------------------------------------- | ---------------------- |
| `shop_name`                           | Магазин                |
| `product_name`                        | Наименование товара    |
| `supply_price`                        | Цена поставки          |
| `retail_price`                        | Цена продажи           |
| `measurement_value`                   | Количество             |
| `product_sku`                         | Артикул                |
| `product_barcode`                     | Баркод                 |
| `product_measurement_unit_short_name` | Единица измерения      |
| `product_brand_name`                  | Бренд                  |
| `categories_path`                     | Категория              |
| `level_1`                             | Категория              |
| `level_2` … `level_5`                 | Подкатегории 1–4       |
| `supplier_name`                       | Поставщик              |
| `estimated_margin`                    | Маржа, %               |
| `estimated_income`                    | Сумма прибыли остатков |
| `product_is_archived`                 | Архивирован            |

### Списания

[`POST /v1/write-off-report-table-export`](/reference/api/operations/post_v1_write_off_report_table_export/) · файл `Отчет по списаниям за <start_date> - <end_date>_<id>`

Списанные товары за период с причинами и суммами. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "currency": "UZS",
  "fields": ["product_name", "written_off_measurement_value", "product_supply_price", "product_retail_price"]
}
```

Колонки:

| Значение `fields`               | Колонка в файле              |
| ------------------------------- | ---------------------------- |
| `write_off_external_id`         | ID списания                  |
| `write_off_name`                | Название списания            |
| `write_off_reason`              | Причина списания             |
| `shop_name`                     | Название магазина            |
| `created_by_name`               | Имя пользователя             |
| `created_at`                    | Время создания               |
| `product_name`                  | Название товара              |
| `product_sku`                   | Артикул                      |
| `product_barcode`               | Баркод                       |
| `categories`                    | Категории                    |
| `level_1`                       | Категория                    |
| `level_2` … `level_5`           | Уровень 1–4                  |
| `product_brand`                 | Бренд                        |
| `supplier`                      | Поставщик                    |
| `product_is_archived`           | Архивирован                  |
| `product_supply_price`          | Цена поставки                |
| `product_retail_price`          | Цена продажи                 |
| `written_off_measurement_value` | Количество списанных товаров |
| `written_off_supply_price_sum`  | Сумма по цене поставки       |
| `written_off_retail_price_sum`  | Сумма по цене продажи        |

### Перемещения

[`POST /v1/transfer-report-excel-export`](/reference/api/operations/post_v1_transfer_report_excel_export/) · файл `Отчет по трансферам за <start_date> - <end_date>_<id>`

Перемещения товаров между магазинами. В `fields` принимаются UUID атрибутов и кастомных полей.

```json
{
  "shop_ids": ["2339a738-a67f-48d2-bb60-8cf4ec54d6cd"],
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "display_currency": "UZS",
  "group_by": "product_name",
  "date_group": "day",
  "fields": ["product_name", "from_shop", "to_shop", "sent_quantity", "arrived_quantity", "sum_supply_price"]
}
```

Колонки:

| Значение `fields`      | Колонка в файле         |
| ---------------------- | ----------------------- |
| `created_at`           | Отправлено              |
| `accepted_at`          | Принято                 |
| `name`                 | Перемещение             |
| `external_id`          | ID                      |
| `from_shop`            | Откуда                  |
| `to_shop`              | Куда                    |
| `product_name`         | Наименование            |
| `product_sku`          | Артикул                 |
| `product_barcode`      | Баркод                  |
| `product_brand`        | Бренд                   |
| `categories_path`      | Категория               |
| `product_attribute`    | Вариация                |
| `product_custom_field` | Кастомное поле          |
| `supplier`             | Поставщик               |
| `sent_quantity`        | Количество отправленных |
| `arrived_quantity`     | Количество принятых     |
| `sum_supply_price`     | Сумма по цене поставки  |
| `sum_retail_price`     | Сумма по цене продажи   |
| `measurement_name`     | Единица измерения       |

## Права

Все шестнадцать методов входят в [список маршрутов ключа интеграции](/reference/permissions/). Выдачу сужает список магазинов, доступных токену: переданные `shop_ids` пересекаются с разрешёнными.