Управление заявками

Взаимодействие с торговой системой в рамках непосредственного ведения торгов сводится к трём основным действиям:

Создание заявки — для размещения своего предложения о покупке или продаже финансового инструмента
Изменение заявки — для редактирования условий выставленного предложения
Снятие заявки — для отзыва ранее выставленного предложения, если оно не было удовлетворено

Передача команд на выполнение этих действий возможна как в рамках отдельных множественных соединений, устанавливаемых при отправке запросов к HTTP API, так и в рамках единого WebSocket-соединения с интерфейсом управления заявками.

Ниже описаны основные особенности управления заявками через WebSocket API.

Интерфейсы

Для управления заявками в торговой системе АЛОР Брокер в рамках единого соединения используется WebSocket-интерфейс /cws. В зависимости от используемого контура системы, полный путь к интерфейсу будет различаться:

Адрес	Контур
`wss://api.alor.ru/cws`	Боевой контур системы. Для использования требуется действующий торговый аккаунт
`wss://apidev.alor.ru/cws`	Тестовый контур системы. Для использования требуется тестовый торговый аккаунт

Обратите внимание!

Для обеспечения безопасности передаваемых данных сервер принимает запросы только по протоколу WebSocket Secure (wss). Попытка подключения по незащищённому протоколу WebSocket (ws) будет отклонена сервером с ответом 406 Not Acceptable.

Формирование запроса

Независимо от того, с каким типом заявки ведётся работа и какое действие выполняется, отправляемый запрос всегда должен соответствовать следующим характеристикам:

Выполняется авторизованным пользователем
Указывает на определённый тип операции
Имеет уникальный идентификатор для отделения от других запросов

Для соблюдения этих требований тело сообщения для каждого поддерживаемого запроса должно содержать заполненные обязательные параметры token, opcode и guid.

Ниже описаны детали применения этих параметров.

Авторизация

Все операции, выполняемые с помощью WebSocket API, требуют обязательную авторизацию для подтверждения личности пользователя API и наличия у него прав на выполнение запрашиваемых действий.В качестве подтверждения используется Access Токен пользователя API, передаваемый серверу в качестве значения параметра token.

При этом, в отличии от запросов для управления подписками, при взаимодействии с интерфейсом /сws авторизация выполняется самостоятельным запросом, применяется к всему WebSocket-соединению и распространяется на все выполняемые в нём запросы.

Для авторизации WebSocket-соединения отправьте запрос с кодом операции authorize в параметре opcode и вашим Access Токеном в параметре token.

Пример тела запроса на авторизацию

{
  "opcode": "authorize",
  "guid": "f35a2373-612c-4518-54af-72025384f59b",
  "token": "eyJhbGciOiJ..."
}

При успешной авторизации в ответ сервер однократно передаст сообщение с кодом 200, подтверждающее авторизацию соединения.

Пример тела ответа, подтверждающего авторизацию соединения

200. Запрос успешно обработан
{
  "requestGuid": "f35a2373-612c-4518-54af-72025384f59b",
  "httpCode": 200,
  "message": "The connection has been initialized."
}

После чего все последующие сообщения, отправленные в рамках этого WebSocket-соединения, будут считаться авторизованными до закрытия соединения или истечения срока действия Access Токена.

Важно!

Система выполняет проверку актуальности токена только при получении клиентских сообщений. Проверка токена при отсутствии сообщений не предусмотрена. Это означает, что система не информирует об истечении срока действия токена, использовавшегося для авторизации соединения, и за этим пользователю необходимо следить самостоятельно.

Срок действия Access токена составляет 30 минут с момента создания. Рекомендуем периодически обновлять авторизацию соединения повторной отправкой запроса на авторизацию, содержащего новый токен. Период обновления рекомендуется установить на несколько минут меньше срока действия токена.

примечание

WebSocket-соединения изолированы друг от друга, в связи с чем авторизация распространяется только на то соединение, в рамках которого был выполнен запрос.

В случае неудачной попытки авторизации (Например, из-за указания недействительного Access токена) в WebSocket-соединение будет возвращён ответ с соответствующим ошибке кодом, после чего соединение будет разорвано сервером.

Пример тела сообщения, содержащего отказ в авторизации

401. Некорректный JWT токен
{
	"requestGuid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
	"httpCode": 401,
	"message": "Invalid JWT token!"
}

Резюме

Для выполнения запросов требуется авторизация
Авторизация применяется к WebSocket-соединению, распространяясь на все запросы, выполняемые в рамках него
Авторизация каждого WebSocket-соединения выполняется отдельно
Для авторизации используется отдельный запрос с кодом операции authorize и заполненным параметром token, в качестве значения которого должен использоваться Access Токен, действительный как для выбранного контура системы, так и для времени выполнения запроса
WebSocket-соединение остаётся авторизованным до тех пор, пока не будет разорвано или не истечёт срок действия использованного Access Токена
Неудачная попытка авторизации или выполнение других запросов в неавторизованном соединении разрывает установленное WebSocket-соединение

Идентификация

В рамках одного авторизованного WebSocket-соединения пользователю API доступна возможность отправки неограниченного количества запросов на создание, изменение и удаление заявок. При этом, во избежание дублирования запросов на выполнение запрашиваемых действий, каждый запрос должен содержать уникальный идентификатор операции, передаваемый серверу в параметре guid.

подсказка

Параметр guid присваивается запросу пользователем API, а не сервером. Предусмотрите механизм генерации значений для данного параметра в используемом ПО.

В качестве значения параметра guid сервер принимает любое произвольное строковое значение, уникальное для установленного WebSocket-соединения. С равным успехом значением данного параметра могут быть следующие комбинации символов:

