# API v1 ## Включение API Для работы с API необходимо активировать модуль API в разделе "Модули"
### Настройки API После активации модуля перейдите в раздел "**API**" ➔ "**Настройки**". Установите желаемые настройки:
* **API:**\ • **Выключен** — доступ к API закрыт\ • **Все пользователи** — доступ к API будет у всех пользователей обменника\ • **Избранные пользователи** — доступ к API будет только у тех пользователей, для кого включена опция "**Работать с REST API**" в настройках пользователя в панели администратора
{% hint style="warning" %} Обратите внимание, что API-ключи для системного пользователя (ID = 0) не будут работать в режиме "**Избранные пользователи**" — для их работы переключите режим на "**Все пользователи**" или назначьте такой ключ реальному пользователю с ID > 0. {% endhint %} * **Логи** — запись лога при работе с API в раздел "**API**" ➔ "**Логи**"\ • **Нет**\ • **Да** * **Методы, доступные для пользователей** — набор методов, которые будут доступны для пользователя при добавлении ключа в личном кабинете обменника
### Получение API ключей через личный кабинет пользователя Пользователь может получить доступ к API через личный кабинет, по умолчанию это ссылка `https://ваш_домен/user-api/`
После выбора методов и указания IP-адресов необходимо нажать кнопку "**Добавить API ключ**". После этого на странице отобразится выпущенная пара "**Логин** — **Ключ**".
Можно выпустить несколько ключей для одного пользователя с различными наборами методов. ### Создание API ключей через панель администратора {% hint style="warning" %} Рекомендуем создавать API-ключи именно для конкретных пользователей, не под пользователем "**Система**".\ Под "**Системой**" вы выдаете доступ от себя, как от админа обменника — лучше создавать API-ключи именно от нужного пользователя. В противном случае пользователь по методу `get_exchanges` (если он включен) получит доступ ко всем заявкам, созданным по API, а не только к созданным от своего аккаунта. {% endhint %} На странице "**API**" ➔ "**Добавить**" добавьте нового пользователя API.
* **Пользователь** — ID пользователя обменника или 0 (пользователь "**Система**") * **Разрешенные IP-адреса** — IP-адреса, с которых будет разрешен доступ к API * **Доступные методы** — набор методов, которыми может воспользоваться пользователь После сохранения данных будет сгенерирована пара "**Логин** — **Ключ**"
*** ## Использование API Точка входа: `https://ваш_домен/api/userapi/v1/ + метод API` Для авторизации, необходимо отправлять в заголовках (headers) запросов к API информацию, полученную ранее в разделе "**API**": **API-LOGIN** — API-логин **API-KEY** — API-ключ **API-LANG** — принудительное использования указанного языка (необязательно). Пример: ru\_RU, en\_US. {% hint style="warning" %} Все запросы отправляются методом **POST**, ответ возвращается в формате json **(GET-запросы не используются),** параметры передаются в теле запроса (не в заголовке). Пример запроса с передачей параметра из Postman и ответ на запрос:\ ![](/files/MiQuQGyBLr1L2Irtgl6C) {% endhint %} ### Методы работы с API: ### test Tестовый метод для проверки работы API. Параметры запроса: ``` --- ``` Ответ: ``` ip — ваш IP-адрес user_id — ID пользователя (если обращается система, ID = 0) locale — язык сайта partner_id — ID партнера ``` ### get\_direction\_currencies Получение списка валют, доступных для обмена Параметры запроса: ``` currency_id_give — ID валюты "Отдаю" (фильтр, необязательный параметр) currency_id_get — ID валюты "Получаю" (фильтр, необязательный параметр) ``` Ответ: ``` В ответе 2 списка: give — список валют "Отдаю" get — список валют "Получаю" В каждом списке содержатся следующие данные: id — ID валюты в обменнике title — название валюты в обменнике logo — ссылка на логотип валюты ``` ### get\_directions Получение списка направлений обменов, доступных для обмена Параметры запроса: ``` currency_id_give — ID валюты "Отдаю" (фильтр, необязательный параметр) currency_id_get — ID валюты "Получаю" (фильтр, необязательный параметр) ``` Ответ: ``` В ответе список направлений обмена, в нем: direction_id — ID направления обмена в обменнике currency_give_id — ID валюты "Отдаю" в обменнике currency_give_title — название валюты "Отдаю" в обменнике currency_give_logo — логотип валюты "Отдаю" в обменнике currency_get_id — ID валюты "Получаю" в обменнике currency_get_title — название валюты "Получаю" в обменнике currency_get_logo — логотип валюты "Получаю" в обменнике ``` ### get\_direction Получение информации о направлении обмена Параметры запроса: ``` direction_id — ID направления обмена ``` Ответ: ``` id — ID направления обмена в обменнике url — ссылка на страницу обмена currency_code_give — код валюты "Отдаю" currency_code_get — код валюты "Получаю" reserve — резерв course_give — курс валюты "Отдаю" course_get — курс "Получаю" sum_give — сумма в валюте "Отдаю" sum_give_com — сумма в валюте "Отдаю" с комиссией sum_get — сумма в валюте "Получаю" sum_get_com — сумма "Получаю" с комиссией com_give — текст комиссии валюты "Отдаю" com_get — текст комиссии "Получаю" min_give — минимальная сумма валюты "Отдаю", no - не установлена max_give — максимальная сумма валюты "Отдаю", no - не установлена min_get — макс сумма валюты "Получаю", no - не установлена max_get — макс сумма валюты "Получаю", no - не установлена info timeline_text — описание обмена frozen_text — текст замороженного статуса before_button_text — текст до кнопки "Оплатить" give_fields — список полей, относящихся к валюте "Отдаю" get_fields — список полей, относящихся к валюте "Получаю" dir_fields — список полей направления обмена Описание поля: name — название для передачи type — тип поля label — описание поля req — 0 - необязательно передавать, 1 - обязательно передавать tooltip — текст подсказки options — возможные опции, если поле имеет тип select cd — указатель дополнительных параметров ``` ### get\_calc Калькулятор сумм для направления обмена Параметры запроса: 
direction_id — ID направления обмена
calc_amount — сумма
calc_action — принадлежность суммы: 1 — сумма в валюте "Отдаю",
                                    2 — сумма в валюте "Получаю",
                                    3 — сумма в валюте "Отдаю" с комиссией,
                                    4 — сумма в валюте "Получаю" с комиссией
