> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/knowledge-base/uvedomleniya-i-integracii/public-api.md).

# API

Клиентский API-доступ, ключи, ограничения, подписи, журналы и оценка подозрительной активности

Раздел управляет доступом клиентов к публичному API. Он одновременно затрагивает учётную запись, отдельные ключи и общие защитные ограничения, поэтому относится к критичным настройкам.

В панели управления откройте:

**«Утилиты» — «Сервисы» — «API»**

Для доступа требуется критичное право «Разрешить доступ к API в админпанели» из блока «Админпанель».

## Список ключей

Страница «Ключи публичного API» показывает ключи всех клиентов. Поиск принимает название ключа, клиента, E-mail или ID. Блок «Требуют внимания» отдельно показывает ключи с повышенной оценкой риска за последние 24 часа.

Колонка «Доступ сейчас» учитывает общий статус API, доступ клиента, состояние ключа, срок действия и запрет для административного аккаунта. Поэтому она может отличаться от сохранённого «Состояние ключа».

Откройте ключ. Редактор разделён на «Права доступа», «Защита и лимиты» и «Сведения». На вкладке «Сведения» переключатель «API-доступ всего клиента» разрешает или запрещает API для всей учётной записи. Отключение доступа клиента имеет приоритет над настройками всех его ключей, но не удаляет их права и лимиты.

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

Доступны настройки:

* разрешённые возможности ключа;
* обязательность HMAC-подписи;
* индивидуальный лимит запросов в минуту;
* дневная и месячная квота;
* признак тарифицируемого использования;
* список разрешённых IP-адресов;
* срок действия и статус.

Пустое значение или ноль в индивидуальном лимите либо квоте означает наследование общего значения, если это указано формой. Выдавайте только те возможности, которые действительно нужны интеграции.

Права выбираются по понятным русским названиям и сгруппированы по назначению. Используйте поиск «Найти право доступа» и проверяйте метку «Изменяет данные». Не выдавайте право только потому, что оно находится рядом с уже нужным.

Значение ключа и секрет подписи показываются клиенту только при создании. В панели доступны настройки и журнал, но не исходный секрет.

«Отключить» временно приостанавливает ключ и позволяет позднее включить его снова. «Отозвать ключ» прекращает работу окончательно; клиенту потребуется создать новый. Удаление убирает запись, поэтому перед ним убедитесь, что ротация завершена и необходимые журналы сохранены.

## Массовое управление

Отметьте строки флажками. Действие «Выбрать все ключи (…)» выбирает все записи текущего фильтра, а не только видимую страницу. После этого доступны «Отключить» и «Удалить».

Перед массовым действием:

1. сбросьте лишние фильтры;
2. выполните точный поиск;
3. проверьте число в «Выбрать все ключи (…)»;
4. откройте несколько строк из начала и конца выборки;
5. только затем подтвердите действие.

Массовое отключение обратимо и не меняет уже отозванные ключи. Массовое удаление необратимо: интеграции немедленно потеряют доступ. Если результат не подтверждён, обновите список перед повторной попыткой.

## Партнёрские выплаты через API

Для чтения способов выплаты, баланса, списка и карточки выплаты ключу нужно право «Партнерские выплаты» из группы «Партнёрская программа».

Для создания заявки дополнительно требуется отдельное право «Запрос партнёрской выплаты». В верхней части редактора оно отмечается как критичное действие «Выплата бонусов».

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

Создание через API формирует ожидающую заявку и списывает запрошенную базовую сумму с доступного партнёрского баланса один раз. Если в партнёрской программе включено подтверждение по E-mail, оно остаётся обязательным. Фактический перевод выполняется обычным процессом партнёрских выплат.

{% hint style="danger" %}
Не выдавайте «Запрос партнёрской выплаты» ключу, которому нужен только просмотр статистики. Для финансовой интеграции обязательно ограничьте IP, включите подпись каждого запроса и проведите тест на минимальной безопасной сумме.
{% endhint %}

## Общие настройки публичного API

Кнопка «Настройки публичного API» открывает общие параметры. Из панели можно менять:

* включение публичного API;
* HMAC для запросов, изменяющих данные;
* допустимое временное окно HMAC;
* максимальное число ключей одного клиента;
* период совместной работы ключей при ротации;
* время хранения и блокировки идемпотентного запроса;
* дневную и месячную квоту по умолчанию;
* тарификацию по умолчанию;
* максимальное число webhook-адресов клиента;
* запрет API для административных аккаунтов.

