Подписки

Пользователь оплачивает пакет на вашей стороне, после чего вы выдаёте ему подписку в 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

Срок подписки в месяцах.

integer

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

number

Стоимость.

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

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

POST /api/v1/partner/subscriptions

Заголовки

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": "Петров"
  }
}

string

required

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

integer

required

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

string

required

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

object

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

Show поля

string

Имя.

string

Фамилия.

Ответ

{
  "user_id": "u_12345",
  "activated_until": 1770252120,
  "plan_title": "Базовый",
  "plan_price_id": 3
}

string

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

integer

Момент окончания действия пакета, unix-время.

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={
        "user_id": "u_12345",
        "plan_price_id": 3,
        "payment_id": "pay_998877",
        "user_info": {"first_name": "Иван", "last_name": "Петров"},
    },
)

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({
    user_id: "u_12345",
    plan_price_id: 3,
    payment_id: "pay_998877",
    user_info: { first_name: "Иван", last_name: "Петров" },
  }),
});

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

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

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

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

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

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

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

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

Ошибки

Помимо ошибок авторизации:

Код	Сообщение	Причина
`404`	Пакет подписки не найден	Указан несуществующий `plan_price_id`
`409`	Платеж с таким payment_id уже есть	По этому платежу подписка уже выдавалась
`409`	Операция выполняется	Запрос с этим `Idempotency-Key` ещё обрабатывается
`422`	Ключ идемпотентности использован с другим телом запроса	Тот же ключ прислан с изменёнными данными
`422`	—	Тело запроса не прошло валидацию
`500`	Не удалось создать пользователя	Внутренняя ошибка при создании аккаунта — повторите запрос
`503`	Не удалось обработать запрос, повторите попытку	Временная ошибка — повторите запрос с тем же ключом

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

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

Авторизация

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

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

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

Заголовки

Тело запроса

Ответ

Пример

Поведение

Ошибки

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

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

​Заголовки

​Тело запроса

​Ответ

​Пример

​Поведение

​Ошибки

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

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

Заголовки

Тело запроса

Ответ

Пример

Поведение

Ошибки