cd — поля из направления обмена, с пометкой cd = 1, в одном поле. Поле обработано URL encode.
cd — city=[код города] (пример: city=SPB)
Ответ: ``` currency_code_give — код валюты "Отдаю" currency_code_get — код валюты "Получаю" reserve — резерв валюты "Получаю" course_give — курс валюты "Отдаю" course_get — курс валюты "Получаю" sum_give — сумма в валюте "Отдаю" sum_give_com — сумма в валюте "Отдаю" с комиссией sum_get — сумма в валюте "Получаю" sum_get_com — сумма в валюте "Получаю" с комиссией com_give — текст комиссии валюты "Отдаю" com_get — текст комиссии валюты "Получаю" min_give — минимальная сумма валюты "Отдаю", no - не установлена max_give — максимальная сумма валюты "Отдаю", no - не установлена min_get — максимальная сумма валюты "Получаю", no - не установлена max_get — максимальная сумма валюты "Получаю", no - не установлена changed — флаг изменения вводимой суммы: 0 - не нужно изменять, 1 - нужно изменить ``` ### get\_exchanges Вывод заявок, созданных данным ключом Параметры запроса: {% code overflow="wrap" %} ``` start_time — unix-время с которого выводить заявки (фильтр, необязательный параметр) end_time — unix-время до которого выводить заявки (фильтр, необязательный параметр) ip — IP-адрес (фильтр, необязательный параметр) id — ID заявки (фильтр, необязательный параметр) api_id — ID, переданное в API (фильтр, необязательный параметр) status_history — выводить ли историю статусов: 0 - нет, 1 - да (фильтр, необязательный параметр) limit — количество выводимых заявок (фильтр, необязательный параметр) offset — сколько заявок пропустить (фильтр, необязательный параметр) ``` {% endcode %} Ответ: ``` items - список заявок id — ID заявки api_id — ID, переданное в API time — время изменения статуса date — дата изменения статуса psys_give — ПС валюты "Отдаю" psys_get — ПС валюты "Получаю" currency_code_give — код валюты "Отдаю" currency_code_get — код валюты "Получаю" course_give — курс валюты "Отдаю" course_get — курс валюты "Получаю" amount_give — сумма в валюте "Отдаю" amount_get — сумма в валюте "Получаю" exchange_success — 0 - заявка выполнена, 1 - заявка не выполнена user_hash — хэш пользователя user_ip — IP-адрес пользователя status — статус заявки statuses — список изменения статусов time — время изменения статуса date — дата изменения статуса status — статус заявки ``` ### create\_bid Создание заявки Параметры запроса: 
direction_id — ID направления обмена
partner_id — ID партнера (необязательный параметр)
api_id — ID заявки в вашей системе (необязательный параметр)
calc_amount — сумма обмена
calc_action — принадлежность суммы: 1 — сумма в валюте "Отдаю",
                                    2 — сумма в валюте "Получаю",
                                    3 — сумма в валюте "Отдаю" с комиссией,
                                    4 — сумма в валюте "Получаю" с комиссией
