Интеграция ELMA365 с 1С

Система «1С:Предприятие 8» является открытой системой. Она предоставляет возможность для интеграции практически с любыми внешними программами и оборудованием на основе общепризнанных открытых стандартов и протоколов передачи данных.
С помощью средств платформы «1С:Предприятие 8» можно организовать обмен файлами различных форматов, осуществлять доступ ко всем объектам системы из внешних приложений, поддерживать различные протоколы обмена и стандарты взаимодействия с другими подсистемами (XML, JSON и т. п.), работать с Интернетом и электронной почтой.

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

Платформа «1С:Предприятие 8» поддерживает в прикладных решениях возможность создания web- и HTTP-сервисов и работу с внешними web- и HTTP-сервисами. Так же поддерживается доступ внешних систем к данным приложений 1С по протоколу OData.

В нашем случае для настройки обмена данными с системой ELMA365 будет использоваться HTTP-сервис и протокол oData. Для POST-запросов из 1С в ELMA365 будем использовать библиотеку ConnectorHTTP.

Для начала рассмотрим HTTP-сервис. В платформе 1С, в дополнение к автоматическому REST интерфейсу, существует возможность создания собственных произвольных HTTP-сервисов в прикладном решении. Разработчик самостоятельно, с помощью встроенного языка, формирует ответ на запрос. При этом есть удобный доступ к телу, заголовкам и строке исходного запроса, а также есть возможность формировать код, тело и заголовки ответа по своему усмотрению.

Приступим к созданию нового HTTP-сервиса и напишем функции для Get запроса.

В ветке “Общие” открываем HTTP-сервисы и создаём новый сервис. В свойстве “Корневой URL” обязательно указываем название сервиса. Это свойство отвечает за формирование URL-адреса к методам сервиса.


Далее создаём шаблон URL (Getcontractors) и методы Get/Post и указываем в обработчике ссылки на функции 1С, которые будут формировать ответ на запрос.

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

Следующим механизмом для интеграции с внешними системами, который мы рассмотрим, является - REST интерфейс. Платформа может автоматически формировать REST интерфейс для всего прикладного решения. После того, как прикладное решение опубликовано на веб-сервере, сторонние системы могут обращаться к нему через REST интерфейс с помощью HTTP запросов. В качестве протокола доступа платформа использует протокол OData версии 3.0. Это открытый веб-протокол для запроса и обновления данных. Он позволяет оперировать данными, используя в качестве запросов HTTP-команды. Получать ответы можно в формате Atom/XML или JSON.

Для удобства редактирования состава стандартного интерфейса oData воспользуемся внешней обработкой “Редактирование состава интерфейса OData”, которая позволит выбрать метаданные для публикации REST интерфейса OData.

Но прежде чем приступить, для использования http-сервисов и интерфейса OData нам необходимо опубликовать базу, а для этого нам потребуется веб-сервер — Apache 2.2 (или 2.4.) Для публикации на веб-сервере необходимо зайти в меню «Администрирование»->»Публикация на веб-сервере» -> заполняем данные -> "Опубликовать".



После публикации на веб-сервере рекомендуется перезапустить Apache, в всплывающем окне нажимаем “Нет” и открываем диспетчер задач, вкладку “Службы”, после чего производим перезапуск службы Apache 2.2. т.к. посредством 1С перезапуск службы Apache не всегда может выполниться корректно.


После публикации на веб-сервер, наша информационная система будет доступна по адресу. Например: https://vm-1c_for_elma.com/1c_for_elma, где:

• vm-1c_for_elma.com - доменное имя сервера;
• 1c_for_elma - имя указанное при публикации;

Закончим настройку состава интерфейса oData. После добавления внешней обработки для редактирования состава интерфейса oData при отладке или открытии через веб нажимаем на “Сервисы” → “Редактирование состава стандартного интерфейса oData” и отмечаем необходимые справочники/документы и регистры, к которым мы будем обращаться через протокол oData.


