История баланса

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

Адрес

Авторизация

Ключ управления с правом billing:read

Расходов на запросы здесь нет: они в расходе и запросах. Текущий баланс — GET /aitunnel/balance. API-ключ историю не читает: об остатке денег он знает только баланс.

Методы

Метод	Право	Что делает
`GET /balance/history`	`billing:read`	Всё, что меняло баланс, кроме расходов на запросы
`GET /referrals`	`billing:read`	Реферальная ссылка, ставка и сколько она принесла
`GET /referrals/earnings`	`billing:read`	Реферальные начисления, новые первыми

Как вызвать

curl "https://api.aitunnel.ru/v1/aitunnel/balance/history?type=topup&from=2026-11-01&to=2026-11-14&timezone=Europe/Moscow" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Параметры

Все необязательные. Без параметров — вся история, новые операции первыми.

Параметр	Смысл
`type`	`topup` — пополнение, `refund` — возврат, `referral` — реферальное начисление, `reward` — награда за задание, `promo` — промокод, `adjustment` — корректировка поддержки
`status`	`done` — проведена, `pending` — платёж ждёт оплаты или возврат в пути, `unpaid` — платёж отклонён или истёк
`method`	Чем оплачено: `card`, `sbp`, `tpay`, `company`, `crypto`, `foreign`, `manual`. Оставляет только платежи и возвраты по ним
`from`, `to`	Период: даты `YYYY-MM-DD`, целые сутки в `timezone`, обе включительно
`timezone`	Часовой пояс IANA для `from` и `to`, по умолчанию `UTC`
`payment_id`	Номер платежа: сам платёж и возвраты по нему
`q`	Поиск по названию и ИНН организации-плательщика, последним цифрам карты и комментарию к операции. До 100 символов
`limit`	От 1 до 100, по умолчанию 30
`cursor`	`next_cursor` предыдущей страницы

Ответ

JSON

{
  "data": [
    {
      "id": "p:418205731",
      "type": "topup",
      "status": "done",
      "occurred_at": "2026-11-14T13:17:42.000Z",
      "amount": 2150,
      "balance_after": 3150.4,
      "payment": {
        "id": 418205731,
        "status": "succeeded",
        "provider": "tbank",
        "source": "checkout",
        "amount": 2000,
        "bonus_amount": 150,
        "refunded_amount": 0,
        "card_pan": "430000******0777",
        "payment_url": "https://securepay.tinkoff.ru/new/AbCdEf12",
        "payer_name": null,
        "payer_inn": null,
        "created_at": "2026-11-14T13:16:00.000Z",
        "paid_at": "2026-11-14T13:17:42.000Z",
        "receipt_url": null
      }
    },
    {
      "id": "p:417990112",
      "type": "topup",
      "status": "unpaid",
      "occurred_at": "2026-11-03T08:40:15.000Z",
      "amount": 0,
      "balance_after": null,
      "payment": {
        "id": 417990112,
        "status": "failed",
        "provider": "tbank",
        "source": "checkout",
        "amount": 700,
        "bonus_amount": 0,
        "refunded_amount": 0,
        "card_pan": null,
        "payment_url": null,
        "payer_name": null,
        "payer_inn": null,
        "created_at": "2026-11-03T08:40:15.000Z",
        "paid_at": null,
        "receipt_url": null
      }
    }
  ],
  "next_cursor": null
}

Поле	Смысл
`id`	Не меняется между страницами: `p:` и номер платежа, `r:` и номер возврата, `l:` и номер записи
`type`, `status`	Как в фильтрах выше
`occurred_at`	Когда операция прошла
`amount`	На сколько изменился баланс, ₽, со знаком. У пополнения — сумма вместе с бонусом. `0` у неоплаченного платежа
`balance_after`	Баланс сразу после операции, ₽. `null`, если он не записан
`payment`	У пополнения: платёж целиком
`refund`	У возврата: `id`, `amount` — сколько вернули, `bonus_deducted` — сколько бонуса снято вместе с ним, `status`, `payment_id` и `payment_amount` — какой платёж возвращён, `receipt_url`
`referral`	У реферального начисления: `from_user` — чья оплата его принесла, маской; `payment_amount` — сумма той оплаты
`note`	У начислений без платежа: промокод, задание или комментарий поддержки. Может быть `null`

Одна операция — одна строка: платёж вместе со своим бонусом, возврат или отдельное начисление.
Неоплаченные платежи тоже здесь, с amount 0. Если у платежа есть payment.payment_url, по нему ещё можно заплатить.
next_cursor — передайте его в cursor, чтобы получить следующую страницу. null — страница последняя.

Рефералы

GET /referrals — сводка реферальной программы аккаунта:

curl https://api.aitunnel.ru/v1/aitunnel/referrals \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "link": "https://aitunnel.ru/?r=123",
  "rate": 0.1,
  "total_referred": 3,
  "total_earned": 180.5,
  "has_referrer": false,
  "recent": [
    {
      "user": "ve***@example.com",
      "earned": 30,
      "joined_at": "2026-11-10T07:21:09.000Z"
    },
    {
      "user": "an***@example.com",
      "earned": 150.5,
      "joined_at": "2026-10-02T16:05:44.000Z"
    }
  ]
}

Поле	Смысл
`link`	Ссылка-приглашение
`rate`	Доля платежа приглашённого, которую получает пригласивший: `0.1` — 10%. Бонус к платежу не считается
`total_referred`	Сколько аккаунтов пришло по ссылке
`total_earned`	Сколько они принесли за всё время, ₽
`has_referrer`	`true`, если сам аккаунт зарегистрирован по чьему-то приглашению
`recent`	До 10 последних приглашённых: `user` — почта маской, `earned` — сколько принёс, `joined_at` — когда зарегистрировался

GET /referrals/earnings — каждое начисление отдельно, новые первыми. Параметры limit (от 1 до 100, по умолчанию 30) и cursor:

JSON

{
  "data": [
    {
      "id": 5120,
      "amount": 50.5,
      "from_user": "an***@example.com",
      "payment_amount": 505,
      "created_at": "2026-11-12T10:14:03.000Z"
    }
  ],
  "next_cursor": null
}

amount — сколько начислено, ₽; payment_amount — сумма платежа, с которого оно начислено; from_user — приглашённый, маской. Те же начисления видны в истории баланса с типом referral.

Ошибки

Статус	Смысл
`400`	`invalid_request` — неверный параметр: значение фильтра, дата, пояс, `limit` или `cursor`. В `error.metadata.fields` — каждый параметр с объяснением
`401`	`authentication_failed` — ключа нет, он неверный, отозван или истёк
`403`	`permission_denied` — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом