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

Возможности и текущие ограничения

Публичный Base URL: https://new.rootactivation.ru/api/partner/v1. Локальная mock-среда запускается отдельно по адресу http://127.0.0.1:8765/api/partner/v1; её синтетические коды не предназначены для production.

Партнёр может проверять код, предварительно проверить аккаунт, запустить разрешённую активацию и читать свои операции. Вызов запуска возвращает оболочку {"operation": ...}, а выполнение продолжается в фоне. Для обновления состояния вызывайте POST /status с тем же кодом.

Проверка не запускает активацию. canActivate учитывает точный результат проверки, известный продукт, доступность провайдера и разрешение партнёра. Поддерживаемый VIP probe может выбрать тип chatgpt_account_id или chatgpt_session_json; передавайте сессию и путь аккаунта, указанные в ответе.

Успех подтверждается только распознанным ответом конкретного поставщика: Dorin activation.completed или проверкой статуса исходного кода used; ByPrice — completed для GPT или done для Grok на ожидаемом заказе; VIP — подтверждённый статус успеха на ожидаемом idempotency key/заказе; Gpay — совпадающий заказ с status=completed и terminal=true. Неизвестный ответ, review и истёкшее локальное ожидание не подтверждают подписку. Claude пока не поддерживается: для него нужна отдельная настройка учётных данных.

Маршруты, авторизованные ключом партнёра, показывают только операции этого партнёра. Если такой маршрут отклоняет код из-за чужого закрепления, ответ — общий 404 code_not_found, не раскрывающий владельца или наличие операции. Ошибки неизвестного или некорректного кода зависят от проверки и не обязаны иметь тот же статус. Клиентский API остаётся доступен по коду: покупатель, уже знающий код, может проверить его результат по обычному клиентскому сценарию.

Доступ и управление ключами

Администратор создаёт партнёра в панели. Полный ключ API показывается только при создании или ротации. Сервер хранит SHA-256-дайджест и последние четыре символа для подсказки; повторно показать полный ключ нельзя. Храните секрет на сервере интеграции и не передавайте его в браузер, URL, журнал или репозиторий. Управление партнёром и его ключом выполняет администратор; отдельного партнёрского API для этого или настройки поставщиков нет.

Все шесть маршрутов требуют заголовок:

Authorization: Bearer <PARTNER_API_KEY>
Accept: application/json

Для POST-запроса добавьте Content-Type: application/json; charset=utf-8. Cookie администратора не заменяет Bearer-ключ. Ключ партнёра не открывает панель администратора и не даёт доступа к секретам поставщиков.

Общие правила запросов

• Успешный вызов возвращает HTTP 200 и JSON. Ошибка использует оболочку {"error":{"code":"...","message":"..."}}.
• POST принимает JSON-объект только с полями маршрута; лишние поля отклоняются с 400 invalid_request. POST query-параметры не поддерживает. Передавайте код в теле, не в URL.
• session — строка, внутри которой находится JSON-сессия, принятая существующим клиентским потоком для этого кода. Передавайте её как JSON-строку, а не вложенный объект. Общий предел — 32 768 символов; сценарий поставщика может ограничивать её сильнее.
• Максимальный размер HTTP-тела — 64 КиБ. Формат сессии и её более строгие пределы зависят от поставщика. Синтетические сессии и mock-сценарии доступны только в локальной среде.
• Лимит партнёра действует на все маршруты в общем скользящем 60-секундном окне. Он задаётся администратором в requestsPerMinute (по умолчанию 60, диапазон 1–600). При превышении API возвращает 429 rate_limited. Проверки также могут иметь отдельный лимит поставщика и вернуть 429 check_rate_limited.
• Production-запросы должны идти по HTTPS на new.rootactivation.ru. Сервер-серверный клиент может опустить Origin; если он передан, используйте origin https://new.rootactivation.ru. Локальный mock-клиент обращается только к loopback адресу http://127.0.0.1:8765.
• Cookie запрещены на маршрутах партнёра (400 bearer_only). Сырая сессия обрабатывается во время вызова; она не возвращается, не записывается в партнёрский журнал и не попадает в HTTP-логи. Для восстановления операции сервис может сохранять маскированный ID/email и данные, нужные рабочему процессу.

Маршруты

{
  "apiVersion": "v1",
  "activationEnabled": true,
  "pollIntervalMs": 1500
}

{"code":"<CODE>"}

{
  "product": "ChatGPT Plus",
  "codeStatus": "available",
  "canActivate": true,
  "instruction": "Для реальной активации введите код и проверьте нужный аккаунт.",
  "accountField": "user.id",
  "operation": null,
  "checkedAt": "2026-10-11T10:00:00Z"
}

