# Организация взаимодействия {#ru_xero_integration}

статья с инструкциями по подключению и настройке основных функциональных возможностей приложения Ecommpay для работы с платформой Xero

## Подключение приложения {#section_mtz_llm_b2c .section}

Чтобы обеспечить автоматическую передачу в облачную платформу Xero информации о платежах, проводимых через платформу Ecommpay \(по актуальным проектам\), и доступность других поддерживаемых возможностей, прежде всего необходимо подключить веб-приложение от Ecommpay к используемой со стороны мерчанта экосистеме в платформе Xero. Для этого следует:

1.  Обеспечить наличие учётной записи портала [Xero Developer](https://developer.xero.com/) и учётной записи интерфейса [Dashboard](ru_dbl_about.md) для мерчантов Ecommpay.
2.  Убедиться, что при подключении приложения от Ecommpay не будет превышено ограничение платформы Xero на количество одновременно используемых сторонних веб-приложений. Если это ограничение может быть превышено, отключить, как минимум, одно из других сторонних приложений.

3.  Подключить веб-приложение.

    1.  Инициировать подключение веб-приложения под учётной записью Xero.
        1.  Открыть интерфейс Xero с использованием учётной записи портала Xero Developer.
        2.  Открыть страницу [https://xero-app.ecommpay.com](https://xero-app.ecommpay.com/) \(в отдельной вкладке браузера\).
        3.  Щёлкнуть кнопку **Login with Xero** на открывшейся странице.
        4.  Предоставить Ecommpay доступ к информации об учётной записи Xero и целевых организациях, для которых актуален обмен информацией между платформами Ecommpay и Xero.

            Для этого необходимо выбрать в выпадающем списке целевые организации, предоставить доступ к информации о них, щёлкнув **Allow access**, и сохранить изменения, щёлкнув **Continue with organisations**.

    2.  Обеспечить возможность обмена данными между платформами Ecommpay и Xero.

        Для этого следует указать на странице с параметрами соединения необходимые сведения:

        -   **Environment** — режим работы веб-приложения: рабочий \(`live`\) или тестовый \(`sandbox`\). Стоит учитывать, что для работы в тестовом режиме должен быть настроен отдельный тестовый проект в платформе Ecommpay.
        -   **Secret** — секретный ключ, полученный от Ecommpay и ассоциированный с учётной записью Dashboard, токен которой указывается в поле **Token** в профиле учётной записи интерфейса Dashboard платёжной платформы Ecommpay \([подробнее](ru_dbl_api_interaction.md#)\).
        -   **Token** — токен учётной записи Dashboard в платформе Ecommpay, используемый для работы с Data API.

    ![](images/ecommpay/xero/xero_connection.svg)

4.  Установить соединение, щёлкнув кнопку **Continue**.
5.  Убедиться, что подключение установлено.

    Если подключение выполнено, в интерфейсе Xero открывается страница со свойствами веб-приложения от Ecommpay \(с активной вкладкой **Settings**\).

    Если подключение не выполнено, в интерфейсе Xero отображается сообщение об ошибке \(список возможных ошибок представлен [на отдельной странице](ru_dbl_api_interaction.md#section_gxv_5mh_smb)\). Например, ошибка **401 Authorization Required** свидетельствует об отказе в доступе, связанном с указанием некорректного токена или секретного ключа. В таком случае необходимо указать корректные данные и попробовать установить подключение повторно.


## Настройка взаимодействия между платформами {#section_e34_dfj_df2c .section}

Чтобы начать работу с подключённым приложением от Ecommpay, необходимонастроить взаимодействие между платформами Ecommpay и Xero. Для этого следует:

1.  Открыть приложение от Ecommpay и перейти на вкладку **Settings**.
2.  Выбрать способ синхронизации.

    Для этого необходимо включить переключатель **I want to synchronize settlements with XERO** и выбрать в выпадающем списке **Synchronization interval** целевой способ синхронизации:

    -   По событиям \(`Live sync`\) — с передачей сведений о каждой операции непосредственно после её выполнения \(при этом в интерфейсе Xero такие сведения могут отображаться с задержкой до 10 минут\).
    -   По периодам \(`Daily, Weekly, Monthly`\) — с передачей сведений о всех релевантных операциях по итогам заданного календарного периода с использованием следующего базового расписания:

        -   `Daily` — начиная с 01:00 UTC каждый день по итогам предыдущего дня,
        -   `Weekly` — начиная с 02:00 UTC каждый понедельник по итогам предыдущей недели,
        -   `Monthly` — начиная с 03:00 UTC каждое 1-е число календарного месяца по итогам предыдущего месяца.
        При синхронизации таким способом в первую группу релевантных операций попадают только те, которым в платформе присваивается итоговый статус `Success` с момента сохранения вносимых изменений \(и регистрации этих сведений в платформе Ecommpay\) и до конца заданного календарного периода, в то время как последующие группы охватывают полные периоды. Информация о первой группе таких операций отправляется по завершении первого периода \(даже если он неполный\).

    ![](images/ecommpay/xero/synchronisation_toggle.svg)

3.  Настроить банковские и расчётные счета \(для каждой из используемых валют, в которых выполняются операции через платформу Ecommpay\), а также резервный расчётный счёт \([подробнее](ru_xero_accounts.md#)\).

    Для задания счёта в конкретной валюте необходимо выбрать соответствующие значения в выпадающих списках:

    -   **Currency** — код валюты \(при этом одна валюта может использоваться только один раз; справочник валют представлен [в отдельной статье](ru_currency_codes.md)\).
    -   **Settle to Bank Account** — название внутреннего счёта в Xero с реквизитами банковского счёта мерчанта \(для расчётов в выбранной валюте\).
    -   **XERO Clearing Account** — название внутреннего промежуточного счёта мерчанта в платформе Xero, используемого для клиринга операций, которые были выполнены через платформу Ecommpay \(в выбранной валюте\).

    Для задания резервного расчётного счёта необходимо выбрать в выпадающем списке **Fallback clearing account** один из промежуточных счетов в качестве резервного.

    ![](images/ecommpay/xero/accounts_configuration.svg)

4.  При необходимости, задать условия фильтрации операций по проектам.

    Для задания отдельного условия фильтрации по конкретному проекту необходимо указать его идентификатор в поле **Enter the project\_id, press Enter, and save the changes below** и нажать клавишу **Enter**. Если актуально указать более одного идентификатора, такую процедуру следует повторить для каждого из них — корректно переданные значения должны отображаться отдельными условиями над этим полем.

    ![](images/ecommpay/xero/filtration_settings2.svg)

5.  При необходимости, настроить возможность проведения оплат по ссылкам из интерфейса Xero \([подробнее](ru_xero_integration.md#)\).

6.  Сохранить изменения, щёлкнув кнопку**Save changes**.
7.  По возможности проверить, что изменения применены и синхронизация обеспечена.

    Для этого можно:

    1.  Проверить \(например, через интерфейс Dashboard платёжной платформы Ecommpay\), что после завершения настройки и до заданного времени синхронизации \(или к текущему времени, если была выбрана синхронизация по событиям\) по одному из целевых проектов была выполнена хотя бы одна финансовая операция.
    2.  Проверить наличие записей о выполненной синхронизации в веб-приложении от Ecommpay для платформы Xero — на вкладке **Monitoring**. Каждая из таких записей должна включать в себя информацию о дате и времени синхронизации, её статусе \(`Success` или `Failed`\) и количестве операций, по которым были переданы сведения в платформу Xero. В случаях с ошибками синхронизации в отчётах могут указываться причины таких ошибок. В случаях, когда количество операций равно нулю, записи о синхронизации не отображаются.
    ![](images/ecommpay/xero/monitoring_tab.svg)


![](images/ecommpay/xero/synchronisation_toggle.svg "Выбор способа синхронизации")

![](images/ecommpay/xero/accounts_configuration.svg "Настройка счетов")

![](images/ecommpay/xero/monitoring_tab.svg "Контроль синхронизации")

**На уровень выше:**[Интеграция с платформой Xero](ru_xero.md)

## Настройка платёжных сервисов {#ru_xero_invoices_setup}

Чтобы проводить оплаты с формированием и отправкой платёжных ссылок из интерфейса Xero и использованием платёжной формы Payment Page от Ecommpay, необходимо настроить работу платёжных сервисов, обеспечивающих отправку запросов на проведение платежей между платформами Xero и Ecommpay. При этом для проведения разовых оплат достаточно настроить платёжный сервис `Ecommpay`, а для проведения повторяемых оплат с использованием методов Direct Debit BACS и Direct Debit SEPA помимо сервиса `Ecommpay`необходимо настроить также сервисы для этих методов.

Чтобы настроить актуальные платёжные сервисы, следует:

1.  Сформировать в веб-приложении от Ecommpay ссылки для использования актуальных платёжных сервисов \(по каждому из актуальных проектов в платформе Ecommpay\).

    Для этого необходимо:

    1.  Открыть веб-приложение и перейти на вкладку **Settings**.
    2.  Включить необходимые переключатели:
        -   **I want to offer Ecommpay as a payment service on XERO invoices** — для использования Ecommpay в качестве платёжного сервиса при выставлении счетов на оплаты через интерфейс Xero;
        -   **I want to offer Ecommpay Direct Debit \(SEPA and BACS\) as payment services provider on Xero invoices** — для использования методов Direct Debit BACS и Direct Debit SEPА.
    3.  Указать идентификатор и ключ рабочего проекта в полях **Project ID** и **Project Secret**.
    4.  Сохранить изменения, щёлкнув кнопку **Save changes**.
    ![](images/ecommpay/xero/provider_settings.svg)

2.  Открыть страницу управления платёжными сервисами в интерфейсе Xero.

    Для этого следует:

    1.  Открыть интерфейс Xero с использованием учётной записи портала Xero Developer.
    2.  Открыть раздел со свойствами целевой организации, щёлкнув в левом верхнем углу интерфейса её название и выбрав в открывшемся контекстном меню раздел **Settings**.
    3.  Открыть подраздел со свойствами для управления платёжными сервисами, щёлкнув в группе **Features** свойство **Payment services**.
3.  Настроить каждый из актуальных сервисов в интерфейсе Xero.

    Для этого необходимо \(отдельно для каждого из настраиваемых сервисов\):

    1.  Скопировать ссылку из числа сформированных в веб-приложении от Ecommpay \(на шаге 1\) с помощью кнопки **Copy**.
    2.  Открыть окно добавления платёжного сервиса, перейдя в интерфейсе Xero на вкладку **Add new payment service** и щёлкнувпод панелями с доступными платёжными сервисами ссылку для добавления сервиса, не представленного в списке \(**If you're wanting a payment service that isn't listed, add another payment option**\).
    3.  Открыть окно для указания платёжного сервиса, активировав в открывшемся окне переключатель **Custom Payment URL** и щёлкнув кнопку **Continue**.
    4.  Указать в открывшемся окнеинформацию о сервисе, заполнив следующие поля:

        1.  **Account name** — внутреннее название сервиса \(например, `Ecommpay` или `Ecommpay BACS`\);
        2.  **Your custom URL** — ссылка, скопированная из приложения от Ecommpay;
        3.  **Pay now button text** — текст для кнопки, используемой в пользовательском интерфейсе Xero для перехода к интерфейсам подтверждения оплаты и проверки её статуса.

            **Прим.:** При проведении повторяемых оплат одна и та же типовая кнопка **Pay now** может использоваться как для подтверждения первичных оплат с регистрацией повторяемых списаний, так и для проверки статусов очередных списаний \(подробнее о таких сценариях — в статье [о проведении оплат](ru_xero_invoices.md#)\). В связи с этим для методов Direct Debit рекомендуется использовать для этой кнопки такой текст, который позволит избежать недопониманий со стороны пользователей, например **Processing with …**.

        ![](images/ecommpay/xero/payment_service1.svg)

    5.  Подтвердить добавление платёжного сервиса с помощью кнопки **Save**.
    6.  Убедиться в добавлении сервиса в платформу Xero.

        Об этом свидетельствует соответствующее уведомление в левом нижнем углу интерфейса и отображение записи об этом сервисе в таблице на вкладке **Manage connected services**.

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

    Для этого следует перейти на вкладку **Manage payment methods** и убедиться, что в группе платёжных сервисов **Connected payment apps** отображаются записи обо всех добавленных сервисах со статусом **On**.

    ![](images/ecommpay/xero/payment_service2.svg)

    Дополнительно для любого из методов Direct Debit можно выставить тестовый счёт со ссылкой на оплату и перейти по этой ссылке.Если платёжные сервисы настроены корректно — должна открываться платёжная форма Ecommpay для завершения оплаты, в ином случае — страница приложения от Ecommpay с записью о том, что платёжный метод не доступен \(**Payment method not enabled**\).


![](images/ecommpay/xero/manual_invoice_first_user_2.svg "Подтверждение корректности настройки ")

![](images/ecommpay/xero/payment_service3.svg "Уведомление о недоступности метода")

![](images/ecommpay/xero/provider_settings.svg "Формирование ссылок")

![](images/ecommpay/xero/payment_service1.svg "Добавление платёжного сервиса")

![](images/ecommpay/xero/payment_service2.svg "Проверка состояния платёжных сервисов")