123456
abcdefABCDEF
!@№;%:?*()-_=+/|"'
c328fcf1-e495-408a-a0ed-e20f95d6b813
Client-31075-Delete-StopLimit-185117

Таким образом, в зависимости от задачи, guid запроса может содержать как случайно сгенерированное, так и персонализированное значение. При этом для значения действует ограничение по длине — не более 50 символов.

Экранирование спецсимволов

При использовании спецсимволов в составе идентификатора убедитесь в сохранении целостности отправляемого JSON объекта. Символы, нарушающие синтаксис, должны быть исключены из комбинации или экранированы с помощью символа \. При этом экранирующий символ не учитывается как часть идентификатора, в связи с чем, например, значение /|\" будет интерпретировано системой как /|".

Каждое WebSocket-соединение изолировано от остальных, в связи с чем одно и то же значение параметра guid может использоваться в нескольких запросах, если они созданы в разных соединениях.

В отличии от запросов на создание подписок, при управлении заявками каждый запрос в рамках установленного WebSocket-соединения должен обладать уникальным значением параметра guid независимо от типа выполняемой операции. Так, например, запросы на авторизацию, создание рыночной заявки и её удаление, выполняемые в рамках одного соединения, потребуют три разных значения параметра guid. При получении сообщения с неуникальным значением сервер отклонит запрос с кодом ответа 400 и сообщением Request with such Guid was already handled, после чего разорвёт соединение.

Резюме

Одно WebSocket-соединение поддерживает возможность выполнения множества одновременно обрабатываемых запросов
Каждый запрос должен содержать заполненный параметр guid
Ответные сообщения от сервера содержат то же значение guid, которое было передано пользователем в запросе
Параметр guid заполняется пользователем API
Значение параметра может быть произвольным, но не длиннее 50 символов
Спецсимволы, нарушающие целостность JSON объекта, должны быть экранированы или исключены
Значение параметра должно быть уникальным для используемого WebSocket-соединения. Уникальным считается значение, не использовавшееся в запросах с момента установления соединения
Одинаковое значение параметра guid может применяться без последствий в разных WebSocket-соединениях
Использование неуникального значения при отправке команды вызовет отказ в обработке полученного запроса с последующим разрывом соединения

Выбор операции

При работе с HTTP API все действия пользователя определяются заданным в качестве пути URL ресурса и HTTP-глаголом, указывающим на метод взаимодействия (GET, PUT, POST, DELETE). В случае с WebSocket API метод взаимодействия определяется кодом операции, передаваемым в рамках WebSocket-соединения клиентском сообщении.

Как и в случае с HTTP-глаголами, коды операции строго определены и не допускают изменений в формулировке или написании. Разница заключается в том, что HTTP-глаголы определены общепринятым стандартом RFC 9110, тогда как для WebSocket API коды операций определяются выбранным создателями системы способом реализации метода.

Точное значение кода для каждой из операций представлено на странице описания соответствующего запроса.

Пример

Для создания рыночной заявки используется код операции create:market. Для успешного выполнения запроса данный код должен передаваться системе в неизменном виде.

Такие варианты, как Create:Market, createmarket, market:create или create:marketorder, будут отклонены системой как неизвестные операции.

Выполнение запроса

Управление биржевыми заявками производится отправкой в установленное WebSocket-соединение сообщения, содержащего в теле код исполняемой операции (opcode), уникальный идентификатор (guid) и дополнительные параметры, определяющие детали заявки.

Пример тела запроса на создание лимитной заявки:

{
  "opcode": "create:limit",
  "guid": "c328fcf1-e495-408a-a0ed-e20f95d6b813",
  "side": "buy",
  "quantity": 1,
  "price": 142.52,
  "instrument": {
    "symbol": "SBER",
    "exchange": "MOEX"
  },
  "comment": "Первая заявка",
  "board": "TQBR",
  "user": {
    "portfolio": "D39004"
  },
  "timeInForce": "OneDay",
  "icebergFixed": 100,
  "icebergVariance": 2,
  "checkDuplicates": true
}

Где:

opcode — Код выполняемой операции
guid — Уникальный пользовательский идентификатор заявки
side — Направление сделки
quantity — Количество лотов финансового инструмента
price — Стоимость лота, по которой должна быть заключена сделка
symbol — Код финансового инструмента (Тикер)
exchange — Биржа
comment — Пользовательский комментарий к заявке
board — Код режима торгов
portfolio — Идентификатор клиентского портфеля, от имени которого выставлена заявка
timeInForce — Тип заявки
icebergFixed — Видимая постоянная часть айсберг-заявки в лотах
icebergVariance — Амплитуда отклонения (в % от icebergFixed) случайной надбавки к видимой части айсберг-заявки
checkDuplicates — Флаг, отвечающий за проверку уникальности команд

примечание

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

Особенности и ограничения

При работе с WebSocket API необходимо учитывать ряд ограничений и условий отправки запросов, налагаемых системой.

Ограничение	Рекомендация
Большое количество активных WebSocket-соединений негативно сказывается на стабильности работы системы. Действия, наносящие вред системе, могут привести ко временной блокировке пользователя, допустившего такое поведение.	Используйте одно соединение для отправки всех сообщений, связанных с управлением заявками, или воспользуйтесь ресурсами HTTP API, если интенсивность торгов низкая.

Ограничение

Рекомендация

Большое количество активных WebSocket-соединений негативно сказывается на стабильности работы системы. Действия, наносящие вред системе, могут привести ко временной блокировке пользователя, допустившего такое поведение.

Используйте одно соединение для отправки всех сообщений, связанных с управлением заявками, или воспользуйтесь ресурсами HTTP API, если интенсивность торгов низкая.

Интерфейсы​

Формирование запроса​

Авторизация​

Идентификация​

Выбор операции​

Выполнение запроса​

Особенности и ограничения​