Обращения через протокол oData производятся по следующему адресу (пример для получения данных справочника Товары в формате json): https://vm-1c_for_elma.com/1c_for_elma/odata/standard.odata/Catalog_Контрагенты?$format=json, где:

• vm-1c_for_elma.com - доменное имя сервера;
• 1c_for_elma - имя указанное при публикации;
• odata/standard.odata/ - обязательная часть, признак обращения к интерфейсу OData;
• Catalog_Контрагенты - имя ресурса сформированное по правилу;
• ?$format=json - указывает возвращаемые данные в формате json.

Полную информацию о правилах доступа и параметрах обращения к ресурсам через oData можно ознакомиться по следующей статье.

В случае с HTTP-сервисом, например, GET-запрос для получения данных контрагента по ИНН, обращение будет по следующему адресу: https://vm-1c_for_elma.com/1c_for_elma/hs/contractor/0997918926, где:

• vm-1c_for_elma.com - доменное имя сервера;
• 1c_for_elma - имя указанное при публикации;
• hs - обязательный сегмент пути, дающий понять, что работаем мы именно с HTTP-сервисом;
• contractor - корневой URL http-сервиса;
• 0997918926 - ИНН нашего контрагента.

Настройка ELMA365
Рассмотрим пример обращения при создании элемента приложения "Компания" в ELMA365 через протокол oData для поиска контрагентов со строковой функцией substringof. В данном запросе мы будем получать все компании из справочника 1С “Контрагенты”, где введенная строка будет являться подстрокой “Description” - Наименование.



Рассмотрим реализацию данной интеграции. Откроем форму создания. Запишем следующие переменные:



Напишем запрос, выполняющийся на сервере:

Код:

interface ReqData {
    ref_Key: string,
    full_name: string,
    short_name: string,
    inn: string,
    kpp: string
}

async function get_companies(): Promise<void> {
    const input_name = Context.data.search_string;
    const request = await fetch(`https://vm-1c_for_elma.com/1c_for_elma/odata/standard.odata/Catalog_Контрагенты?$filter=substringof('${input_name}', Description) eq true`, {
        method: 'GET',
        headers: {
            "Authorization": `Basic ${btoa('Login:Password')}`,
            "Accept": 'application/json'
        }
    });
    if (request.ok) {
        const req = await request.json();
        if (req.value.length > 0) {
            const data: ReqData = req.value.map((i: any) => {
                return {
                    ref_Key: i['Ref_Key'],
                    full_name: i['Description'],
                    inn: i['ИНН'],
                    kpp: i['КПП']
                }
            });
            ViewContext.data.data_1c = data;
        }
        else {
            ViewContext.data.data_1c = [];
        }
    }
    else {
        throw new Error('Ошибка выполнения запроса: ' + request.status + ' ' + request.statusText);
    }
}

В данном случае рассматривается Аутентификация 1С:Предприятия. При использовании этого вида аутентификации средствами 1С:Предприятия в конфигураторе для пользователя задается имя пользователя и пароль. Для аутентификации запроса необходимо добавить заголовок Authorization, который будет содержать разделенные двоеточием имя пользователя и пароль в кодировке Base64:

Код:

                headers: {
                    "Authorization": `Basic ${btoa('Login:Password')}`
                

Примечание: функция btoa не предусмотрена для кодирования кириллицы в Base64. Необходимо использовать латинские символы для возможности закодировать логин и пароль через функцию btoa.
Либо сразу в строке авторизации указывать закодированную строку. Например:

Код:

"Authorization": `Basic TG9naW46UGFzc3dvcmQ=`,

Функции, выполняющиеся на стороне клиента:

Код:

declare const clear_all: Function;
declare const add_info: Function;


async function start_prepare(): Promise<void> {
    if (Context.data.search_string && Context.data.search_string.length >= 3) {
        if (ViewContext.data.get_new_data == true) {
            await Server.rpc.get_companies();
            if (ViewContext.data.data_1c) {
                clear_all();
                add_info(ViewContext.data.data_1c);
            }
            else {
                clear_all();
            }
        }
    }
    else {
        clear_all();
    }
}


async function ready_element(element_id: string): Promise<void> {
    ViewContext.data.get_new_data = false;
    if (element_id) {
        const el = ViewContext.data.data_1c.find((f: any) => f.ref_Key == element_id);
        if (el) {
            clear_all();
            Context.data.full_company_name = el.full_name;
            Context.data.inn = el.inn;
            Context.data.kpp = el.kpp;
        }
    }
    ViewContext.data.get_new_data = true;
}

Так же создаём на форме создания Виджет “Код” со следующим содержимым:

Код:

<style>
    #help-menu {
        display: flex;
        flex-direction: column;
        position: absolute;
        top: 35px;
        max-height: 50vh;
        overflow-y: auto;
        z-index: 100;
    }
    .menu-element {
      background-color: #f1f1f1;
      min-width: 160px;
      box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2);
      z-index: 100;
    }

    .menu-element span {
      color: black;
      padding: 12px 16px;
      text-decoration: none;
      display: block;
      cursor: pointer;
    }

    .menu-element span:hover {
      background-color: #c6c6c6;
    }

    .dropdown span:hover {
      background-color: #ddd;
    }
</style>

<script>
    $(document).ready(function(){
        let intervalId = setInterval(function() {
            const element = $('#search_string');
            if (element.length > 0) {
                const parent = element.parent();
                if (parent.length > 0) {
                    parent.append($('<div id="help-menu"></div>'));
                    clearInterval(intervalId);
                }
            }
        }, 500)
    })
    function add_info(all_data) {
        const menu = $('#help-menu');
        if (menu.length > 0 && all_data.length > 0) {
            for (let el of all_data) {
                let new_position = $('<div class="menu-element" onclick=<%=Scripts%>.ready_element("' + el.ref_Key + '")><span class="menu-text">' + el.full_name + '(' + el.inn + ')' + '</span></div>');
                new_position.attr('data-guid', el.ref_Key);
                menu.append(new_position);
            }
        }
    }
    function clear_all() {
        const all_menu = $('.menu-element');
        if (all_menu.length > 0) {
            all_menu.remove();
        }
    }
    function test() {
        alert('click');
    }
</script>

Подобные запросы так же можно производить для поиска товаров при формировании Лида.



Теперь перейдём к ситуации, когда необходимо после формирования счета в ELMA365 осуществить его отправку бухгалтеру в 1С.



Напишем сценарий для бизнес-процесса:

Код:

async function sendData(): Promise<void> {

        const app = await Context.data.outgoinginvoice.fetch();
    const company = await app.data.Contractor?.fetch();
    const agreement = await app.data.Agreement?.fetch();
    const request = await fetch(`https://vm-1c_for_elma.com/1c_for_elma/odata/standard.odata/Catalog_СчетаПокупателям`, {
        method: 'POST',
        headers: {
            "Authorization": `Basic ${btoa('Login:Password')}`,
            "Accept": 'application/json'
        },
        body: JSON.stringify({
            'Ref_Key': app.id,
            "Description": app.data.__name,
            "Контрагент_Key": company?.data.guid || '',
            "ДатаВыставленияСчета": app.data.__createdAt.format(),
            "ИтоговаяСумма": app.data.Amount?.asFloat() || 0,
            "Договор": agreement?.data.__name || 'Без названия',
            "Статус": "НеОплачен",
            "ОплатаДо": app.data.PaymentDate?.format() || app.data.__createdAt.format()
        }
        )
    });
    if (request.ok) {
        Context.data.Comment = `Данные по счету ${app.data.__name} успешно отправлены в 1С!`;
    }
    if (!request.ok) {
        Context.data.Comment = `Ошибка запроса данных: ${request.status} ${request.statusText}`;
    }
}

По результатам данного запроса в 1С будет сформирован счёт на оплату в справочнике “Счета покупателям”.



Напоследок рассмотрим ситуацию, когда 1С будет инициировать отправку данных в ELMA365. Например, в 1С приходит платёж по определенному счёту, и его необходимо передать в ELMA365.

