# Экспорт CSV и отчётность: как выгрузить счета

> Выгрузка счетов из кабинета и через API, смысл фильтров и колонок, кодировка UTF-8, иероглифы в Excel и сверка с отчётом в кабинете Kaspi Pay — почему суммы могут не совпасть точно.

## Коротко

Список счетов можно получить двумя способами: **из раздела Счета в кабинете** (ставите фильтры и выгружаете то, что видите) и **через API** (`GET /api/v1/invoices` с фильтрами по периоду и статусу). Данные одни и те же, разница только в удобстве.

Два правила, которые решают почти все проблемы: **кодировка UTF-8** (если открыть файл в Excel двойным щелчком, будут иероглифы) и **песочница отделена от боевого режима** (тестовые счета в бухгалтерию не отдают).

## Выгрузка из кабинета

Кабинет → **Счета**. Перед выгрузкой выставьте фильтры:

| Фильтр | Что делает |
|---|---|
| Поиск | По идентификатору счёта, номеру заказа, описанию, телефону или имени клиента |
| Статус | `pending`, `paid`, `failed`, `expired`, `cancelled`, `refunded` |
| Режим | Режим организации: счета песочницы лежат отдельно от боевых |
| Кассир | Если ключ привязан к конкретному кассиру, в списке только его счета |

После фильтрации список сохраняется в файл. Если период нужен точный (например, календарный месяц), удобнее взять API — там есть параметры `from` и `to`.

## Выгрузка через API

`GET /api/v1/invoices` принимает все фильтры:

| Параметр | Значение |
|---|---|
| `from`, `to` | Начало и конец периода (дата-время ISO) |
| `status` | Один статус |
| `externalOrderId` | Конкретный номер заказа |
| `search` | По идентификатору, номеру заказа, описанию, телефону, имени |
| `limit`, `offset` | Не больше 200 записей за запрос, остальное через `offset` |

В ответе приходит список `invoices` и `total` — общее количество записей, подходящих под фильтр. Если `total` больше выданного, идите дальше страницами через `offset`.

Например, счета за август:

```bash
curl -s 'https://api.qut.kz/api/v1/invoices?from=2026-08-01T00:00:00%2B05:00&to=2026-08-31T23:59:59%2B05:00&limit=200' \
  -H 'X-API-Key: qp_live_…'
```

Полученный JSON превращаете в CSV любым удобным инструментом. Файл сохраняйте в **UTF-8** — это единственное условие, при котором русские и казахские буквы отобразятся правильно.

Если ключ привязан к кассиру, в выгрузке будут только его боевые счета: [Привязка API-ключа к кассиру](/kb/ru/api-key-connection).

## Что означают колонки

Колонки повторяют поля счёта.

| Колонка | Смысл |
|---|---|
| `id` | Идентификатор счёта, `inv_…` |
| `createdAt` | Когда счёт создан |
| `paidAt` | Когда оплата подтверждена. У неоплаченного пусто |
| `amount` | Сумма в тенге |
| `refundedAmount` | Возвращённая сумма, если возврат был |
| `status` | Статус счёта |
| `kind` | `qr` или `phone` |
| `mode` | `live` или `sandbox` |
| `description` | Описание, которое видит покупатель |
| `externalOrderId` | Ваш номер заказа |
| `customer` | Имя, телефон, email — только то, что передали вы |
| `receiptNumber` | Номер чека у оплаченного счёта |

Как читать статусы:

| Статус | Что значит в отчёте |
|---|---|
| `new`, `pending` | Открытый счёт, денег ещё нет |
| `paid` | Оплачен |
| `cancelled`, `expired` | Закрыт, денег нет |
| `failed` | Платёж не прошёл |
| `refunded` | Оплачен, затем возвращён полностью |
| `partially_refunded` | Оплачен, часть возвращена |

**Как правильно посчитать выручку:** `paid`, `refunded` и `partially_refunded` — все три означают оплаченный счёт, но из двух последних нужно вычесть возврат. То есть чистая выручка = сумма `amount` − сумма `refundedAmount`. Счета `new` и `pending` в выручку не входят.

