Подписки

Пользователь оплачивает пакет на вашей стороне, после чего вы выдаёте ему подписку в Ai-Seven через API. Взаиморасчёт между компаниями происходит отдельно, по итогам периода.

Список пакетов

GET /api/v1/partner/subscription-plans

Возвращает пакеты, доступные для выдачи. У каждого варианта зафиксированы срок и объём токенов.

[
  {
    "title": "Базовый",
    "prices": [
      { "id": 2, "period_months": 3,  "tokens": 200000, "price": 5500 },
      { "id": 3, "period_months": 6,  "tokens": 400000, "price": 8500 },
      { "id": 4, "period_months": 12, "tokens": 700000, "price": 12500 }
    ]
  }
]

string

Название пакета.

array

Варианты пакета с разными сроками.

Show поля

integer

Идентификатор варианта. Его нужно передавать при выдаче как plan_price_id.

integer | null

Срок подписки в месяцах. null — бессрочный вариант.

integer

Количество токенов, начисляемых при выдаче.

number

Стоимость в рублях.

Запрашивайте список перед выдачей — состав пакетов и цены могут меняться. Выдать можно только существующий вариант. Пакеты с ограниченным числом мест в список не входят и через API не выдаются.

Выдача подписки

POST /api/v1/partner/subscriptions

Получателя указывают одним из двух способов:

user_id — ваш идентификатор пользователя (sub токена входа). Если аккаунта ещё нет, он создаётся.
public_id — наш идентификатор из статистики или из токена виджета. Пакет ложится в существующий аккаунт, новый не создаётся.

Заголовки

Authorization: Bearer <JWT>
Idempotency-Key: <уникальный ключ операции>

string

required

Уникальный ключ операции, от 6 до 64 символов. Защищает от повторной выдачи при таймаутах и ретраях.

Тело запроса

{
  "user_id": "u_12345",
  "plan_price_id": 3,
  "payment_id": "pay_998877",
  "user_info": {
    "first_name": "Иван",
    "last_name": "Петров"
  }
}

{
  "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
  "plan_price_id": 3,
  "payment_id": "pay_998878",
  "marketing_percent": 50
}

string

Идентификатор пользователя в вашей системе — тот же, что вы передаёте в sub токена входа. От 1 до 64 символов. Передаётся ровно одно из user_id и public_id.

string

Идентификатор пользователя в Ai-Seven, UUID. Передаётся ровно одно из user_id и public_id.

integer

required

Идентификатор варианта пакета из GET /subscription-plans.

string

required

Идентификатор платежа в вашей системе, от 1 до 64 символов. Используется при сверке взаиморасчётов и защищает от повторной выдачи по одному платежу. Важно: параметр уникален в рамках партнёра.

integer

default:"0"

Процент цены пакета, от которого начисляются выплаты маркетинга, от 0 до 100. Учитывается, только если маркетинг при выдаче включён для вашей интеграции — см. Выплаты маркетинга.

object

Данные пользователя для отображения в кабинете. Учитываются только при выдаче по user_id и только при создании нового аккаунта.

Show поля

string

Имя, до 64 символов.

string

Фамилия, до 64 символов.

Ответ

{
  "user_id": null,
  "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
  "activated_until": 1770252120,
  "plan_title": "Базовый",
  "plan_price_id": 3
}

string | null

Ваш идентификатор пользователя — если выдача была по user_id. При выдаче по public_id — null.

string

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

integer

Момент окончания пакета, который действует у пользователя после выдачи, unix-время в секундах. У бессрочного пакета — 4102444800 (01.01.2100).

string

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

integer

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

Пример

import uuid
import requests

requests.post(
    "https://aisevenai.ru/api/v1/partner/subscriptions",
    headers={
        "Authorization": f"Bearer {api_token}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "public_id": "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
        "plan_price_id": 3,
        "payment_id": "pay_998878",
        "marketing_percent": 50,
    },
)

import { randomUUID } from "crypto";

await fetch("https://aisevenai.ru/api/v1/partner/subscriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiToken}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    public_id: "9f1c2a6e-4b70-4f1a-9d2c-8b5e0a7d3f42",
    plan_price_id: 3,
    payment_id: "pay_998878",
    marketing_percent: 50,
  }),
});

curl -X POST https://aisevenai.ru/api/v1/partner/subscriptions \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_12345",
    "plan_price_id": 3,
    "payment_id": "pay_998877"
  }'

Выплаты маркетинга

Выдача пакета может запускать выплаты маркетинга Ai-Seven — так же, как покупка этого пакета на сайте: прямой бонус и матчинг вышестоящим по структуре пользователя, учёт в обороте периодических бонусов. Выплаты получают пользователи Ai-Seven, с вас ничего не списывается. Выплаты запускаются, только если выполнены все условия:

Маркетинг при выдаче включён для вашей интеграции

Включается с нашей стороны вместе с суточным потолком выдач — договоритесь с контактным лицом в Ai-Seven. Без включения marketing_percent не учитывается: пакет выдаётся, выплат нет.

В запросе передан marketing_percent больше 0

Не передан или 0 — пакет выдаётся без выплат.

База выплат — цена варианта пакета в нашем каталоге (price из GET /subscription-plans) × marketing_percent / 100. Например, вариант за 8 500 ₽ с marketing_percent: 50 даёт выплаты как покупка за 4 250 ₽. Повтор успешной выдачи с тем же Idempotency-Key или payment_id второй раз ничего не выдаёт и не начисляет.

Лимиты

Суточный потолок выдач

Сумма цен выданных вами пакетов за сутки по московскому времени, с 00:00. Задаётся с нашей стороны. Выдача, с которой сумма превысит потолок, отклоняется с 429 — ничего не выдаётся и не начисляется.

Лимиты запросов

Число запросов в минуту и в сутки на всю интеграцию — общее для всех эндпоинтов Partner API. Подробнее — в Обзоре.

Поведение

Пользователь ещё не заходил в Ai-Seven

При выдаче по user_id аккаунт создаётся автоматически, пакет ждёт первого входа. Сценарий «купил, потом зашёл» работает — пользователю достаточно перейти по кнопке из вашего кабинета.При выдаче по public_id аккаунт не создаётся: неизвестный public_id — 404.

У пользователя уже есть подписка

Выдача не понижает действующий пакет пользователя. Прежний пакет остаётся, если он выше рангом, а при равном ранге — если он кончается позже, чем кончился бы выданный, или это другой пакет и он дороже. Тогда plan_title, plan_price_id и activated_until в ответе — прежнего пакета. В остальных случаях пакет заменяется на выданный — пакеты не суммируются.Выданный пакет действует с момента выдачи на свой полный срок, остаток прежнего пакета к нему не прибавляется. Месяц срока — 30 суток.Доступ к платформе продлевается до более поздней из двух дат: нынешнего окончания доступа или момента выдачи плюс срок пакета.Токены выданного варианта начисляются в любом случае.

Повторный запрос с тем же Idempotency-Key

Успешный ответ повторяется как есть, повторной выдачи не происходит. Если операция завершилась ошибкой, ключ освобождается, и повтор с тем же ключом выполняет её заново (например, после 429 потолка — на следующие сутки).Если первая операция ещё выполняется, вернётся 409. Если ключ пришёл с другим телом запроса — 422.

Повторный запрос с тем же payment_id

Возвращается 409. Один платёж может быть использован для выдачи только один раз, независимо от ключа идемпотентности.

Ошибки

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

Код	`error.code`	Сообщение	Причина
`403`	`test_partner_grants_by_user_id`	Тестовый партнёр выдаёт пакеты только по user_id	Тестовая интеграция передала `public_id`
`404`	`plan_not_found`	Пакет подписки не найден	Указан несуществующий `plan_price_id`
`404`	`user_not_found`	Пользователь не найден	Указан несуществующий `public_id`
`409`	`duplicate_payment`	Платеж с таким payment_id уже есть	По этому платежу подписка уже выдавалась
`409`	`limited_pack_direct_payment_only`	Этот пакет покупается только прямой оплатой	Вариант пакета с ограниченным числом мест
`409`	`conflict`	Операция выполняется	Запрос с этим `Idempotency-Key` ещё обрабатывается
`422`	`validation_error`	Ключ идемпотентности использован с другим телом запроса	Тот же ключ прислан с изменёнными данными
`422`	`validation_error`	массив с разбором полей, см. Формат ошибки	Запрос не прошёл проверку: нет `Idempotency-Key` или его длина вне 6–64 символов, `public_id` не UUID, переданы оба или ни одного из `user_id` и `public_id`, `marketing_percent` вне 0–100
`429`	`partner_daily_cap_exceeded`	Превышен суточный потолок выдач партнёра: … ₽	Выдача превысила бы суточный потолок
`500`	`partner_user_failed`	Не удалось создать пользователя	Внутренняя ошибка при создании аккаунта — повторите запрос
`500`	`partner_user_failed`	Внутренняя ошибка при идентификации пользователя	Внутренняя ошибка при поиске аккаунта — повторите запрос
`503`	`service_unavailable`	Внутренняя ошибка. Мы уже разбираемся.	Временная ошибка — повторите запрос с тем же ключом

Используйте новый Idempotency-Key на каждую операцию выдачи. При повторном использовании ключа с другими данными вернётся 422, и выдача не выполнится.

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

Авторизация

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

Виджет

Список пакетов

Выдача подписки

Заголовки

Тело запроса

Ответ

Пример

Выплаты маркетинга

Лимиты

Суточный потолок выдач

Лимиты запросов

Поведение

Ошибки