Траты клиента за период

Траты за период

POST https://gptunnel.ru/api/v1/balance/spending

Возвращает траты клиента в рублях за период с разбивкой по дням или по месяцам. Клиент задаётся ровно одним полем:

user_id — траты пользователя: с личного счёта и со счетов организаций-клиентов партнёра, в которых он работает;
org_id — траты со счёта организации, по всем её сотрудникам.

Тратой считаются списания за использование сервиса — запросы к моделям и другие платные функции — за вычетом возвратов за неуспешные генерации. Возврат может прийти в другой день, чем списание, поэтому сумма за период бывает отрицательной. Пополнения, переводы и возвраты переводов в выдачу не попадают.

Метод только читает данные, заголовок Idempotency-Key не нужен.

Headers

Параметр	Тип	Описание
`Authorization`*	`string`	API ключ организации
`Content-Type`*	`string`	application/json

Параметры запроса

Параметр	Тип	Описание
`user_id`	`string`	ID пользователя-клиента, 24 hex-символа строчными. Ровно одно из user_id, org_id и user_data
`org_id`	`string`	ID организации-клиента, 24 hex-символа строчными. Ровно одно из user_id, org_id и user_data
`user_data`	`object`	Поиск пользователя по телефону: { "phone": "+79XXXXXXXXX" }. Подключается отдельно, см. обзор
`date_from`*	`string`	Начало периода, YYYY-MM-DD, включительно
`date_to`*	`string`	Конец периода, YYYY-MM-DD, включительно. Не раньше date_from
`group_by`	`string`	day (по умолчанию) или month
`by_user`	`boolean`	true — добавить в каждый период разбивку по сотрудникам. Только вместе с org_id

Границы дней и месяцев считаются по московскому времени. Длина периода ограничена: до 92 дней при group_by: "day" и до 366 дней при group_by: "month".

Пример запроса

curl --request POST \
  --url https://gptunnel.ru/api/v1/balance/spending \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "6ad72133269dc8d9f75a33bc",
    "date_from": "2026-11-01",
    "date_to": "2026-11-02"
}'

import axios from 'axios'

const response = await axios({
  method: 'POST',
  url: 'https://gptunnel.ru/api/v1/balance/spending',
  headers: { Authorization: 'YOUR_API_KEY' },
  data: {
    user_id: '6ad72133269dc8d9f75a33bc',
    date_from: '2026-11-01',
    date_to: '2026-11-02',
  },
})

console.log(response.data)

import requests

response = requests.post(
    'https://gptunnel.ru/api/v1/balance/spending',
    headers={'Authorization': 'YOUR_API_KEY'},
    json={
        'user_id': '6ad72133269dc8d9f75a33bc',
        'date_from': '2026-11-01',
        'date_to': '2026-11-02',
    },
)

print(response.json())

Ответ

Поля ответа

Параметр	Тип	Описание
`code`	`number`	0 при успехе
`type`	`string`	user или org — по кому построен отчёт
`id`	`string`	ID пользователя или организации
`date_from`	`string`	Начало периода из запроса
`date_to`	`string`	Конец периода из запроса
`group_by`	`string`	day или month
`currency`	`string`	Всегда RUB
`periods`	`array`	По одному элементу на каждый день или месяц периода, по возрастанию. Периоды без трат тоже присутствуют, с нулями
`summary`	`object`	Итог за весь период в тех же полях, что у элемента periods, без period и users

Элемент periods

Параметр	Тип	Описание
`period`	`string`	YYYY-MM-DD при группировке по дням, YYYY-MM — по месяцам
`amount`	`number`	Потрачено рублей. Отрицательное, если возвратов в периоде больше, чем списаний
`bonus`	`number`	Потрачено бонусов, 1 бонус = 0,5 ₽
`total`	`number`	Итог в рублях: amount плюс бонусы по курсу
`personal`	`object`	Только для пользователя: траты с личного счёта — amount, bonus, total
`orgs`	`array`	Только для пользователя: его траты со счетов организаций — org_id, amount, bonus, total; по убыванию total
`users`	`array`	Только для org_id с by_user: true — траты по сотрудникам: user_id, amount, bonus, total; по убыванию total

При группировке по месяцам в неполный месяц попадают только дни внутри date_from — date_to.

200 Пользователь
200 Организация по сотрудникам

{
  "code": 0,
  "type": "user",
  "id": "6ad72133269dc8d9f75a33bc",
  "date_from": "2026-11-01",
  "date_to": "2026-11-02",
  "group_by": "day",
  "currency": "RUB",
  "periods": [
    {
      "period": "2026-11-01",
      "amount": 86.4,
      "bonus": 0,
      "total": 86.4,
      "personal": { "amount": 36.4, "bonus": 0, "total": 36.4 },
      "orgs": [
        { "org_id": "6ad7a4f2269dc8d9f75a41d0", "amount": 50, "bonus": 0, "total": 50 }
      ]
    },
    {
      "period": "2026-11-02",
      "amount": 0,
      "bonus": 0,
      "total": 0,
      "personal": { "amount": 0, "bonus": 0, "total": 0 },
      "orgs": []
    }
  ],
  "summary": {
    "amount": 86.4,
    "bonus": 0,
    "total": 86.4,
    "personal": { "amount": 36.4, "bonus": 0, "total": 36.4 },
    "orgs": [
      { "org_id": "6ad7a4f2269dc8d9f75a41d0", "amount": 50, "bonus": 0, "total": 50 }
    ]
  }
}

{
  "code": 0,
  "type": "org",
  "id": "6ad7a4f2269dc8d9f75a41d0",
  "date_from": "2026-10-01",
  "date_to": "2026-10-31",
  "group_by": "month",
  "currency": "RUB",
  "periods": [
    {
      "period": "2026-10",
      "amount": 1240.75,
      "bonus": 0,
      "total": 1240.75,
      "users": [
        { "user_id": "6ad72133269dc8d9f75a33bc", "amount": 900.5, "bonus": 0, "total": 900.5 },
        { "user_id": "6ad8c0be269dc8d9f75a52e1", "amount": 340.25, "bonus": 0, "total": 340.25 }
      ]
    }
  ],
  "summary": { "amount": 1240.75, "bonus": 0, "total": 1240.75 }
}

Ошибки

HTTP	code	Когда
400	3	Тело не по схеме: нет клиента или указано больше одного поля, лишнее поле, id не из 24 символов `0-9a-f`, дата не `YYYY-MM-DD` или несуществующая, `date_from` позже `date_to`, период длиннее лимита, `by_user: true` без `org_id`. Подробности — в поле `details`
403	13	Ключ личного аккаунта, а не организации
403	27	Поиск по `user_data` организации не подключён
403	40	Организации ключа метод не подключён
404	17	Пользователь не найден, удалён или не является клиентом партнёра
404	24	Организация не найдена, удалена или не является клиентом партнёра

Ключ проверяется раньше тела: ключ без доступа получит 403 даже на запрос с телом не по схеме.

Полный список кодов и ответ 401 на неверный ключ — в справочнике ошибок.