Часть значений показывается как справочная конфигурация и не редактируется в этом окне: общий лимит запросов, глобальное требование HMAC, пауза между созданиями ключей, тайм-аут webhook и режим фоновой обработки webhook.

Изменение общего значения затрагивает все ключи, которые его наследуют. Перед ужесточением лимита найдите интеграции с высоким нормальным трафиком.

### Защита создания заявки от повторов

При создании заявки интеграция передаёт уникальный заголовок `Idempotency-Key` для одной логической операции. Если сервер уже завершил запрос, повтор с тем же ключом и теми же данными возвращает прежний результат. Если под тем же ключом передать изменённые данные, запрос отклоняется.

Два общих параметра определяют окно защиты:

* **«Хранение результата для защиты от повторов, часы»**;
* **«Блокировка повторного выполнения, секунды»**.

Если соединение оборвалось после отправки, повторите тот же запрос с прежним ключом и неизменным телом. Не создавайте новый ключ, пока результат первой операции неизвестен.

### Фоновая отправка webhook

Параметр **«Автоотправка webhook»** включает отправку событий на адреса клиента. Также учитываются **«Адресов получения событий на клиента»** и **«Ожидание ответа получателя, секунды»**.

Webhook обрабатывается в фоне. Медленный получатель не должен задерживать основную операцию, а временная ошибка приводит к контролируемой повторной доставке и восстановлению зависших отправок. Получатель обязан безопасно принимать повтор одного события: храните идентификатор события и не выполняйте финансовое действие второй раз.

Событие о нажатии клиентом **«Я оплатил»** сообщает только о действии пользователя. Оно не подтверждает поступление средств. Фактическую оплату устанавливают callback, проверка мерчанта или подтверждённая операция в сети.

## Суммы при создании заявки

Сумма должна быть положительной десятичной записью: цифры и при необходимости точка с дробной частью. Не передавайте знак `+`, запятую или экспоненциальную форму наподобие `1e8`. Для денежных значений предпочтительна JSON-строка, например `"1250.50"`: так клиентская библиотека не округлит дробь до отправки.

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

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

## Подозрительная активность

Вкладка «Подозрительная активность» показывает недавние сигналы риска по пользователям и ключам: уровень, причины и рекомендации. Это средство приоритизации проверки, а не доказательство нарушения.

При высоком риске:

1. Сверьте пользователя и ключ.
2. Откройте журналы запросов.
3. Проверьте IP, Origin, Referer, User-Agent и частоту ошибок.
4. Сопоставьте время с известными действиями клиента.
5. При необходимости сначала отключите ключ, затем свяжитесь с владельцем.

## Журналы API

Общий журнал открывается по пути:

**«Журнал событий» — «Журнал публичного API»**

Для доступа требуется право «Разрешить доступ к API в админпанели» из блока «Админпанель».

Можно открыть общий журнал или журнал конкретного ключа. Запись может содержать источник запроса, IP клиента и исходный IP, Origin, Referer, User-Agent, идентификаторы запроса, код сбоя, заголовки, тело запроса, ответ API и сообщение об ошибке.

Не передавайте журнал третьим лицам без очистки чувствительных данных. Кнопка «Очистить лог» удаляет доступные записи для выбранной области и лишает команду доказательств инцидента.

{% hint style="danger" %}
Перед очисткой журналов сохраните необходимые доказательства и убедитесь, что завершены расследование и обязательный срок хранения.
{% endhint %}

## Контрольный сценарий

1. Включите API-доступ тестового клиента.
2. Выдайте минимальный набор возможностей тестовому ключу.
3. Ограничьте IP, если у интеграции фиксированный адрес.
4. Выполните разрешённый и запрещённый запрос.
5. Проверьте допустимую десятичную сумму, ноль, отрицательное значение, экспоненциальную запись и изменение резерва после расчёта.
6. Проверьте лимит, квоту, подпись, идемпотентность и запись в журнале.
7. Повторите создание с тем же ключом и телом, затем убедитесь, что вернулся прежний результат.
8. Повторите тот же ключ с изменённым телом и убедитесь, что запрос отклонён.
9. Имитируйте временную недоступность тестового webhook-получателя и проверьте последующую доставку без повтора основной операции.
10. Отключите ключ и убедитесь, что новый запрос больше не проходит.

Если запрос отклонён, проверяйте по порядку: общий статус API, доступ клиента, состояние и срок ключа, возможность, IP-список, подпись, квоту и лимит. Код и детали из журнала точнее, чем повторные изменения нескольких настроек.
