Журнал изменений (Changelog)

В данном разделе публикуется официальный список изменений и обновлений Syncra Merchant API. Мы фиксируем все новые функции (features), исправления ошибок (bugfixes), объявления об устаревании (deprecations) и обратно-несовместимые изменения (breaking changes).

Формат записей

Каждая запись в changelog имеет стандартизированную структуру:

• Заголовок: Дата релиза (в формате YYYY-MM-DD) и краткое резюме.
• Тип изменения:
  • [FEATURE] — Добавление нового функционала или эндпоинта.
  • [FIX] — Исправление ошибок в логике работы API.
  • [DEPRECATION] — Предупреждение об устаревании функционала и планируемом отключении.
  • [BREAKING] — Обратно-несовместимые изменения, требующие обновления вашего кода.
• Категория: Сфера влияния изменения (payin, payout, auth, callbacks, disputes, balance, general).
• Описание: Детальное объяснение изменений и инструкции по обновлению (Migration Path).

Актуальная история версий

2026-07-12 — Запуск Merchant API V2 и Адаптера V1

[FEATURE] [general]

Официальный запуск Merchant API V2. Новая архитектура предоставляет повышенную стабильность, единый формат интеграции и улучшенные показатели безопасности.

Основные нововведения:

• HMAC-SHA256 подписи: Внедрена унифицированная схема подписи X-Signature от тела запроса для всех эндпоинтов вместо разрозненных формул в V1.
• Строковые перечисления статусов: Переход с числовых кодов состояний (например, 11, 1) на строковые String Enums (PAID, PENDING), что повышает читаемость логов и кода.
• Суммы в минимальных единицах (копейках): Суммы больше не передаются в виде строк с точкой ("1500.00"). Теперь используется целочисленный формат int64 (копейки, центы: 150000). Это защищает от ошибок округления чисел с плавающей запятой.
• Интерактивная песочница (API Playground): Документация теперь содержит интерактивный Reference с возможностью выполнять тестовые запросы прямо из браузера.

[FEATURE] [general]

Внедрение V1 Compatibility Adapter (Адаптера совместимости).

• Позволяет существующим клиентам, интегрированным с API V1, переключиться на новую инфраструктуру Syncra V2 без изменения своего исходного кода.
• Адаптер автоматически парсит старые заголовки (MERCHANT, SIGNATURE), проверяет подписи по алгоритму HMAC-SHA512, конвертирует форматы сумм и отдает ответы в старом конверте {failures, value, isSuccess}.

[DEPRECATION] [general]

Объявление о выводе из эксплуатации API V1.

• Период поддержки (Grace Period): 6 месяцев с текущей даты (до 12 января 2027 года). В этот период адаптер работает в штатном режиме без ограничений.
• Период предупреждений (Warning Period): Начиная с 13 января 2027 года, ответы через адаптер V1 начнут содержать заголовок X-Syncra-Deprecated: true, а также текстовые предупреждения об устаревании.
• Полное отключение (Sunset): 12 февраля 2027 года V1 адаптер будет окончательно выключен. Все запросы по старым путям начнут возвращать статус 410 Gone.

2026-07-13 — Архитектурная модернизация: Data-Driven Currencies и Appeals API

[BREAKING] [payout]

Поля card_number и full_name в PayOut переименованы в target_requisite и target_name для поддержки всех типов реквизитов (карта, СБП, e-wallet). V1 адаптер обрабатывает маппинг автоматически.

Инструкция по миграции:

- "card_number": "2202201234567890"
- "full_name": "Иван Иванович"
+ "target_requisite": "2202201234567890"
+ "target_name": "Иван Иванович"

[FEATURE] [disputes]

Добавлен полноценный Appeals API для мерчантов:

• POST /appeals — открытие диспута по сделке
• GET /appeals — список диспутов с фильтрацией
• GET /appeals/{id} — получение диспута
• POST /appeals/{id}/messages — отправка сообщения в чат
• GET /appeals/{id}/messages — история чата

[FEATURE] [general]

Переход на data-driven конфигурацию: валюты, страны, лимиты и методы оплаты теперь управляются через админ-панель без перезапуска сервисов.

[FEATURE] [balance]

Мультивалютные балансы: поле currency теперь отражает реальную валюту тенанта. USDT wallet_id содержит реальный TRC-20 адрес мерчанта.

Шаблон для добавления будущих записей

При внесении любых изменений в API разработчики Syncra обязаны добавлять новую запись в конец этого документа по следующему шаблону:

### YYYY-MM-DD — Заголовок изменения

#### `[FEATURE|FIX|DEPRECATION|BREAKING]` `[категория]`
Детальное описание изменений для разработчиков мерчантов.

**Инструкция по миграции (если применимо):**
Что именно нужно переписать на стороне мерчанта.