## Кодировка и Excel

Файл в UTF-8. При открытии двойным щелчком Excel пытается прочитать его в старой кодировке вашего компьютера — отсюда иероглифы. С самим файлом при этом всё в порядке.

Как открыть правильно:

1. откройте в Excel пустую книгу;
2. **Данные** → **Получить данные** → **Из текста/CSV**;
3. выберите файл;
4. в поле **Кодировка файла** (File Origin) поставьте **65001: Юникод (UTF-8)**;
5. проверьте разделитель и нажмите **Загрузить**.

В том же окне задайте колонкам телефона и номера заказа тип **Текст** — иначе Excel превратит длинные числа в `7,7051E+10` или срежет ведущий ноль.

Самый простой путь — открыть файл в Google Sheets или LibreOffice Calc: оба распознают UTF-8 сами. Подробный разбор проблем: [Экспорт не открывается или неверный](/kb/ru/csv-export-issue).

## Передача в бухгалтерию

- **Ставьте период по календарному месяцу**, часовой пояс — Алматы.
- **Убедитесь, что вы в боевом режиме.** Строки песочницы в отчёт попадать не должны.
- **Сохраните файл в XLSX** — чтобы иероглифы не повторились на компьютере бухгалтера.
- **Предупредите, что деньги приходят прямо на счёт в Kaspi.** Эта выгрузка — список счетов, а банковская выписка — движение денег: [Когда и куда приходят деньги](/kb/ru/money-arrival).

Если организаций несколько, отчётность у каждой своя: [Несколько организаций в одном аккаунте](/kb/ru/multiple-organizations).

## Сверка с отчётом Kaspi Pay

Наш список и отчёт в кабинете Kaspi Pay — про разные вещи. У нас — **счета, которые мы выставили**, у Kaspi — **движение по вашему счёту**. Поэтому полное совпадение цифр не является нормой. Причины расхождений:

| Причина | Пояснение |
|---|---|
| Kaspi сам определяет удерживаемую сумму | Поступление в отчёте Kaspi может быть меньше суммы нашего счёта |
| Платежи мимо Qut Pay | Наличные, POS, счёт, выставленный вручную в приложении Kaspi — у Kaspi есть, у нас нет |
| Поздние оплаты | Деньги могут прийти после закрытия счёта: [Поздняя оплата](/kb/ru/late-payment) |
| Возвраты | В выписке Kaspi возврат идёт отдельной строкой, у нас он внутри счёта |
| Граница периода | Счёт, созданный под полночь, может быть оплачен уже следующим днём |
| Строки песочницы | В Kaspi их нет вообще |
| Несколько кассиров | Если ключ привязан к одному кассиру, в выгрузке только его счета |

Порядок сверки: выставьте одинаковый период в обоих местах → возьмите из нашей выгрузки только `paid`, `refunded`, `partially_refunded` → вычтите возвраты → сравните с поступлениями за этот период в выписке Kaspi → остаток разницы ищите среди платежей, прошедших мимо Qut Pay.

## Вопросы и ответы

**Почему в выгрузке нет тиынов?** У QR-счёта допускается не больше двух знаков после запятой, счёт на телефон идёт целыми тенге. Поэтому в части строк дробной части просто нет.

**Можно ли выгрузить весь год одним запросом?** Нет, за запрос отдаётся максимум 200 записей. Листайте через `offset` или разбейте период на месяцы.

**Есть ли в выгрузке дополнительные данные о клиенте?** Только то, что вы сами передали при создании счёта. Мы не собираем о покупателе ничего сверх этого.

**Выгрузка вернула меньше строк, чем раньше.** Статусы могли измениться (например, прошёл возврат), но сама строка не пропадает. Снимите фильтр по статусу и проверьте ещё раз.

**Попадают ли счета песочницы в лимит тарифа?** Нет, и в отчётность они попадать тоже не должны.