Обзор

Partner API позволяет управлять подписками и доступами ваших пользователей в Ai-Seven и забирать статистику со стороны вашего сервиса. База: https://aisevenai.ru/api/v1/partner

Авторизация

Запросы подписываются тем же приватным ключом, что и токены входа пользователей. Отдельные API-ключи не выдаются.

Authorization: Bearer <JWT>

Формат токена

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<ваш kid>"
}

{
  "aud": "ai-seven:api"
}

string

required

Всегда ai-seven:api. Отличает токен API от токена входа пользователя — они не взаимозаменяемы.

Больше в payload ничего не требуется: токен представляет вашу компанию, а не конкретного пользователя. Срок жизни не ограничен — подпишите токен один раз и укажите в конфигурации своего сервиса.

Не используйте токен входа пользователя (aud: "ai-seven:sso") для запросов к Partner API — такие запросы отклоняются.

Генерация токена

import jwt  # pip install pyjwt[crypto]

token = jwt.encode(
    {"aud": "ai-seven:api"},
    open("private.pem").read(),
    algorithm="RS256",
    headers={"kid": "<ваш kid>"},
)

import jwt from "jsonwebtoken";
import { readFileSync } from "fs";

const token = jwt.sign({ aud: "ai-seven:api" }, readFileSync("private.pem"), {
  algorithm: "RS256",
  keyid: "<ваш kid>",
});

<?php
use Firebase\JWT\JWT;

$token = JWT::encode(
    ['aud' => 'ai-seven:api'],
    file_get_contents('private.pem'),
    'RS256',
    '<ваш kid>'
);

Формат ошибки

Любая ошибка приходит в одном виде: текст для человека в detail и машинный код в error.code. Стройте обработку по error.code — тексты могут меняться.

{
  "detail": "Доступ с таким ключом уже заведён",
  "error": {
    "code": "access_exists",
    "request_id": "3b6f0c2e9a1d4e7f8a2c5b1d0e9f6a7c"
  }
}

string | array

Описание ошибки, строка. У ошибок разбора запроса — массив: параметры, заголовки или тело не прошли проверку.

string

Машинный код ошибки. Коды перечислены в разделе «Ошибки» каждого эндпоинта.

string

Идентификатор запроса — 32 шестнадцатеричных символа. Если вы передали свой заголовок X-Request-ID и он подходит под ^[A-Za-z0-9._-]{1,64}$, используется он. Тот же идентификатор приходит в заголовке ответа X-Request-ID. Сообщите его нам, если нужно разобраться с конкретным ответом.

array

Только у ошибок разбора запроса: список полей, не прошедших проверку.

Show поля

string

Имя поля, параметра или заголовка. Вложенные поля — через точку. У ошибки всего тела, например «нужен ровно один из user_id и public_id», — пустая строка.

string

Что не так с полем.

Ошибка разбора запроса:

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["header", "Idempotency-Key"],
      "msg": "String should have at least 6 characters",
      "input": "abc",
      "ctx": { "min_length": 6 }
    }
  ],
  "error": {
    "code": "validation_error",
    "request_id": "9d2e4b7a1c3f4e8b9a6d0c5e2f1b7a3d",
    "details": {
      "fields": [
        { "field": "Idempotency-Key", "reason": "String should have at least 6 characters" }
      ]
    }
  }
}

Ошибки авторизации

Возвращаются любым эндпоинтом Partner API.

Код	`error.code`	Сообщение	Причина
`401`	`partner_auth_failed`	Невалидный токен	Заголовок токена не разбирается — токен повреждён или обрезан
`401`	`partner_auth_failed`	Не указан kid	В заголовке токена отсутствует `kid`
`401`	`partner_auth_failed`	Невалидный токен	Заголовок `Authorization` отсутствует, неверная подпись или неверный `aud`
`401`	`partner_auth_failed`	Ключ не найден или деактивирован	Неизвестный `kid`, либо ключ или интеграция отключены
`401`	`partner_auth_failed`	Истёк срок действия токена	В токен добавлен `exp`, и он уже наступил
`429`	`partner_rate_limited`	Превышен лимит N запросов в минуту / в день	Превышен лимит запросов, см. ниже
`500`	`partner_key_broken`	Публичный ключ не задан. Обратитесь к администратору	Внутренняя ошибка конфигурации — свяжитесь с нами

Поле exp в токене Partner API не требуется. Если вы его добавите, мы будем его учитывать — токен перестанет работать после истечения срока.

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

На интеграцию действуют два лимита — число запросов в минуту и в сутки. Они общие для всех эндпоинтов Partner API и согласуются при подключении; суточного лимита может не быть. Суточный счётчик сбрасывается в полночь по московскому времени. Запрос сверх лимита отклоняется с 429 и кодом partner_rate_limited — повторите его позже. Публичные ключи виджета (/.well-known/jwks.json) отдаются без авторизации и лимитов.

Эндпоинты

Подписки

Список доступных пакетов и выдача подписки пользователю.

Доступы

Свои доступы: завести, выдать, отозвать, проверить.

Статистика

Активность, регистрации и продажи, доступы и профиль пользователей.

Согласие и профиль

Когда вы получаете имя, фото и email пользователя.

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

Авторизация

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

Виджет

Авторизация

Формат токена

Генерация токена

Формат ошибки

Ошибки авторизации

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

Эндпоинты

Подписки

Доступы

Статистика

Согласие и профиль