Для написания запроса для отправки данных будем использовать ConnectorHTTP для удобной работы с запросами и ответами в формате JSON.

Подробнее о данной библиотеке на 1С по ссылке на GitHub.

Отправка данных так же может настраиваться автоматически, в качестве примера это реализовано через кнопку “Отправить”.

Для выполнения запроса по отправке данных в ELMA365 напишем следующую функцию 1С, выполняемую на сервере.
Структура JSON и наименование свойств в данном случае определены структурой модуля на стороне ELMA365, который принимает данные значения.

Код:

&НаСервере
Процедура ОтправитьПОСТ()

    ДокументСсылка = Документы.Платеж.НайтиПоНомеру(Объект.Номер);
    ГУИД = ДокументСсылка.УникальныйИдентификатор();
    Объект.ИдентификаторОбъекта = ГУИД;

    СправочникСсылка = Справочники.СчетаПокупателям.НайтиПоКоду(Объект.СчетПокупателю.Код);
    ГУИД_Счета = СправочникСсылка.УникальныйИдентификатор();
    Объект.ИдентификаторСчета = ГУИД_Счета;

    КомпанияСсылка = Справочники.Контрагенты.НайтиПоКоду(Объект.Контрагент.Код);
    ГУИД_Компании = КомпанияСсылка.УникальныйИдентификатор();
    Объект.ИдентификаторКомпании = ГУИД_Компании;


    СоответствиеДанные = Новый Структура;
    СоответствиеДанные.Вставить("_totalAmount", Объект.Сумма);
    СоответствиеДанные.Вставить("_paymentDate", Формат(Объект.ДатаОплаты, "ДФ=yyyy-MM-ddTHH:mm:ss") + ".300Z");
    СоответствиеДанные.Вставить("_guid_1c", Объект.ИдентификаторОбъекта);
    СоответствиеДанные.Вставить("_guid_account", Объект.ИдентификаторСчета);
    СоответствиеДанные.Вставить("_guid_company", Объект.ИдентификаторКомпании);

    ИмяСервера = "https://elmaserver.elma365.ru";
    Токен = "55ec3251-ab91-4d36-aab6-e338602d11bd";

    СтрокаДанные = КоннекторHTTP.ОбъектВJson(СоответствиеДанные);
    ДополнительныеПараметры = Новый Структура;
    ДополнительныеПараметры.Вставить("Заголовки", Новый Соответствие);
    ДополнительныеПараметры.Заголовки.Вставить("Authorization", "Bearer " + Токен);


        Ответ = КоннекторHTTP.Post(ИмяСервера + "/api/extensions/189b0262-78c5-4f14-bf03-30c0635e314d/script/create_payment", СтрокаДанные, ДополнительныеПараметры);

    Если Ответ.КодСостояния = 200 Тогда

        СтрокаОтвет = КоннекторHTTP.КакТекст(Ответ);
        Соответствие = КоннекторHTTP.JsonВОбъект(СтрокаОтвет);

        Объект.ИдентификаторЭлемента = Соответствие["item"]["app_id"];

    Иначе

    КонецЕсли;


КонецПроцедуры

В случае, если работа с элементами будет осуществляться через Web API и стандартную функцию “Создать элемент” в ELMA365, то структура будет начинаться со следующего:

Код:

СоответствиеДанные = Новый Структура;
СоответствиеДанные.Вставить("context", Новый Соответствие);
СоответствиеДанные.context.Вставить("__name", Объект.Номер);
СоответствиеДанные.context.Вставить("__directory", Неопределено);
СоответствиеДанные.context.Вставить("__externalProcessMeta", Неопределено);
СоответствиеДанные.context.Вставить("__externalId", Неопределено);

В результате выполнения нашего запроса будет сформирован элемент приложения “Платежи” в ELMA365.

Добрый день, а каким образом мигрировать данные из 1С в ELMA365, имея при этом открытый протокол обмена "odata" что описан в методе

