Асинхронный сервис активации подписки: пришлите токен сессии — получите job_id — опрашивайте статус до терминала.
Все эндпоинты, кроме /ping, требуют заголовок X-Api-Key. Ключ выдаётся администратором и привязан к вашим задачам — чужие задачи по своему ключу вы не увидите.
curl -H "X-Api-Key: gpta_..." https://HOST/api/v1/plans
Ошибки — JSON {"error": "код"}, иногда с доп. полями (retry_after, allowed). HTTP-код всегда соответствует смыслу (400/401/404/413/429/502/503).
| Код | Значение |
|---|---|
| 401 unauthorized | нет/неверный X-Api-Key |
| 429 rate_limited | превышен лимит запросов, смотрите retry_after (сек) |
| 429 cooldown | этот же токен уже отправляли недавно |
| 429 busy | очередь активаций полна, повторите позже |
| 429 ip_blocked | IP временно заблокирован (подбор ключей) |
| 503 maintenance | сервис на паузе, попробуйте позже |
Проверка доступности, без авторизации.
{"ok": true, "time": 1758000000}
Какие тарифы сейчас можно активировать.
{"plans": [{"plan": "plus", "available": true}]}
Запуск активации. Возвращает сразу, работа идёт в фоне.
curl -X POST https://HOST/api/v1/activate \
-H "X-Api-Key: gpta_..." -H "Content-Type: application/json" \
-d '{"session_token": "...", "plan": "plus", "order_ref": "123"}'
→ 202 {"job_id": "a1b2c3d4e5f6", "status": "queued"}
Повторная отправка того же session_token, пока задача ещё не завершилась, вернёт тот же job_id вместо новой задачи (200, не 202). Сразу после завершения действует короткий кулдаун на этот же токен. order_ref — необязательный номер вашего заказа, попадёт в журнал активаций на нашей стороне.
Активация по одноразовому коду (CDK) вместо API-ключа — без авторизации, код сам по себе является допуском. Один код можно попробовать активировать повторно, если предыдущая попытка не списала его (см. статусы ниже).
curl -X POST https://HOST/api/v1/redeem \
-H "Content-Type: application/json" \
-d '{"code": "GP-XXXXX-XXXXX", "session_token": "..."}'
→ 202 {"job_id": "a1b2c3d4e5f6", "status": "queued"}
Тариф берётся из самого кода, указывать plan не нужно. Неверный/уже использованный/деактивированный код → 404 {"error":"invalid_code"}. Дальше — тот же GET /api/v1/jobs/{job_id}, что и у /activate.
Статус задачи. Опрашивайте раз в 5–10 секунд до терминального статуса.
| status | терминальный? | что значит |
|---|---|---|
| queued / running | нет | идёт обработка |
| success | да | подписка активирована, есть order_id |
| client_fault | да | проблема на стороне клиента — message уже готов для показа пользователю |
| hold | да | на ручной проверке — не наша вина и не клиента, разбирает оператор |
| error | да | внутренняя ошибка сервиса |
{
"job_id": "a1b2c3d4e5f6", "plan": "plus", "status": "success",
"attempts": 1, "email": "a***@gmail.com",
"order_id": "10234", "message": "Подписка активирована",
"created_at": 1758000000, "updated_at": 1758000090
}
Активация — дорогая операция (минуты, реальные деньги на карте), лимитирована жёстче остальных вызовов. При 429 подождите retry_after секунд перед повтором, не ретраить чаще.