Статистика

Статистику вы забираете сами — мы не отправляем исходящих запросов к вашей системе. Данные доступны за любой период и обновляются по мере активности пользователей.

Справочник событий

GET /api/v1/partner/stats/user-events

Возвращает список событий, по которым доступна статистика. Ключи из поля type — это же ключи объектов stats и counts в ответах статистики.

[
  { "type": "generation.text",  "description": "Генераций текста" },
  { "type": "generation.image", "description": "Генераций изображений" },
  { "type": "generation.video", "description": "Генераций видео" },
  { "type": "generation.audio", "description": "Генераций аудио" },
  { "type": "tokens.spent",     "description": "Потрачено токенов" },
  { "type": "crm.sale",         "description": "Продажи" },
  { "type": "crm.registration", "description": "Регистрации" }
]

string

Ключ события. Используется как ключ в объектах stats и counts.

string

Название события на русском языке — можно показывать в интерфейсе как есть.

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

Единицы событий

В stats — сумма по событию за период, в counts — сколько раз событие произошло. Единица суммы у каждого события своя:

Событие	`stats` — сумма	`counts` — число
`generation.*`	генерации, штуки	генерации
`tokens.spent`	списанные токены	списания
`crm.sale`	полученные выплаты, в копейках	выплаты
`crm.registration`	приглашённые пользователи	приглашённые пользователи

Сумма crm.sale — в копейках, а не в рублях: 125000 — это 1 250 ₽. Делите на 100 перед показом.

Статистика пользователей

GET /api/v1/partner/stats/users

Постраничный список пользователей с их активностью. Здесь приходит public_id каждого пользователя с активностью за период; ещё он приходит в ответе выдачи подписки и в sub токена виджета. Сохраните его, чтобы потом запрашивать статистику по конкретному пользователю.

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

integer

Позиция, с которой продолжить обход. Для первой страницы не передаётся, дальше — значение next_cursor из предыдущего ответа.

integer

default:"20"

Размер страницы, от 1 до 100.

integer

Начало периода, unix-время в секундах. Не передан — считаем с начала истории.

integer

Конец периода, unix-время в секундах. Не передан — считаем по настоящий момент.

Ответ

{
  "items": [
    {
      "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
      "external_user_id": "u_12345",
      "stats": {
        "generation.text": 128,
        "generation.image": 34,
        "generation.video": 6,
        "generation.audio": 2,
        "tokens.spent": 184300,
        "crm.sale": 125000,
        "crm.registration": 3
      },
      "counts": {
        "generation.text": 128,
        "generation.image": 34,
        "generation.video": 6,
        "generation.audio": 2,
        "tokens.spent": 141,
        "crm.sale": 2,
        "crm.registration": 3
      },
      "accesses": [
        { "key": "championship", "title": "Чемпионат", "expires_at": 1767214800 }
      ],
      "profile": {
        "name": "Иван Петров",
        "photo_url": "https://example.com/photo.jpg",
        "email": "ivan@example.com"
      }
    }
  ],
  "next_cursor": 4820
}

array

Пользователи, у которых была активность за период.

Show поля

string

Идентификатор пользователя в Ai-Seven. Нужен для запроса статистики по одному пользователю, для выдачи подписки и доступов.

string | null

Ваш идентификатор пользователя — тот, что вы передавали в sub токена входа. null, если пользователь пришёл не через вашу платформу.

object

Суммы по каждому событию из справочника за период. События без активности присутствуют со значением 0.

object

Число событий каждого типа за период. Ключи — те же, что в stats; события без активности — со значением 0.

array

Действующие доступы, которые пользователю выдали вы. Истёкшие и отозванные не показываются, доступы других партнёров — тоже. Нет доступов — пустой массив.

Show поля

string

Ключ доступа.

string

Название доступа.

integer | null

Момент окончания доступа, unix-время в секундах. null — бессрочный.

object | null

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

Show поля

string | null

Отображаемое имя: имя и фамилия из профиля.

string | null

Ссылка на фото профиля.

string | null

Email аккаунта.

integer | null

Курсор следующей страницы. null — данные закончились.

Статистика одного пользователя

GET /api/v1/partner/stats/users/{public_id}

string

required

Идентификатор пользователя из списка выше.

integer

Начало периода, unix-время в секундах.

integer

Конец периода, unix-время в секундах.

Ответ

{
  "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
  "external_user_id": "u_12345",
  "stats": {
    "generation.text": 12,
    "generation.image": 3,
    "generation.video": 0,
    "generation.audio": 0,
    "tokens.spent": 20450,
    "crm.sale": 0,
    "crm.registration": 1
  },
  "counts": {
    "generation.text": 12,
    "generation.image": 3,
    "generation.video": 0,
    "generation.audio": 0,
    "tokens.spent": 15,
    "crm.sale": 0,
    "crm.registration": 1
  },
  "accesses": [
    { "key": "championship", "title": "Чемпионат", "expires_at": null }
  ],
  "profile": null
}

string

Идентификатор пользователя в Ai-Seven.

string | null

Ваш идентификатор пользователя.

object

Суммы по каждому событию из справочника за период. События без активности присутствуют со значением 0.

object

Число событий каждого типа за период.

array