Добрый вечер. Одним из вариантов может стать отправка Get запроса к определенному справочнику/документу, например, Catalog_Контрагенты?$format=json и разобрать весь JSON, создавая элемент приложения для каждого объекта 1С.
Ещё как быстрая альтернатива миграции данных - выгрузить справочник из 1С в формате XLSX, подкорректировать его структуру и в соответствующем справочнике, настроенном для миграции, внутри ELMA365 использовать "Импорт данных", загрузив в систему данные для приложения.

Добрый день! Подскажите, а файлы из 1С если передавать через HTTP в бинарном виде, в елме есть стандартный скрипт чтения/преобразования бинарных данных обратно в файл или писать самому надо?

Добрый вечер! Да, при передаче из 1С файлов, закодированных в Base64, есть возможность их чтения и преобразования. Решается написанием функции на TypeScript для преобразования строки формата Base64 в ArrayBuffer, а далее использованием метода FileField.create, позволяющим создавать файлы из ArrayBuffer в папке экземпляра процесса. Подробнее о методе FileField.create - https://tssdk.elma365.com/ru/interfaces/_02_types_.filefield.html#create

Добрый день! Подскажите пожалуйста через Web api создавать документы из 1с - научился. Отправлять из ELMA тоже вроде в 1С получилось по Вашему "гайду". Но вот никак не пойму как отправить файл из 1С в ELMA(и в обратную сторону) Вроде нашел метод в справке. Как просто файл создать в ELMA(и потом я так понимаю уже ид того созданного файла мы прикрепляем в поле элемента в ELMA) /pub/v1/disk/directory/{id}(тут сгенерированный нами ИД например Новый УникальныйИдентификатор() как я понял)/upload. Но не получается никак файл отправить. Есть у Вас расширения Вашего примера с передачей файла? Очень поможете

Добрый день! Для отправки файла из 1С в ELMA365 можно воспользоваться вышеупомянутым методом Web API с загрузкой файлов. Подробнее о загрузке файла и его использовании можно изучить в следующей статье: https://community.elma365.com/ru/threads/182/
Соответственно, на стороне 1С нужно будет на внутреннем языке сформировать POST запрос.
Другим способом для передачи файла через строку формата ArrayBuffer - использование собственных методов. Система предоставляет возможность создавать пользовательские модули и собственные методы. Подробнее о реализации своих методов так же есть статья: https://community.elma365.com/ru/threads/108/
При такой реализации, которая была упомянута выше сообщением, необходимо будет написать метод с функцией на TypeScript для преобразования строки формата Base64 в ArrayBuffer, а далее использованием метода FileField.create, позволяющим создавать файлы из ArrayBuffer в папке экземпляра процесса.

Для отправки файла из ELMA365 в 1С тут вы сами выбираете более предпочтительную реализацию для вас со стороны 1С. Либо собственный HTTP сервис, либо отправлять POST запрос со строкой формата ArrayBuffer через OData в объект "Присоединенные файлы". У них имеется "ТекстХранилище_Base64Data", где содержимое файла в Base64.

Подскажите, пожалуйста, а как создавать вот этот скрипт (который принимает запрос из 1С)? Поискал, как будто этот кусок пропущен просто
/api/extensions/189b0262-78c5-4f14-bf03-30c0635e314d/script/create_payment

Это метод API в модуле.
https://elma365.com/ru/help/platform/extention-api.html

"... POST запрос со строкой формата ArrayBuffer через OData в объект "Присоединенные файлы". У них имеется "ТекстХранилище_Base64Data", где содержимое файла в Base64."
Можно по подробней:
- так всё таки в каком формате отправлять файл - Base64 или ArrayBuffer;
- объект "Присоединенные файлы" - такого справочника нет или это не справочник, а что-то другое, например Регистр какого-то типа? Есть такой объект - Catalog_ДоговорыКонтрагентовПрисоединенныеФайлы, может Вы его имели ввиду?;
- а можно пример кода отправки файла в 1С в карточку договора например.