# Сервис работы с торговыми поручениями
<details>
<summary>Статусная модель заявок</summary>
<img src="/investAPI/img/order_status_diagram.png" width="650">
</details>
## Выставить заявку
Одна из главных функций торгового робота — выставление заявок на бирже.
Для этого можно использовать unary-метод [postOrder](/investAPI/orders#postorder).
Через него можно выставлять все типы заявок — и рыночные, и лимитные.
В запросе метода передаётся параметр `instrument_id` — идентификатор инструмента, который принимает значения `figi` или `instrument_uid`. [Подробнее об идентификаторах](/investAPI/faq_identification/).
[Подробнее о торговых поручениях, их видах и особенностях исполнения на биржах](/investAPI/faq_orders/)
<blockquote>
<p><strong>Важно</strong><br>
Чтобы исключить дублирование заявок, используется параметр <code>order_id</code> — его нужно сгенерировать любым удобным способом перед вызовом метода. Если сервис получит несколько запросов с одинаковым <code>order_id</code>, на биржу выставится только одно торговое поручение. Все последующие запросы с одним <code>order_id</code> будут возвращать ошибку выставления `30057`. </p>
</blockquote>
<blockquote>
<p><strong>Важно</strong><br>
Сейчас у нас есть два параметра с одинаковым названием:</p>
<ul>
<li><code>order_id</code> как входной параметр — ключ идемпотентности. Уникальность значений отслеживается только за последний месяц.</li>
<li><code>order_id</code> как выходной параметр — биржевой идентификатор заявки, который в дальнейшем используется для отслеживания статуса заявки. </li>
</ul></blockquote>
<a name="coupon"></a>
При выполнении операций с облигациями также учитывайте [накопленный купонный доход](/investAPI/glossary#coupon).
Размер НКД можно узнать через методы получения информации по облигациям или метод выставления торгового поручения — для этого используется параметр `aci_value`.
Обратите внимание: в параметре `aci_value` возвращается размер НКД в валюте расчётов за 1 лот. То есть при покупке облигаций к стоимости сделки будет добавлено произведение НКД на количество лотов в сделке (`aci_value`∗`quantity`), при продаже — сумма сделки будет уменьшена на это произведение.
Выставлять заявку с отрицательным значением цены можно только для фьючерсов — в остальных случаях метод вернёт ошибку.
>**Рекомендация**<br>
>Сейчас выставить заявку стоимостью больше 30 млн рублей через T-Invest API нелья — её нужно подтверждать по СМС. Поэтому мы рекомендуем разбивать такие заявки на заявки меньшего размера.
## Получить список активных заявок по счёту
Чтобы торговый робот более эффективно управлял торговыми поручениями, ему нужно иметь
возможность получать список активных заявок на данный момент.
Для этого можно использовать метод [getOrders](/investAPI/orders#getorders). Обратите внимание: метод
возвращает только активные торговые поручения — после исполнения заявка пропадает из возвращаемого списка.
## Получить статус торгового поручения
Статус исполнения поданного торгового поручения можно
используя метод [getOrderState](/investAPI/orders#getorderstate). Помимо статуса он возвращает стадии выполнения заявки — массив `stages`.
>**Важно**<br>
>Метод не предусмотрен для получения глубокой истории и может не возвращать информацию по поручениям, которым больше одного дня.
## Идентификатор ключа идемпотентности
**Пример**. Вы оформляете заявку на покупку ценной бумаги. Запрос может потеряться в пути, и вы пробуете отправить его ещё раз. Проблема в том, что мог потеряться не запрос, а ответ — и тогда будут созданы две заявки.
Поэтому для таких операций есть требование идемпотентности — это значит, что при повторном вызове операции результат будет тот же, что и при первом. В нашем примере — вне зависимости от того, сколько раз был отправлен запрос, должна быть создана только одна заявка или ни одной, если возникнет ошибка.
Стандартный способ достичь идемпотентности — генерация ключа идемпотентности на стороне клиента. Это некое уникальное значение: на стороне обработки запроса выполняется только та операция, ключ которой ещё не встречался. Таким образом можно делать повторные вызовы безопасно.
<blockquote>
<p><strong>Важно</strong><br>
Для сохранения единообразия параметр <code>order_id</code> означает:</p>
<ul>
<li>В запросах метода <a href="/investAPI/orders#postorder">postOrder</a> — ключ идемпотентности, передаваемый от клиента. </li>
<li>В ответах метода <a href="/investAPI/orders#postorder">postOrder</a> — биржевой идентификатор заявки. </li>
</ul>
<p>В ответах других методов ключ идемпотентности, который передаётся клиентом, — это параметр <code>order_request_id</code>. </p>
</blockquote>
В запросе метода [getOrderState](/investAPI/orders#getorderstate) в параметре `order_id` нужно передавать `order_id` из ответа метода [postOrder](/investAPI/orders#postorder) — то есть биржевой идентификатор заявки.
Повторное использование одного и того же `order_id` в запросах метода [postOrder](/investAPI/orders#postorder) приведёт к ошибке, если уже существует успешно размещённая заявка с таким `order_id`.
## Отменить торговое поручение
Не все торговые поручения, которые выставляются на торговую площадку, могут и должны быть исполнены.
Ситуация на рынке меняется динамично, поэтому торговому роботу нужна возможность отменять
выставленные заявки — для этого используйте метод [cancelOrder](/investAPI/orders#cancelorder).
## Стрим исполнения поручений пользователя
T-Invest API предоставляет стрим с трансляцией исполнения сделок. В этот стрим попадают все
совершённые сделки по всем счетам пользователя.
Чтобы сохранять стабильное подключение при отсутствии данных в stream-соединении, сервер периодически
отправляет ping-пакет. Клиенту не нужно на него реагировать.
## Изменить выставленную заявку
Чтобы изменять уже выставленные поручения, используйте метод [replaceOrder](/investAPI/orders#replaceorder).
Через него можно отменить существующую выставленную заявку и выставить новую с изменёнными параметрами.
Чтобы использовать метод, понадобится идентификатор заявки на бирже, который вы получили при выставлении заявки через метод [postOrder](/investAPI/orders#postorder).
Во время использования метода на этапах исполнения могут произойти разные события, и вернётся ошибка. Например:
- Если поручение нельзя отменить, вернётся ошибка с кодом `30059` и описанием причины в `message`.
- Если после отмены поручения нельзя выставить новое, вернётся ошибка метода [postOrder](/investAPI/orders#postorder) с соответствующим кодом и описанием.
[Все коды и описания ошибок](/investAPI/errors)
### Стрим совершённых сделок пользователя
В T-Invest API есть gRPC server-side [TradesStream](https://russianinvestments.github.io/investAPI/orders/#tradesstream) получения сделок с биржи.
Стрим предназначен для получения событий по поручениям пользователя по факту их исполнения.
TradesStream используется для быстрого получения информации об исполнении поручения и выполненных сделках в рамках поручения с отображением номера счёта, на котором выполнилось поручение.
Для работы со стрим-соединениями есть [ограничения](/investAPI/limits).
### Получить торговые статусы инструментов и расписание торгов
[Торговые статусы инструментов и расписание торгов](https://russianinvestments.github.io/investAPI/faq_trading_status/)
Также рекомендуем смотреть актуальную информацию по режимам и статусам торгов на сайтах [Московской биржи](https://www.moex.com/) и [СПБ биржи](https://spbexchange.ru/).
### Выставить заявки по опционам
Сейчас для работы с опционами в T-Invest API доступны только лимитные заявки.
Рыночная заявка, тейк-профиты и стоп-заявки в разработке.