{"code":"<CODE>","session":"<JSON_SESSION_STRING>"}

{
  "product": "ChatGPT Plus",
  "account": {
    "email": "demo@example.invalid",
    "maskedId": "dem••••123",
    "idType": "user.id",
    "source": "customer"
  }
}

{"code":"<CODE>","session":"<JSON_SESSION_STRING>"}

{
  "operation": {
    "id": "op_<32 lowercase hex characters>",
    "product": "ChatGPT Plus",
    "state": "queued",
    "codeStatus": "processing",
    "executionMode": "mock",
    "createdAt": "2026-10-11T10:00:00Z",
    "updatedAt": "2026-10-11T10:00:00Z",
    "lastCheckedAt": "2026-10-11T10:00:00Z",
    "account": {
      "email": "demo@example.invalid",
      "maskedId": "dem••••123",
      "idType": "user.id",
      "source": "customer"
    },
    "publicCode": null,
    "message": "Тестовый запрос принят и ожидает обработки.",
    "events": [
      {"at":"2026-10-11T10:00:00Z","state":"queued","label":"Тестовый запрос принят в очередь"}
    ]
  }
}

{"code":"<CODE>"}

{
  "items": [
    {
      "id": "op_<32 lowercase hex characters>",
      "product": "ChatGPT Plus",
      "state": "running",
      "codeStatus": "processing",
      "executionMode": "mock",
      "createdAt": "2026-10-11T10:00:00Z",
      "updatedAt": "2026-10-11T10:00:02Z",
      "lastCheckedAt": "2026-10-11T10:00:02Z",
      "account": {"email":"demo@example.invalid","maskedId":"dem••••123","idType":"user.id","source":"customer"},
      "publicCode": null,
      "message": "Выполняется локальная тестовая операция.",
      "events": [
        {"at":"2026-10-11T10:00:00Z","state":"queued","label":"Тестовый запрос принят в очередь"},
        {"at":"2026-10-11T10:00:02Z","state":"running","label":"Локальная тестовая операция началась"}
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

Поля ответов

Ответ проверки похож на клиентский API. В партнёрском ответе могут присутствовать дополнительные поля проверки поставщика; этот список описывает основные стабильные поля и не является закрытым перечнем.

Для preview и activate поле session — строка с сериализованным JSON. Например, тело запроса для синтетического ChatGPT-кода (вложенные кавычки экранированы, секретов здесь нет):

{"code":"TEST-success-012345ABCDEF","session":"{\"status\":\"authenticated\",\"user\":{\"id\":\"synthetic-chatgpt-user-123456\",\"email\":\"chatgpt@example.invalid\"}}"}

Для Grok текущий формат использует вложенное session.userId; в этом примере код должен соответствовать локальному Grok-сценарию:

{"code":"TEST-grok-012345ABCDEF","session":"{\"status\":\"authenticated\",\"session\":{\"userId\":\"synthetic-grok-user-123456\",\"email\":\"grok@example.invalid\"}}"}

Отправляйте сессию только по защищённому каналу в теле запроса. Не подставляйте в документацию, тесты или журналы реальные пользовательские сессии.

Состояния и опрос

Типичный путь: queued → running → succeeded или queued → running → failed. Сценарии поставщика могут включать reconciling или review. succeeded и failed — терминальные состояния этой операции; новые версии могут добавлять промежуточные состояния, поэтому неизвестное состояние не должно ломать клиент.

После запуска опрашивайте POST /status с тем же кодом с рекомендуемым интервалом из /config — сейчас 1500 мс. Состояние сохраняется сервером и может оставаться прежним между запросами. Опрос API не управляет частотой внутренних запросов к поставщику.

Операция не возвращает исходный код. Партнёру следует хранить код у себя с соответствующими мерами защиты. Ответы партнёра исключают внутренние идентификаторы заказов и статусы поставщиков.

Ошибки и восстановление

Все ошибки используют оболочку:

{"error":{"code":"invalid_partner_key","message":"Проверьте ключ партнёра."}}

Клиенту следует ветвиться по HTTP-коду и error.code. Текст message можно показать пользователю, но не использовать как машинный идентификатор.

Предварительная проверка Gpay

Для реального Gpay код и аккаунт должны пройти предварительную проверку до запуска; после preview используйте тот же аккаунт и ту же сессию в activate. Предварительная проверка действует пять минут.

Повторяйте запуск только при однозначном ответе, что он не был принят. Если соединение оборвалось после отправки /activate, опрашивайте тот же код и не отправляйте новый запуск автоматически.

Локальная mock-проверка (опционально)

Этот пример обращается только к локальному серверу 127.0.0.1:8765, а не к production API. Тестовые коды и sample session недоступны на публичном сервере.

1. Запустите приложение и создайте партнёра в панели администратора. Сохраните ключ на сервере интеграции, включите партнёра и разрешите ему запуск теста (allowActivation).
2. В клиентском интерфейсе откройте Тестовые сценарии и создайте код для сценария «Успешная активация». Он имеет вид TEST-success-<12 заглавных hex-символов>. Это локальная имитация; она не отправляет заказ поставщику и не оформляет подписку.
3. Установите переменные окружения PARTNER_API_KEY и TEST_CODE. Пример ниже прекращает работу до первого сетевого запроса, если код не соответствует точному формату этого тестового сценария.

Пример Python 3 с urllib выполняет полный mock-путь: /config → /check → /preview → один вызов /activate → опрос /status. Для ChatGPT тестовая сессия использует только синтетические значения:

import json
import os
import re
import time
import urllib.error
import urllib.request

BASE = "http://127.0.0.1:8765/api/partner/v1"
API_KEY = os.environ["PARTNER_API_KEY"]
TEST_CODE = os.environ["TEST_CODE"]
# Fail closed before sending any request; never substitute a real code.
if not re.fullmatch(r"TEST-success-[A-F0-9]{12}", TEST_CODE):
    raise SystemExit("TEST_CODE must be a locally generated TEST-success code")

HEADERS = {"Authorization": f"Bearer {API_KEY}", "Accept": "application/json"}
SESSION = json.dumps({
    "status": "authenticated",
    "user": {"id": "synthetic-chatgpt-user-123456", "email": "chatgpt@example.invalid"},
})

def call(method, path, payload=None):
    data = None if payload is None else json.dumps(payload).encode("utf-8")
    headers = dict(HEADERS)
    if data is not None:
        headers["Content-Type"] = "application/json; charset=utf-8"
    request = urllib.request.Request(BASE + path, data=data, headers=headers, method=method)
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return response.status, json.load(response)
    except urllib.error.HTTPError as error:
        return error.code, json.load(error)

def require_ok(result):
    status, body = result
    if status != 200:
        raise RuntimeError(f"HTTP {status}: {body}")
    return body

config = require_ok(call("GET", "/config"))
if not config["activationEnabled"]:
    raise SystemExit("Enable this partner's test activation in local admin first")
checked = require_ok(call("POST", "/check", {"code": TEST_CODE}))
if checked.get("codeStatus") != "available" or not checked.get("canActivate"):
    raise SystemExit("The generated mock code is not available for this partner")
require_ok(call("POST", "/preview", {"code": TEST_CODE, "session": SESSION}))

# Send activate once only. If the connection times out, recover by polling status;
# do not send a second activate request.
try:
    launch = require_ok(call("POST", "/activate", {"code": TEST_CODE, "session": SESSION}))
    print("Accepted:", launch["operation"].get("state"))
except (TimeoutError, urllib.error.URLError) as error:
    print("Launch response was ambiguous; polling the same test code:", error)

terminal = {"succeeded", "failed"}
deadline = time.monotonic() + 30
while time.monotonic() < deadline:
    status = require_ok(call("POST", "/status", {"code": TEST_CODE}))
    operation = status.get("operation")
    if operation:
        print("Current state:", operation.get("state"))
        if operation.get("state") in terminal:
            break
    time.sleep(config["pollIntervalMs"] / 1000)
else:
    print("Still unresolved; inspect GET /operations?page=1. Do not launch again.")

Активация в этом примере строго ограничена синтетическим TEST-success-… кодом и выполняется ровно один раз. Для Grok используйте отдельный синтетический TEST-grok-… код и строку сессии с session.userId, показанную выше. Не передавайте реальные коды, пользовательские сессии или GPAY-…. Партнёрский API не создаёт тест-коды и не выдаёт список сценариев; тесты не должны обращаться к внешним API.

Совместимость и эксплуатация

apiVersion обозначает контракт v1. Клиент должен игнорировать неизвестные поля, учитывать operation: null и не полагаться на наличие email или publicCode. Даты — ISO 8601 UTC с суффиксом Z. Элементы /operations используют ту же очищенную схему операции, что и ответ запуска. Партнёрские ответы содержат только нормализованные поля этого документа и не раскрывают сырые ответы поставщиков или секреты.