:orphan: :nosearch: .. remove orphan and nosearch and include in toctree after review. .. _mpos_integration_ru: mPOS API Ru ########### .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code Закрытие дня ============ **Описание закрытия дня** Деньги переводятся на расчетный счет торговца после закрытия дня. При неуспешном завершении процедуры закрытия дня или если процедура закрытия вовсе не инициируется торговцем, операция клиринга не производится, таким образом деньги не зачисляются на расчетный счет торговца. Если по какой-либо причине не удается провести закрытие дня, используя «Удаленное закрытие дня», необходимо провести операцию закрытия дня вручную через личный кабинет или обратиться за помощью в службу поддержки. Данная операция доступна не для всех эквайеров, за информацией обращайтесь в службу поддержки. Для закрытия дня доступны следующие способы: :ref:`manuallycloseday` :ref:`autocloseday` :ref:`autoclosedaytime` :ref:`apicloseday` .. _manuallycloseday: Принудительное закрытие дня --------------------------- Для принудительного закрытия дня менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется закрыть день. .. figure:: ../_static/images/mpos_integration/pic1.png :scale: 100 % :align: center :alt: pic1 close_day | .. figure:: ../_static/images/mpos_integration/pic2.png :scale: 100 % :align: center :alt: pic2 close_day На странице шлюза нажмите кнопку "Закрыть день" и подтвердите закрытие дня на всплывающем окне. На странице начнет отображаться окно "Закрытие дня для 'имя шлюза'", дождитесь завершения операции. .. figure:: ../_static/images/mpos_integration/pic3.png :scale: 100 % :align: center :alt: pic3 close_day После успешного закрытия дня на странице шлюза будет отображена информация о дате закрытия и сумме транзакций с момента последнего закрытия дня для данного шлюза до текущего закрытия дня. .. figure:: ../_static/images/mpos_integration/pic4.png :scale: 100 % :align: center :alt: pic4 close_day .. warning:: Во время закрытия дня шлюз блокируется и транзакции по нему проходить не будут. .. _autocloseday: Автоматическое закрытие дня --------------------------- Для автоматического закрытия дня менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется закрывать день автоматически. .. figure:: ../_static/images/mpos_integration/pic1.png :scale: 100 % :align: center :alt: pic1 close_day | .. figure:: ../_static/images/mpos_integration/pic2.png :scale: 100 % :align: center :alt: pic2 close_day На странице шлюза нажмите кнопку "Редактировать", поставьте галочку напротив пункта "Автоматическое закрытия дня" и нажмите "Сохранить". .. figure:: ../_static/images/mpos_integration/pic5.png :scale: 100 % :align: center :alt: pic5 close_day | При автоматическом закрытии дня оптимальное время закрытия выбирается системой автоматически (ближе к концу рабочего дня по МСК). .. warning:: Во время автоматического закрытия дня шлюз блокируется и транзакции по нему проходить не будут. После успешного автоматического закрытия дня на странице шлюза будет отображена информация о дате закрытия и сумме транзакций с момента последнего закрытия дня для данного шлюза до текущего закрытия дня. .. figure:: ../_static/images/mpos_integration/pic4.png :scale: 100 % :align: center :alt: pic4 close_day .. _autoclosedaytime: Автоматическое закрытие дня по заранее установленному времени ------------------------------------------------------------- | Для автоматического закрытия дня по заданному времени менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется закрывать день автоматически в установленное время. .. figure:: ../_static/images/mpos_integration/pic1.png :scale: 100 % :align: center :alt: pic1 close_day | .. figure:: ../_static/images/mpos_integration/pic2.png :scale: 100 % :align: center :alt: pic2 close_day | На странице шлюза нажмите кнопку "Редактировать", поставьте галочку напротив пункта "Закрывать день автоматически", появится пункт "Время закрытия дня", нужно выставить время закрытия дня, затем нажать "Сохранить". | Обратите внимание, что пункт "Автоматическое закрытия дня" должен быть выключен, иначе время закрытия дня будет выбрано автоматически системой. .. figure:: ../_static/images/mpos_integration/pic6.png :scale: 100 % :align: center :alt: pic6 close_day Закрытие дня будет выполняться в заданное время, после успешного закрытия дня на странице шлюза будет отображена информация о дате закрытия и сумме транзакций с момента последнего закрытия дня для данного шлюза до текущего закрытия дня. .. figure:: ../_static/images/mpos_integration/pic7.png :scale: 100 % :align: center :alt: pic6 close_day .. warning:: Во время автоматического закрытия дня по заданному времени шлюз блокируется и транзакции по нему проходить не будут. .. _apicloseday: Удаленное закрытие дня ---------------------- | Удаленное закрытие дня позволяет закрыть день сразу на всех шлюзах определенного терминала. Для этого необходимо для ВСЕХ шлюзов ассоциированных с терминалом установить в настройках "Удаленное закрытие дня". | Для удаленного закрытия дня менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется включить удаленное закрытие дня. .. figure:: ../_static/images/mpos_integration/pic1.png :scale: 100 % :align: center :alt: pic1 close_day | .. figure:: ../_static/images/mpos_integration/pic2.png :scale: 100 % :align: center :alt: pic2 close_day | На странице шлюза нажмите кнопку "Редактировать", поставьте галочку напротив пункта "Удаленное закрытие дня", при необходимости, задайте число дней через которое будет срабатывать автоматическое закрытие дня, начиная с последнего успешного удаленного закрытия дня - пункт "Максимальная задержка закрытия дня (дн.)", автоматически устанавливается 3 дня, затем нажмите "Сохранить". .. figure:: ../_static/images/mpos_integration/pic8.png :scale: 100 % :align: center :alt: pic8 close_day .. warning:: Во время удаленного закрытия дня шлюзы блокируются и транзакции по ним проходить не будут. | Для инициации Удаленного закрытия дня необходимо отправить HTTP запрос следующего вида: :: POST https://${hostname}/paynet/api/v2/close-day/{endpointId} | Аутентификация пользователя происходит по OAuth 1.0, описание: :ref:`oauth` **Тело запроса** | В теле запроса укажите данные со следующей структурой: :: { "day_close_request_id": {string}, "sale_approved_count": {string}, "sale_approved_sum": {string}, "reversal_approved_count": {string}, "reversal_approved_sum": {string} } +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | Имя свойства | Тип(длина) | Описание | +============================================+=================+===================================================================================+ | *Обязательные параметры* | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | day_close_request_id | string(8-32) | Уникальный идентификатор запроса. Может содержать буквы и цифры | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | *Необязательные параметры* | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | sale_approved_count | string | Число подтвержденных sale транзакций | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | sale_approved_sum | string | Сумма по подтвержденным sale транзакциям | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | reversal_approved_count | string | Число подтвержденных reversal транзакций | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ | reversal_approved_sum | string | Сумма по подтвержденным reversal транзакциям | +--------------------------------------------+-----------------+-----------------------------------------------------------------------------------+ **Тело ответа** | Пользователь генерирует идентификатор запроса и посылает запрос на закрытие дня. Если этот идентификатор используется впервые - начинается инициализация закрытия дня для гейта(ов), ассоциированного(ых) с переданным идентификатором терминала. Пользователю возвращается асинхронный ответ со статусом 'starting'. | Пример структуры ответа следующий: :: { "response": { "status": "starting", "gates": [ { "gateId": 193, "isDayClosing": true, "epntId": 1 }, { "gateId": 82, "isDayClosing": true, "epntId": 1 }, { "gateId": 317, "isDayClosing": true, "epntId": 1 } ] }, "theRequestSerialNumber": "00000000-0000-0000-0000-00000000001c" } +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Имя свойства | Тип | Описание | +===============================+==========+===================================================================================+ | status | string | Статус операции закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | gateId | long | Идентификатор шлюза по которому происходит закрытие дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | isDayClosing | boolean | Флаг закрытия дня, при значении true - шлюз заблокирован | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | epntId | long | Свойство, присваемое банком терминалу при его настройке в системе банка | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | theRequestSerialNumber | string | Серийный номер запроса закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Запрос с идентификатором day_close_request_id, уже использованным ранее, выполняет функцию статус-запроса. После первичного (инициирующего запроса) пользователь может продолжать посылать запросы по тому же адресу с тем же самым идентификатором запроса. В данном случае, этот идентификатор всегда будет ассоциирован с процедурой закрытия дня, которую он инициировал. Пока операция по закрытию дня в процессе выполнения - пользователю будет возвращаться асинхронный ответ со статусом 'processing'. | Пример структуры ответа следущий: :: { "response": { "status": "processing", "gates": [ { "gateId": 193, "isDayClosing": true, "epntId": 1 }, { "gateId": 82, "isDayClosing": true, "epntId": 1 }, { "gateId": 317, "isDayClosing": true, "epntId": 1 } ] }, "theRequestSerialNumber": "00000000-0000-0000-0000-00000000001e" } +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Имя свойства | Тип | Описание | +===============================+==========+===================================================================================+ | status | string | Статус операции закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | gateId | long | Идентификатор шлюза по которому происходит закрытие дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | isDayClosing | boolean | Флаг закрытия дня, при значении true - шлюз заблокирован | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | epntId | long | Свойство, присваемое банком терминалу при его настройке в системе банка | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | theRequestSerialNumber | string | Серийный номер запроса закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Информация о закрытом дне появится в ответе от сервера по мере ее поступления от процессоров (в случае одновременного закрытия нескольких гейтов). После закрытия дня гейта(ов) статус ответа примет значение 'finished', вне зависимости от того, завершилось ли закрытие дня на всех гейтах успешно, или часть гейтов (или все) закрылись с ошибкой. .. warning:: Если во время удаленного закрытия дня шлюз(ы) останутся в заблокированном состоянии (в теле ответа при "status": "finished" для шлюза - "isDayClosing": true), воспользуйтесь инструментом снятия блокировки в личном кабинете системы, который описан далее в этом разделе. | Пример структуры ответа следующий: :: { "response": { "status": "finished", "gates": [ { "gateId": 193, "isDayClosing": false, "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018", "epntId": 1, "saleApprovedCount": "2334", "saleAmount": "87328428482.00", "reversalApprovedCount": "123", "reversalAmount": "12393423.00", "code39": "000", "RRN": "2034829434" }, { "gateId": 82, "isDayClosing": false, "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018", "epntId": 1, "saleApprovedCount": "2334", "saleAmount": "87328428482.00", "reversalApprovedCount": "123", "reversalAmount": "12393423.00", "code39": "000", "RRN": "2034829434" }, { "gateId": 317, "isDayClosing": false, "gateCloseDate": "Mon Dec 10 14:44:21 MSK 2018", "epntId": 1, "saleApprovedCount": "2334", "saleAmount": "87328428482.00", "reversalApprovedCount": "123", "reversalAmount": "12393423.00", "code39": "000", "RRN": "2034829434" } ] }, "theRequestSerialNumber": "00000000-0000-0000-0000-00000000002c" } +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Имя свойства | Тип | Описание | +===============================+==========+===================================================================================+ | status | string | Статус операции закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | gateId | long | Идентификатор шлюза по которому происходит закрытие дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | isDayClosing | boolean | Флаг закрытия дня, при значении true - шлюз заблокирован | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | gateCloseDate | string | Дата закрытия дня шлюза | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | epntId | long | Свойство, присваемое банком терминалу при его настройке в системе банка | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | saleApprovedCount | string | Число подтвержденных sale транзакций | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | saleAmount | string | Сумма по подтвержденным sale транзакциям | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | reversalApprovedCount | string | Число подтвержденных reversal транзакций | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | reversalAmount | string | Сумма по подтвержденным reversal транзакциям | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | code39 | string | Результат закрытия, ответ банка на вызов процедуры закрытия гейта | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | RRN | string | Номер закрытия дня сгруппированный по ID терминала | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | theRequestSerialNumber | string | Серийный номер запроса закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Если во время выполнения процедуры закрытия дня пользователь посылает повторный запрос на закрытие дня с новым идентификатором запроса - сервер вернет ответ со статусом 'error' и с описанием ошибки. Использовать повторно идентификатор этого запроса для дальнейшего инициирования закрытия дня бессмысленно, т.к. статус ошибки - это финальный статус и идентификатор запроса всегда будет ассоциирован с этим запросом. | Пример структуры ответа следующий: :: { "response": { "status": "error", "errorCode": "99", "errorMessage": "gate is closing already" }, "theRequestSerialNumber": "00000000-0000-0000-0000-000000000020" } +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Имя свойства | Тип | Описание | +===============================+==========+===================================================================================+ | status | string | Статус операции закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | errorCode | string | Код ошибки | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | errorMessage | string | Описание ошибки | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | theRequestSerialNumber | string | Серийный номер запроса закрытия дня | +-------------------------------+----------+-----------------------------------------------------------------------------------+ | Если пользователь инициирует запрос с новым идентификатором запроса на терминал, по которому уже было закрытие дня, и часть ассоциированных с терминалом гейтов закрылись с ошибкой (и находятся в закрытом состоянии) - сервер пришлет ответ со статусом 'error' и соответствующим описанием ошибки. .. warning:: Для разрешения этой проблемы проведите операцию закрытия дня вручную в личном кабинете системы. Инструмент снятия блокировки для шлюза -------------------------------------- Если во время проведения удаленного закрытия дня, один или несколько шлюзов остались в заблокированном состоянии (в теле ответа при "status": "finished" для шлюза - "isDayClosing": true), Вы можете снять блокировку в личном кабинете системы и, при необходимости, закрыть день вручную. Для снятия блокировки на шлюзе менеджеру или его сотруднику в личном кабинете системы надо перейти в настройки шлюза, для которого требуется снять блокировку. .. figure:: ../_static/images/mpos_integration/pic1.png :scale: 100 % :align: center :alt: pic1 close_day | .. figure:: ../_static/images/mpos_integration/pic2.png :scale: 100 % :align: center :alt: pic2 close_day На странице шлюза нажмите кнопку "Locks", для вызова инструмента снятия блокировки. .. figure:: ../_static/images/mpos_integration/pic9.png :scale: 100 % :align: center :alt: pic9 close_day | .. figure:: ../_static/images/mpos_integration/pic10.png :scale: 100 % :align: center :alt: pic10 close_day В меню "Current locks" отображена текущая информация о блокировке шлюза: * Lock session ID - идентификатор сессии блокировки. * Start day closing date - дата начала закрытия дня. * Bank terminal lock status - блокировка терминала для проведения траназкций (Blocked/Free). * Initial gate job status - статус задачи по инициализации шлюза. * Close day job status - статус задачи по закрытию шлюза. * Is day closing - шлюз в стадии закрытия, т.е. находится ли в заблокированном состоянии (Y/N). Y - шлюз заблокирован, N - блокировки нет. Доступны следующие команды снятия блокировки: * CLEAR_TRANSACTION_LOCK - сбросить сессию из-за которой произошла блокировка. * CLEAR_INIT_ATTEMPT - сбросить статус задачи по инициализации шлюза. * CLEAR_CLOSING_DAY_ATTEMPTS - сбросить статус задачи по закрытию шлюза. * CLEAR_CLOSING_DAY_FLAG - сбросить задачу по закрытию шлюза, снять блокировку. Отметьте галочкой нужный пункт меню и нажмите кнопку "Update". После выполнения команды сброса, повторно откройте инструмент снятия блокировки и проверьте, что в меню "Current locks" изменился статус сбрасываемого параметра. Например, если шлюз был заблокирован, то после снятия блокировки параметр "Is day closing" = N. Инструмент отладки для удаленного закрытия дня ---------------------------------------------- | Чтобы воспроизвести вызов API, введите все данные из исходного запроса, включая маркеры проверки подлинности. Не забудьте установить nonce и timestamp значения, которые Вы использовали. Запрос, подписанный с помощью :ex:`OAuth`, должен совпадать со значением в инструменте отладки ниже, вне зависимости от используемой библиотеки и языка программирования. Если подписи отличаются, значит в Вашем коде подписи :ex:`OAuth` есть ошибка. .. raw:: html :file: ../_static/examples/close_day_Api_Debug.html