РусскийПользовательский APIАвторизация и соглашения

Авторизация и соглашения

Эта страница описывает соглашения, на которые опираются все остальные разделы API: как авторизоваться, как устроен формат ответа и какие системные ошибки может вернуть любой эндпоинт.

Авторизация

Запрос можно авторизовать двумя способами; оба приводятся к одному и тому же пользователю и проходят одинаковую проверку блокировки.

API-ключ (скрипты, рекомендуется)

Ваш постоянный API-ключ находится в Профиль → API-ключ. Формат: {user_id}-{user_api}, например 42-d3adb33f….

Передавайте его как query-параметр id — это работает на всех эндпоинтах, включая POST (query-строка читается всегда, даже когда тело запроса — JSON):

curl "https://my.altercpa.top/api/profile/info.json?id=42-d3adb33f…"

Или в заголовке Authorization как Bearer-токен (тогда передаётся только сам ключ, без {user_id}-):

curl -H "Authorization: Bearer d3adb33f…" \
     "https://my.altercpa.top/api/profile/info.json"

Когда параметр id имеет вид {user_id}-{user_api}, он трактуется только как API-ключ, и user_id обязан совпадать с владельцем ключа — иначе вернётся ошибка key. Если id не похож на {user_id}-{user_api} (например, это идентификатор ресурса), он для авторизации игнорируется, и применяется Bearer-токен из заголовка.

API-ключ не имеет срока действия. Его можно обновить в Профиле или через profile/apikey; старый ключ перестаёт работать немедленно.

Дашборд входит через Telegram и использует собственный короткоживущий сессионный токен; для программного доступа используйте API-ключ выше.

Соглашения

  • GET для чтения, POST для записи. Без исключений.

  • Каждый ответ — HTTP 200 с Content-Type: application/json, независимо от результата. Проверяйте поле status, а не HTTP-код.

  • Успешный ответ почти всегда плоский: поля лежат на верхнем уровне рядом с "status": "ok".

    { "status": "ok", "id": 42, "api_key": "42-d3adb33f…" }

  • Часть эндпоинтов (как правило, списки) оборачивают полезную нагрузку в ключ data:

    { "status": "ok", "data": [ … ] }

    Какой формат у конкретного эндпоинта — указано в его примере ответа.

  • Ошибка всегда плоская:

    { "status": "error", "error": "code" }

  • Метки времени в ответах — это целые числа (Unix-секунды); 0 означает, что значение не задано.

  • Эндпоинты оканчиваются на .json (например profile/info.json).

  • Тело POST-запросов может быть JSON (Content-Type: application/json) или form-encoded (application/x-www-form-urlencoded). При JSON-теле его значения имеют приоритет над одноимёнными query-параметрами. Размер тела ограничен 1 МиБ (кроме загрузки файлов — там действует отдельный лимит).

  • Параметр ?id= для авторизации всегда передаётся в строке запроса (query string), даже для POST-эндпоинтов.

Системные ошибки

Эти ошибки может вернуть любой авторизуемый эндпоинт.

ОшибкаЗначение
keyОтсутствует или недействительный API-ключ
accessАвторизация прошла, но ресурс вам не принадлежит или не существует
banАккаунт заблокирован
funcНеизвестный путь эндпоинта или неверный метод
dbОшибка базы данных — повторите попытку; если проблема сохраняется, обратитесь в поддержку
unpaidПодписка истекла и льготный период завершился
limitПревышен тарифный или квотный лимит

Ошибки, специфичные для конкретных эндпоинтов (exists, token, webhook, unreachable, …), описаны на соответствующих страницах.

Льготный период: когда подписка истекает, публичный API продолжает работать ещё некоторое время — льготное окно (сейчас 7 дней, но оператор может изменить этот срок); после его окончания авторизуемые продуктовые эндпоинты возвращают unpaid. Эндпоинты входа, профиля и оплаты при этом работают всегда, чтобы истёкший аккаунт мог войти, проверить статус и продлить подписку. Полные правила перехода — в разделе Оплата и тарифы.

Обзор APIПрофиль и трекер