Справочник API

Подключение аккаунта

Обновить состояние runtime

Синхронизирует актуальное состояние runtime провайдера для аккаунта. runtime_status принимает одно из стандартных значений платформы: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error. Специфичные для провайдера метки предварительно нормализуются к этому набору.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/runtime/refresh

Перед вызовом

Используйте X-Api-Key нужного рабочего пространства на сервере. Перед запуском замените все заполнители.

Завершите авторизацию и проверьте runtime_status. Авторизация и соединение — разные состояния; HTTP-успех не доказывает готовность.

Откуда взять параметры
account_id
Возьмите data.id из создания или запроса аккаунта. Идентификатор относится к рабочему пространству X-Api-Key. Получить аккаунт

Параметры запроса

Заголовки

X-Api-Key
stringобязательно

API-ключ рабочей области. Рабочая область определяется по этому заголовку.

Content-Type
stringобязательно

Используйте application/json при отправке JSON-тела запроса.

Параметры пути

account_id
stringобязательно

Идентификатор для маршрута раздела runtime.

Тело запроса

Этот эндпоинт принимает пустой JSON-объект; отправьте {} как в примере запроса.

Как понять результат

Проверьте runtime_status: starting/reconnecting требуют повторной проверки. При auth_required=true продолжите авторизацию. Отсутствие флага не доказывает подключение.

Ответ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "runtime_status": "running"
  }
}

Тело ответа

account_id
string

Аккаунт провайдера, к которому относится этот ответ.

provider
string

Идентификатор канала. Используйте значение API без изменений; возвращаемые этим API значения указаны в enum ниже.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

action
string

Запрошенное действие runtime.

enum: refresh_status, start, stop, reconnect

operation_status
string

Статус принятия или завершения действия runtime.

runtime_status
string

Нормализованное состояние runtime: одно из unknown, starting, running, stopping, stopped, reconnecting, disconnected или error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

runtime_error
string

Ошибка runtime провайдера, если действие не удалось завершить.

auth_required
boolean

При true продолжите авторизацию канала. Подсказка возвращается только при наличии данных авторизации от канала или ранее подтверждённого незавершённого процесса. Отсутствие поля или false не означает подключение: проверьте runtime_status. Одного disconnected недостаточно для вывода о необходимости повторной авторизации. Runtime API не возвращает code, qrcode, auth_payload или provider_data; получите данные через API авторизации канала.

auth_status
string

Необязательный статус авторизации: например pending, awaiting_qr_scan или passkey_required. Возвращается при наличии данных авторизации или подтверждённого незавершённого процесса. Следуйте руководству канала; полный статус и данные доступны в API авторизации, а состояние подключения — в runtime_status.

Ответы

200

200 OK

Запрос выполнен. См. пример тела ответа.

400

Bad Request

Тело запроса, путь или параметры некорректны.

401

Unauthorized

Заголовок X-Api-Key отсутствует или недействителен.

409

Conflict

Запрошенная операция конфликтует с существующим аккаунтом провайдера или ресурсом.

500

Internal Server Error

Сервис столкнулся с неожиданной ошибкой.

502

Bad Gateway

Адаптер или вышестоящий провайдер не смог завершить операцию.

При ошибке запроса

Проверьте HTTP и error.code/numeric_code, сохраните request_id. Исправьте параметры, завершите авторизацию или проверьте runtime. До повторной отправки или записи выясните результат предыдущей попытки. Справочник ошибок

invalid_request · 10000 · 400
Проверьте обязательные поля, форматы и условия канала, затем исправьте запрос.
invalid_api_key · 11001 · 401
Проверьте X-Api-Key и активность рабочего пространства.
provider_not_ready · 30009 · 409
Восстановите авторизацию и соединение, выясните предыдущий результат перед повтором.