Действующие доступы, выданные вами. Поля — как в списке пользователей.

object | null

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

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

Пример

Обход всех страниц за последние сутки:

import time
import requests

BASE = "https://aisevenai.ru/api/v1/partner"
headers = {"Authorization": f"Bearer {api_token}"}
params = {"date_from": int(time.time()) - 86400, "limit": 100}

while True:
    response = requests.get(f"{BASE}/stats/users", headers=headers, params=params)
    response.raise_for_status()
    page = response.json()

    for user in page["items"]:
        sales_rub = user["stats"]["crm.sale"] / 100
        print(user["public_id"], user["counts"]["crm.registration"], sales_rub, user["accesses"])

    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

const BASE = "https://aisevenai.ru/api/v1/partner";
const params = new URLSearchParams({
  date_from: String(Math.floor(Date.now() / 1000) - 86400),
  limit: "100",
});

for (;;) {
  const response = await fetch(`${BASE}/stats/users?${params}`, {
    headers: { Authorization: `Bearer ${apiToken}` },
  });
  const page = await response.json();

  for (const user of page.items) {
    const salesRub = user.stats["crm.sale"] / 100;
    console.log(user.public_id, user.counts["crm.registration"], salesRub, user.accesses);
  }

  if (!page.next_cursor) break;
  params.set("cursor", String(page.next_cursor));
}

curl -G https://aisevenai.ru/api/v1/partner/stats/users \
  -H "Authorization: Bearer $API_TOKEN" \
  -d date_from=$(( $(date +%s) - 86400 )) \
  -d limit=100

Поведение

Что попадает в статистику

Учитывается вся активность пользователя в Ai-Seven, а не только то, что он делал после перехода из вашего кабинета.Генерации считаются штуками и раскладываются по категориям: text, image, video, audio. Составные инструменты попадают в категорию своего результата — например, слайды карусели считаются изображениями, а озвучка — аудио.tokens.spent — сумма списанных токенов за период, включая операции, которые не являются генерацией.

Продажи — crm.sale

Событие получает пользователь, которому выплачен бонус за покупку в его структуре: прямой бонус, матчинг или бонус за VIP-пакет. Одна выплата — одно событие.В stats — сумма полученных выплат в копейках, точно, без округления. В counts — число выплат. Бонус, который начислен, но не выплачен, события не даёт.Сумма события — это выплата пользователю, а не цена покупки, за которую она начислена.

Регистрации — crm.registration

Событие получает первый пригласитель пользователя — тот, кто пригласил его раньше всех. Если приглашений не было, событие получает текущий пригласитель. Одно событие на каждого приглашённого, сумма — 1. В stats и counts — число приглашённых за период.Время события — время этого первого приглашения. Если приглашения нет — момент, когда пользователь попал в структуру пригласителя, а если нет и его — время создания аккаунта. Регистрации записываются периодически, раз в 5 минут, поэтому появляются в статистике с задержкой до 5 минут — уже со временем приглашения.Каждый приглашённый учитывается один раз. Если у пользователя потом сменится пригласитель, второго события не будет, а первое останется у прежнего пригласителя.

После подключения события регистраций появятся и за прошлые периоды.

Кто попадает в список

В список попадают пользователи, у которых было хотя бы одно событие из справочника за указанный период — генерация, списание токенов, выплата или регистрация приглашённого. Пользователь без единого события за период не вернётся вовсе — это не то же самое, что нули в stats. Выданный вами доступ событием не считается.Сами объекты stats и counts в обоих эндпоинтах устроены одинаково: в них всегда присутствуют все события из справочника, отсутствующие — нулями.

Чужие пользователи в ответе

Список включает всех пользователей платформы, а не только пришедших через вашу интеграцию. У пользователей, пришедших не от вас, поле external_user_id равно null. Пользователи обезличены: имя, фото и email приходят только в profile и только с согласия пользователя на передачу данных вам.Если вам нужны только свои — отбирайте по непустому external_user_id на своей стороне.

Границы периода

date_from и date_to — unix-время в секундах, обе границы включительно, с точностью до секунды. Можно указать только одну: без date_from считаем с начала истории, без date_to — по текущий момент.События записываются в момент завершения операции. Генерация, начатая до date_to и завершившаяся после, попадёт в следующий период. Регистрации появляются с задержкой до 5 минут, но со временем приглашения.accesses и profile от периода не зависят — это состояние на момент запроса.

Ошибки

Помимо общих ошибок:

Код	`error.code`	Сообщение	Причина
`404`	`not_found`	Пользователь не найден	Указан несуществующий `public_id`
`422`	`validation_error`	—	`public_id` не является UUID, `limit` вне диапазона 1–100, отрицательные даты или неизвестный параметр запроса

Для регулярной выгрузки берите период, который закончился хотя бы 5 минут назад, и опирайтесь на date_from/date_to, а не на «всё время»: так объём ответа остаётся предсказуемым, регистрации за период уже записаны, и повторный запрос за тот же период даёт те же stats и counts. accesses и profile — состояние на момент запроса.

Начало работы

Авторизация

Партнёрский API

Виджет

Справочник событий

Единицы событий

Статистика пользователей

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

Ответ

Статистика одного пользователя

Ответ

Пример

Поведение

Ошибки