callback_url - укажите url, на который API будет присылать ответ при изменении статуса заявки. Приходит методом POST:

bid_id — id заявки,
account1 — cо счета
cfgive8 — имя владельца карты
account2 — на счет
cf1-99 — кастомные поля
Примеры полей:

cf1 — Имя
cf2 — Отчество
cf3 — Фамилия
cf4 — Телефон
cf5 — Skype
cf6 — E-mail
cf8 — Номер паспорта
cf10 — Регион
cf11 — Telegram
Ответ: ``` url — ссылка на страницу обмена id — ID заявки hash — hash заявки status — статус заявки status_title — название статуса заявки psys_give — ПС валюты "Отдаю" psys_get — ПС валюты "Получаю" currency_code_give — код валюты "Отдаю" currency_code_get — код валюты "Получаю" amount_give — сумма в валюте "Отдаю" amount_get — сумма в валюте "Получаю" api_actions — опции type — тип оплаты cancel — способ отмены заявки api — методом API disabled — отключено ссылка на отмену pay — способ оплаты api — методом API disabled — отключено ссылка на отмену instruction — инструкция по оплате pay_amount — сумма к оплате ``` ### cancel\_bid Отмена заявки (метод работает только в том случае, если при создании заявки (`create_bid`) в ответе `api_actions` ➔ `cancel`= "**api"**) Параметры запроса: ``` hash — хэш заявки ``` Ответ: ``` статус заявки ``` ### pay\_bid Отметка заявки оплаченной (метод работает **только в том случае**, если при создании заявки методом `create_bid` в ответе будет `"api_actions"` ➔`"pay": "api"` (когда в направлении обмена **не используется** мерчант)).
Если в заявке был использован мерчант, то заявка по API сменит статус на "**Оплаченная**" **только автоматически** (когда мерчант увидит поступление средств по заявке). Параметры запроса: ``` hash — хэш заявки ``` Ответ: ``` статус заявки ``` | Статусы заявок в API | Статусы в разделе "Заявки" | | -------------------- | --------------------------------------------- | | new | новая заявка | | coldnew | заявка в ожидании верификации | | cancel | отмененная пользователем заявка | | delete | удаленная заявка | | techpay | когда пользователь перешел на страницу оплаты | | payed | пользователь отметил заявку как оплаченную | | coldpay | ожидание подтверждения от мерчанта | | partpay | частично оплачено | | realpay | оплаченная заявка | | verify | заявка на проверке | | mercherror | ошибка мерчанта | | error | ошибочная заявка | | payouterror | ошибка автовыплаты | | scrpayerror | ошибка автовыплаты (API платежной системы) | | coldsuccess | ожидание подтверждения от модуля автовыплат | | partpayout | частичная выплата | | success | выполненная заявка | ### success\_bid Отметка заявки выполненной. Параметры запроса: ``` hash — хэш заявки ``` Ответ:
``` статус заявки ``` ### bid\_info Платежная информация о заявке {% hint style="warning" %} Запрашивать информацию по заявке с помощью этого метода возможно только если сама заявка была создана по API. {% endhint %} параметры запроса: ``` id — ID заявки (необязательно, если задан hash) hash — хэш заявки (необязательно, если задан ID) ``` Ответ: ``` url — ссылка на страницу обмена id — ID заявки hash — hash заявки status — статус status_title — название статуса psys_give — ПС валюты "Отдаю" psys_get — ПС валюты "Получаю" currency_code_give — код валюты "Отдаю" currency_code_get — код валюты "Получаю" amount_give — сумма в валюте "Отдаю" amount_get — сумма в валюте "Получаю" api_actions — опции type — тип оплаты cancel — способ отмены заявки api — методом API disabled — ссылка на отмену отключена pay - способ оплаты api — методом API disabled — отключено ссылка на оплату instruction — инструкция по оплате pay_amount — сумма к оплате ``` ### get\_partner\_info Информация о партнере Параметры запроса: ``` --- ``` Ответ: ``` partner_id - ID партнера balance - баланс min_payout - мин. сумма выплаты items - список валют, для заказа выплаты id - ID валюты title - название валюты comission - комиссия amount - баланс в этой валюте ``` ### get\_partner\_links Информация о партнерских переходах Параметры запроса: ``` start_time - unix-время с которого выводить (фильтр, необязательный параметр) end_time - unix-время до которого выводить (фильтр, необязательный параметр) ip - IP-адрес (фильтр, необязательный параметр) limit - количество выводимых (фильтр, необязательный параметр) ``` Ответ: ``` items - список партнерских переходов time - время перехода date - дата перехода browser - браузер ip - адрес перещедшего пользователя referrer - страница, с которой был совершен переход user_hash - хэш пользователя query_string - строка запроса ``` ### get\_partner\_exchanges Информация о партнерских обменах Параметры запроса: {% code overflow="wrap" %} ``` start_time - unix-время, с которого выводить заявки (фильтр, необязательный параметр) end_time - unix-время, до которого выводить заявки (фильтр, необязательный параметр) ip - IP-адрес (фильтр, необязательный параметр) id - ID заявки (фильтр, необязательный параметр) status_history - выводить ли историю статусов: 0 - нет, 1 - да (фильтр, необязательный параметр) limit - количество выводимых заявок (фильтр, необязательный параметр) ``` {% endcode %} Ответ: ``` items - список заявок id - ID заявки time - время изменения статуса date - дата изменения статуса psys_give - ПС валюты "Отдаю" psys_get - ПС валюты "Получаю" currency_code_give - код валюты "Отдаю" currency_code_get - код валюты "Получаю" course_give - курс валюты "Отдаю" course_get - курс валюты "Получаю" amount_give - сумма в валюте "Отдаю" amount_get - сумма в валюте "Получаю" exchange_success - 0 - заявка выполнена, 1 - заявка не выполнена accrued - 0 - не начислено вознаграждение, 1 - начислено partner_reward - партнерская сумма user_hash - хэш пользователя user_ip - IP-адрес пользователя status - статус заявки statuses - список изменения статусов time - время изменения статуса date - дата изменения статуса status - статус заявки ``` ### get\_partner\_payouts Список запросов от пользователей на вывод денежных средств Параметры запроса: ``` start_time - unix-время с которого выводить (фильтр, необязательный параметр) end_time - unix-время до которого выводить (фильтр, необязательный параметр) limit - количество выводимых (фильтр, необязательный параметр) id - ID заявки (фильтр, необязательный параметр) ``` Ответ: ``` items - список id - ID заявки time - время выплаты date - дата выплаты method_id - валюта выплаты account - счет выплаты pay_amount - сумма выплаты pay_currency_code - код валюты выплаты original_amount - оригинальная сумма выплаты original_currency_code - оригинальный код валюты выплаты status - статус заявки. 0 в ожидании, 1 - выплачено, 2 - отменено ``` ### add\_partner\_payout Создание запроса на выплату параметры запроса: ``` method_id - ID валюты выплаты account - номер счета для выплаты ``` ответ: ``` payout_id - ID выплаты ``` ## Ответы от API при ошибках ### **Api disabled**
Возможные причины ошибки и методы их устранения: * Указаны некорректные авторизационные данные из раздела "**API**" для пользователя, который работает с API
* Не разрешена работа с API в настройках пользователя в разделе "**Пользователи**"
### Пустой ответ
* Запрошенная информация отсутствует — проверьте передаваемые параметры ### No bid exists
* Запрошенная заявка не существует ### Method not supported
* Не активирован выбранный метод в разделе "**API**" для пользователя
### Direction not found
Не разрешен доступ к направлению обмена через API (при запросе направления обмена), необходимо разрешить доступ в настройках направления обмена, вкладка "**Ограничения и проверки**"
[^1]: ``` (для запроса курса обмена по конретному городе при работе с напарвлениями обмена с наличными ``` [^2]: нумерация полей может отличаться, указан пример --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://premium.gitbook.io/main/api-premium-exchanger/api-v1.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.