Перейти к содержанию

gRPC

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

Вся работа с Tinkoff Invest API ведётся по протоколу gRPC.

Документация gRPC

Одна из ключевых особенностей протокола — bidirectional streaming. Это особый режим работы, при котором открывается одно стрим-соединение, в которое оба участника взаимодействия могут отправлять сообщения. Это позволяет более гибко и оперативно реализовать работу.

Например, bidirectional streaming сервиса котировок в одном и том же соединении принимает сообщения об изменении статуса подписки и предоставляет различные виды биржевой информации — стаканы, свечи, поток обезличенных сделок и другие.

Авторизация

Для успешной работы с Tinkoff Invest API нужно передавать токен доступа в metadata каждого запроса.

Формат заголовка — Authorization: Bearer [токен доступа].

Пример запроса: Authorization: Bearer t.QtEo8ahkNFX4RTpbqp0u4z4GDZq27HzUp6AotJASBx7_DVqmqZMHfM2Cy7JmUjS80boI9eVg

Адреса сервиса

  • Продовый контур — invest-public-api.tinkoff.ru:443.
  • Песочница — sandbox-invest-public-api.tinkoff.ru:443.

Подробнее про различия контуров

trackingId запросов

Заголовок x-tracking-id добавляется во все ответы unary-методов Tinkoff Invest API.

Это уникальный UUID запроса, который нужен технической поддержке для разбора инцидентов. При обращении в службу технической поддержки обязательно указывайте x-tracking-id запроса — это ускорит решение вашего вопроса.

В рамках stream-соединений для сообщений управления статусом подписки x-tracking-id передаётся в виде выходного параметра.

Полный текст ошибки

Если при вызове метода Tinkoff Invest API происходит ошибка, в ответе возвращается параметр message. В нём можно посмотреть полный текст описания ошибки.

В Kreya текст ошибки можно посмотреть на вкладке Header в поле message.

AppName запросов

В запросы к Tinkoff Invest API можно добавлять служебный заголовок x-app-name — он нужен для сбора статистики по используемым инструментам.

Если вы разработчик SDK, рекомендуем использовать AppName формата <Ник в GitHub>.<Название репозитория> — например, user.tinkoffSDK.

Рекомендации по тестированию методов

Для тестирования работы Tinkoff Invest API можно использовать любой доступный gRPC-клиент.

Ниже приведены краткие инструкции по настройке двух наиболее популярных клиентов — Kreya и BloomRPC, а также ссылка на гайд по настройке встроенного gRPC-клиента IntelliJ от энтузиаста.

Kreya

Бесплатный gRPC-клиент с широким набором функционала и возможностей.

Скачать клиент

  1. После установки и запуска приложения в меню выберите Project → Importers.

  2. Нажмите New importer. Укажите название источника данных и его тип — gRPC proto files.

  3. Нажмите Add proto directory и укажите папку со скачанными proto-контрактами сервиса Tinkoff Invest API. Также можно нажать Add proto files и выбрать все proto-файлы из папки вручную.

    Скачать актуальную версию контрактов Tinkoff Invest API

    Важно

    Tinkoff Invest API использует google.api.field_behavior-нотацию к полям контрактов. Скачайте field_behavior.proto и сохраните его в папке <contracts_dir>\google\api, где <contracts_dir> — папка с контрактами Tinkoff Invest API.

  4. Сохраните изменения и нажмите Back.

  5. Слева нажмите на папку Tinkoff. Укажите endpoint сервиса — https://invest-public-api.tinkoff.ru:443.

    Остальные настройки заполните как на скриншоте. Обратите внимание на блок Metadata: в нём нужно указать заголовок Authorization, в значении которого передаётся строка Bearer <токен доступа>.

    Как получить токен доступа

После этого можно выполнять запросы к сервису.

В Kreya можно посмотреть служебные заголовки ответа сервера:

  • x-ratelimit-limit — текущий лимит пользователя по данному методу;

  • x-ratelimit-remaining — количество оставшихся запросов данного типа в минуту;

  • x-ratelimit-reset — время в секундах до обнуления счётчика запросов.

Обновление proto-контрактов

Чтобы получить доступ к новому функионалу, который появился после обновления версии, нужно актуализировать proto-контракты.

Для этого заново скачайте контракты, замените скачанные файлы в папке проекта и нажмите Run all importers в левом верхнем углу приложения. Убедитесь, что все proto-контракты имеют актуальную версию.

Не храните бекапы и копии контрактов в одной папке с актуальными.

Если вы получили ошибку The referenced gRPC method is not imported., убедитесь, что вы очистили проект в Kreya от прошлых загруженных контрактов. Всегда проверяйте путь до папки с загружаемыми контрактами, полное наличие всех proto-файлов и их соответствие актуальной версии Tinkoff Invest API. Изменение proto-файлов повлечет за собой ошибку их прочтения у gRPS-клиентов.

BloomRPC

Клиент с простым интерфейсом — чтобы начать работу, нужно указать домен сервиса и импортировать все proto-файлы.

Скачать клиент

  1. Импортируйте скачанные proto-контракты сервиса.

    Скачать актуальную версию контрактов Tinkoff Invest API

  2. Укажите адрес сервера — invest-public-api.tinkoff.ru:443 — и заполните поле metadata: подставьте своё значение токена доступа.

    { "Authorization": "Bearer t.QtEo8ahkNFX4RTpbqp0u4z4GDZq27HzUp6AotJASBx7_DVqmqZMHfM2Cy7JmUjS80boI9eVg" }

    3. При выполнении запросов обязательно указывайте тип TLS-подключения.

После этого можно выполнять запросы к сервису.

В BloomRPC нельзя увидеть заголовки ответов сервера, поэтому мы рекомендуем использовать Kreya.

Встроенный gRPS-клиент IntelliJ

Инструкция — использование встроенного gRPC-клиента IntelliJ