Клиент для BCS Trade API на PHP/Laravel

🔗 GitHub Репозиторий: https://github.com/tigusigalpa/bcs-trade-php

Этот пакет представляет собой неофициальный клиент для торгового API БКС, разработанный для экосистемы PHP и Laravel. Он обеспечивает полное взаимодействие с API брокера, используя как HTTP для запросов, так и WebSocket для получения данных в реальном времени.

Ключевые особенности

• Полное покрытие API: Реализована поддержка всех HTTP-эндпоинтов и WebSocket-каналов, предоставляемых BCS Trade API.
• Автоматизация: Встроен механизм автоматического обновления токенов OAuth 2.0 для непрерывной работы.
• Надежность: Пакет умеет обрабатывать сетевые сбои с помощью повторных попыток и корректно реагирует на превышение лимитов запросов (HTTP 429).
• Удобство: Включает автоматическую пагинацию для загрузки больших объемов исторических данных и валидацию запросов.
• Современный стек: Написан на PHP 8.1+ с использованием современных возможностей языка и поддерживает актуальные версии Laravel (9-12).
• Качество кода: Соответствует стандарту PSR-12 и покрыт тестами на Pest для гарантии стабильности.
• Продуманная обработка ошибок: Используются кастомные исключения для каждого типа ошибок API, что упрощает отладку.

Требования к окружению

Для корректной работы пакета ваше окружение должно соответствовать следующим критериям:

• PHP: версия 8.1 или новее.
• Laravel: одна из версий 9.x, 10.x, 11.x или 12.x.
• Composer: для управления зависимостями.

Процесс установки

Установка клиента производится с помощью Composer. Выполните следующую команду в терминале вашего проекта:

После установки пакета необходимо опубликовать файл конфигурации. Это можно сделать с помощью команды:

Настройка клиента

Получение токена доступа (Refresh Token)

Для аутентификации в API вам потребуется

. Чтобы его получить, следуйте этим шагам:

1. Авторизуйтесь в личном кабинете БКС Мир Инвестиций.
2. Перейдите в профиль и откройте раздел, посвященный управлению токенами API.
3. Сгенерируйте новый токен. Обязательно скопируйте полученный
   refresh_token
   .
4. Обратите внимание, что срок действия этого токена составляет 90 дней, после чего его потребуется обновить.

Настройка переменных окружения

Добавьте полученный токен и другие необходимые параметры в файл

вашего Laravel-приложения:

Детальная конфигурация

Файл

содержит все доступные параметры для тонкой настройки клиента. Ниже представлена таблица с описанием каждого параметра.

Примеры использования

Инициализация клиента

Вы можете инициализировать клиент несколькими способами, в зависимости от архитектуры вашего приложения.

Взаимодействие с HTTP API

Аутентификация

Пакет автоматически управляет токенами доступа. Однако, при необходимости, вы можете получить токен вручную.

Лимиты портфеля

Получение информации о текущих лимитах вашего портфеля.

Состав портфеля

Запрос для получения полного состава вашего инвестиционного портфеля.

Справочная информация

Доступ к различной справочной информации по инструментам и торгам.

Рыночные данные (Свечи)

Получение исторических данных о ценах (свечей) для анализа.

Торговые операции (Ордера)

Важно: Для выполнения торговых операций ваш токен должен иметь

.

Сделки

Получение списка ваших сделок.

Скидки по инструментам

Получение информации о доступных скидках.

Работа с WebSocket API

Клиент предоставляет удобный интерфейс для подписки на real-time данные через WebSocket. Все каналы поддерживают автоматическое переподключение в случае разрыва соединения с использованием экспоненциальной задержки.

Обновления лимитов в реальном времени

Подписка на изменения лимитов вашего счета.

Обновления портфеля в реальном времени

Отслеживание изменений в составе и стоимости вашего портфеля.

Маржинальные показатели

Получение данных о маржинальных показателях в реальном времени.

Последняя свеча

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

Стакан котировок (Order Book)

Получение обновлений стакана котировок (глубины рынка) в реальном времени.

Котировки

Подписка на получение актуальных котировок для одного или нескольких инструментов.

Обезличенные сделки (All Trades)

Получение информации обо всех совершаемых на бирже сделках по инструменту.

Статус исполнения ордеров

Отслеживание статуса ваших ордеров в реальном времени.

Статус транзакций

Получение обновлений о статусе ваших финансовых транзакций.

Обработка исключений

Для упрощения отладки и повышения надежности вашего кода, клиент использует строго типизированные исключения для разных классов ошибок. Это позволяет гибко реагировать на каждую нештатную ситуацию.

Тестирование пакета

Проект покрыт набором тестов, написанных с использованием Pest. Для их запуска выполните следующие команды в корневой директории проекта:

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

Для получения более подробной информации о возможностях и правилах работы с API, обратитесь к официальной документации BCS Trade API.

Ключевые разделы документации:

• Ограничения API
• HTTP: Авторизация
• HTTP: Торговые операции
• WebSocket: Обзор

Важные ограничения

При работе с API следует учитывать несколько ключевых моментов:

1. Срок жизни Refresh Token: Токен для аутентификации действителен ровно 90 дней. По истечении этого срока вам потребуется вручную сгенерировать новый в личном кабинете БКС.
2. Лимит на исторические данные: За один API-запрос можно получить не более 1000 свечей (баров). Для загрузки данных за более длительные периоды используйте метод
   getCandlesPaginated()
   .
3. Ограничение частоты запросов (Rate Limiting): API имеет лимиты на количество запросов в единицу времени. Пакет пытается обрабатывать это автоматически, но рекомендуется отлавливать исключение
   BCSRateLimitException
   .
4. Права доступа для торговли: Для выполнения торговых операций (создание, изменение, отмена ордеров) необходимо, чтобы ваш
   client_id
   был установлен в значение
   trade-api-write
   .

История изменений

Все изменения, вносимые в проект, документируются в файле CHANGELOG.md.

Лицензия

Данный пакет распространяется под лицензией MIT. Подробности можно найти в файле LICENSE.

Автор и поддержка

• Разработчик: Igor Sazonov (@tigusigalpa)
• Вопросы и предложения: Создавайте Issue в соответствующем разделе репозитория.
• Пулл-реквесты: Приветствуются и принимаются здесь.

---

Отказ от ответственности: Этот пакет является неофициальной разработкой и не имеет прямого отношения к компании БКС. Вся ответственность за его использование лежит на вас.