> 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/exchanger-api/nachalo-raboty/readme.md).

# Что такое iEXExchanger API

iEXExchanger API позволяет подключить обменник к внешнему сайту, мобильному приложению, Telegram-боту, CRM или партнерскому кабинету. Через API можно получить направления обмена, рассчитать сумму, создать заявку, проверить статус, загрузить документы и получать события через webhooks.

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

## Что можно сделать через API

| Возможность                      | Пример использования                                    |
| -------------------------------- | ------------------------------------------------------- |
| Получить платежные системы       | Показать пользователю, что он может отдать и получить.  |
| Получить направления обмена      | Построить форму обмена на своем сайте или в приложении. |
| Рассчитать обмен                 | Показать сумму к получению до создания заявки.          |
| Проверить заявку перед созданием | Узнать, каких полей не хватает и пройдет ли заявка.     |
| Создать заявку                   | Отправить обменную заявку от имени клиента.             |
| Получить статус заявки           | Показать пользователю текущий этап обработки.           |
| Подтвердить оплату               | Передать, что пользователь оплатил заявку.              |
| Загрузить файл                   | Отправить документ, карту или вложение к заявке.        |
| Получить webhooks                | Автоматически узнавать об изменении статусов.           |
| Смотреть usage                   | Контролировать лимиты и расход API.                     |
| Работать с партнеркой            | Получать рефералов, обмены, выплаты и статистику.       |

## Кому что читать

| Кто вы                                    | С чего начать                                                                                                                                                                                                                                                                       |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Администратор обменника                   | [Как администратору включить API](https://docs.iexexchanger.com/exchanger-api/poluchenie-dostupa-i-klyuchei/admin-enable-api.md)                                                                                                                                                    |
| Клиент обменника                          | [Как клиенту получить API-ключ](https://docs.iexexchanger.com/exchanger-api/poluchenie-dostupa-i-klyuchei/client-get-api-key.md)                                                                                                                                                    |
| Технический руководитель                  | [Все возможности API](https://docs.iexexchanger.com/exchanger-api/nachalo-raboty/api-capabilities.md)                                                                                                                                                                               |
| Разработчик                               | [Быстрый старт: первая заявка](https://docs.iexexchanger.com/exchanger-api/nachalo-raboty/quick-start.md)                                                                                                                                                                           |
| Backend-разработчик production-интеграции | [HMAC-подпись запросов](https://docs.iexexchanger.com/exchanger-api/kak-ustroen-api/hmac-signature.md), [Idempotency-Key](https://docs.iexexchanger.com/exchanger-api/kak-ustroen-api/idempotency.md), [Webhooks](https://docs.iexexchanger.com/exchanger-api/webhooks/overview.md) |
| Support                                   | [Ошибки и как их обрабатывать](https://docs.iexexchanger.com/exchanger-api/kak-ustroen-api/errors.md), [Решение частых проблем](https://docs.iexexchanger.com/exchanger-api/spravochnik/common-issues.md)                                                                           |

## Главный сценарий подключения

Минимальный путь до рабочей интеграции:

```
1. Администратор включает API клиенту.
2. Клиент создает ключ в Профиль -> Настройки -> API.
3. Разработчик проверяет ключ через /private/health/client.
4. Приложение получает платежные системы и направления.
5. Приложение рассчитывает quote.
6. Приложение проверяет данные через preflight.
7. Приложение создает заявку с Idempotency-Key.
8. Статусы приходят через webhook или читаются через status endpoint.
```

## Базовый URL

В примерах используется:

```
https://example.com/api/v3
```

В реальной интеграции замените `example.com` на домен вашего обменника:

```
https://{your-domain}/api/v3
```

Не добавляйте `app.` автоматически. Используйте тот домен, который выдал владелец обменника или который настроен в nginx.

## Что нужно для приватных запросов

Минимально:

```http
Accept: application/json
Authorization: Bearer YOUR_API_KEY
```

Для `POST`, `PUT`, `PATCH`, `DELETE` в production также рекомендуется:

```http
Idempotency-Key: unique-operation-key
X-Api-Timestamp: 1782190000
X-Api-Nonce: req-20260623-001
X-Api-Signature: sha256=...
```

## OpenAPI и SDK

В репозитории есть:

| Файл                                | Для чего нужен                                                  |
| ----------------------------------- | --------------------------------------------------------------- |
| `openapi/openapi.yaml`              | OpenAPI-файл со всеми endpoints, параметрами и схемами ответов. |
| `sdk/php/PublicApiSigner.php`       | PHP helper для подписи HMAC-запросов.                           |
| `sdk/typescript/PublicApiClient.ts` | TypeScript-клиент для запросов к API.                           |

Live OpenAPI также может быть доступен на установке:

```
https://{your-domain}/api/v3/openapi.yaml
```

## API Reference

Раздел [API Reference](https://docs.iexexchanger.com/exchanger-api/api-reference/openapi-reference.md) построен из `openapi/openapi.yaml`. В нем удобно смотреть точные параметры endpoints, request body, headers, responses и scopes.

Руководства объясняют сценарии, а API Reference дает точный контракт запроса.
