Зміст

Загальні відомості

API (Application Programming Interface) це готовий інтерфейс за допомогою якого дані програми за допомогою розробника можна пов’язати із зовнішніми програмами (наприклад, з сайтом, мобільним додатком і т.д.).

У BAF використовується REST API, призначений для роботи через web. Для доступу до даних використовується протокол OData, що дозволяє програмі працювати безпосередньо з даними програми, до яких дозволено доступ і отримувати потрібну інформацію (наприклад, відображати в мобільному додатку час запису клієнта, інформацію про взаєморозрахунки по ньому, графік роботи потрібного лікаря і т.д. з Єнота, або передавати в банк інформацію з відомості щодо нарахування зарплати).

В цей момент API Єнота відкритий тільки для читання інформації, послуга надається користувачам виділених серверів. Розширення можливостей доступу та використання послуги для клієнтів на загальних серверах можливе за індивідуальною домовленістю.

Технічна інформація

REST інтерфейс дозволяє читати дані BAF, змінювати їх, створювати нові об’єкти даних та видаляти існуючі.

Ви можете використовувати інтерфейс REST для таких завдань як:

Інтеграція прикладного рішення з інтернет-сайтами та інтернет-магазинами;
Реалізація сторонніми засобами додаткової функціональності прикладного рішення без зміни конфігурації;
Завантаження даних у прикладне рішення та вивантаження даних з нього;
Інтеграція прикладного рішення з корпоративними системами, можливо, навіть без додаткового програмування.

Типові операції, що виконуються через інтерфейс REST це:

Отримання списку документів, довідників, записів регістру відомостей тощо, можливо з фільтром;
Отримання даних елемента довідника, документа (за посиланням), даних запису незалежного регістру відомостей (за ключем), даних набору записів підпорядкованого регістру (реєстратора);
Редагування даних одного елемента довідника, документа та іншого об’єкта посилання;
Створення нового елемента довідника, документа, набору записів;
Проведення одного документа, старт бізнес-процесу.

Як протокол доступу платформа використовує протокол OData версії 3.0. Це відкритий вебпротокол для запиту та оновлення даних. Він дозволяє оперувати даними, використовуючи як запити HTTP-команди. Отримувати відповіді можна у різних форматах, але поки що ми підтримуємо лише роботу з даними у форматі Atom/XML.

У платформі ми реалізували лише серверну частину REST сервісів. Тобто прикладне рішення може автоматично постачати свою функціональність через послуги REST. Для взаємодії зі сторонніми REST сервісами з BAF (для організації клієнтської частини) можна використовувати наявні у платформі засоби роботи з об’єктами НТТРЗ’єднання, НТТРЗапит та HTTPВідповідь.

Однак основне завдання REST інтерфейсу прикладних рішень бачимо в інтеграції зі сторонніми системами. І тут проблеми не виникає, адже клієнти OData існує практично для всіх значних платформ:

Мобільні: iOS, Windows Phone, Android;
Серверні/настільні: .NET, Java, PHP, Objective-C, Ruby, JavaScript;
Підтримка у системах керування вмістом (CMS): Drupal, Joomla.

Використовувати стандартний інтерфейс OData прикладного рішення просто:

Ви звертаєтесь із запитом до Служби тех. підтримки вказуючи які дані для публікації на зовнішньому ресурсі вам необхідні, а також для якого користувача мають бути доступні їх публікація;
Після цього об’єкти прикладного рішення стають доступними через цей інтерфейс;
Способи аутентифікації OData клієнтів повністю збігаються зі способами, які використовуються для вебсервісів;
OData клієнти можуть запросити через HTTP документ метаданих, який описує доступні об’єкти прикладного рішення;
OData клієнти виконують операції створення, читання, модифікації та видалення даних прикладного рішення.

У інтерфейсі REST доступні практично всі основні об’єкти конфігурації: довідники, документи, константи, перерахування, плани обміну, регістри накопичення, розрахунку, бухгалтерії та відомостей, віртуальні таблиці періодичного регістру відомостей, регістрів бухгалтерії та регістрів накопичення, плани рахунків, видів характеристик і видів розрахунку, бізнес-процеси, завдання та журнали документів.

Недоступними на цей час є звіти та обробки, команди, критерії відбору, регламентні завдання, зовнішні джерела даних та користувачі.

В інтерфейсі REST доступні реквізити об’єктів конфігурації, операції створення, читання, модифікації та видалення даних, а також деякі методи вбудованої мови. Наприклад:

Для документа – Post() і Unpost();
Для завдання – ExecuteTask();
Для бізнес-процесу – Start ();
Для регістру відомостей – SliceLast() та SliceFirst();
Для регістру накопичення та регістра бухгалтерії – Balance (), Turnovers () і Balance And Turnovers ();
Для регістру розрахунку – ScheduleData(), ActualActionPeriod(), <Ім’яПерерахунку>() і Base<Ім’я базового регістру розрахунку>().

Читання даних виконується GET-запитом. Наприклад, читання списку довідника Goods (тут і далі для стислості наведено лише заголовки запитів):

GET /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods

Наприклад, читання даних одного елемента довідника Goods за GUID’ом:

GET /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods(guid’7f4b5034-0331-11e3-b914-5404a6a68c42′)

Створення нового елемента даних виконується запитом POST. Як значення посилання передається нульовий GUID. При створенні та модифікації об’єктів значення властивостей передаються у тілі запиту у форматі XML (тут текст запиту наведено повністю):

POST /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods HTTP/1.1

Content-Type: application/atom+xml

DataServiceVersion: 3.0;NetFx

MaxDataServiceVersion: 3.0;NetFx

Accept: application/atom+xml,application/xml

Accept-Charset: UTF-8

User-Agent: 1C-Enterprise

Host: test-host:8090

Content-Length: 1610

<?xml version=»1.0″ encoding=»utf-8″?>

<entry xmlns=//www.w3.org/2005/Atom

xmlns:d=//schemas.microsoft.com/ado/2007/08/dataservices

xmlns:m=//schemas.microsoft.com/ado/2007/08/dataservices/metadata

xmlns:georss=//www.georss.org/georss

xmlns:gml=//www.opengis.net/gml>

<id />

</author>

<m:properties>

<d:Code>157</d:Code>

<d:DeletionMark>false</d:DeletionMark>

<d:Description>Майка синя</d:Description>

<d:IsFolder>false</d:IsFolder>

<d:Parent_Key m:null=»true» />

<d:Ref_Key m:type=»Edm.Guid»>00000000-0000-0000-0000-000000000000</d:Ref_Key>

<d:Артикул m:null=»true» />

<d:Поставщик_Key>F400322D-7AE8-4803-A7BE-0D80E525E8C2</d:Поставщик_Key>

</m:properties>

</content>

</entry>

Модифікація наявних даних виконується PATCH-запитом. Наприклад, зміна даних одного елемента довідника Goods за GUID’ом:

PATCH /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods(guid’7f4b5034-0331-11e3-b914-5404a6a68c42′)

Для видалення даних використовується DELETE-запит (позначка на видалення буде реалізована надалі окремою ODATA-операцією):

DELETE /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods(guid’7f4b5034-0331-11e3-b914-5404a6a68c42′)

Методи об’єктів вбудованої мови виконуються запитами POST. Наприклад, проведення документа:

POST /OData_Tests_Infobase/odata/standard.odata/Document_Invoice(guid’17ed2041-0345-11e3-b914-5404a6a68c42′)/Post()

У разі помилкової ситуації BAF повертає відповідь із HTTP-статусом 4XX або 5XX. Статус 4XX говорить про неправильні дії клієнта, статус 5XX – про помилку на сервері. У разі статусу 4XX BAF намагається допомогти клієнту зрозуміти причину помилки та може передати додатковий внутрішній код помилки та інформаційне повідомлення.

Під час читання та запису даних за допомогою REST інтерфейсу платформа виконує всі звичайні перевірки прав та викликає обробники подій, за винятком перевірки заповнення.

Під час роботи через REST інтерфейс підтримується оптимістичне блокування даних. При запиті даних (одного об’єкта чи списку) разом із ними платформа повертає значення поля (полів) ВерсіяДаних. У наступних запитах PUT, PATCH і DELETE з тими самими даними, можна передати BAF версію лічених даних. Якщо версія даних, що знаходяться в інформаційній базі, до цього моменту не змінилася, запитана дія виконується.

При отриманні списків даних можна використовувати стандартні умови фільтрації ODATA запитів. Наприклад, отримати товари, у яких ціна менша або дорівнює 3,5 або більше ніж 200:

GET /OData_Tests_Infobase/odata/standard.odata/Catalog_Goods?$filter=Price le 3.5 or Price gt 200

Приклади та імена метаданих

Приклад роботи з Rest api з реального проєкту (авторизаційні дані знеособлені): Скачати

Дані з Єнота, необхідні для відображення на сайті, публікуються хотлайном після попереднього клієнтського запиту.

Надалі сам користувач відповідає за опубліковані посилання.

Приклади посилань

Загальний вид посилання:

Довідники

Для довідників на прикладі Каталогу номенклатури

//de.enote.link/05e4719e-ac83-11e4-ab99-00163ee5d2d3/odata/standard.odata/Catalog_Номенклатура?$format=application/json;odata=nometadata

Імена метаданих Довідників ТУТ

Документи

Для документів на прикладі Діагностичних досліджень

//de.enote.link/05e4719e-ac83-11e4-ab99-00163ee5d2d3/odata/standard.odata/Document_Анализи?$format=application/json;odata=nometadata

Імена метаданих Документів ТУТ

Реєстри відомостей

Для регістрів відомостей на прикладі Стан попереднього запису

//de.enote.link/05e4719e-ac83-11e4-ab99-00163ee5d2d3/odata/standard.odata/InformationRegister_СостояниеПредварительнойЗаписи/SliceLast()?$format=application/json;odata=nometadata

Імена метаданих Регістрів відомостей ТУТ

Регістр накопичення

Регістри накопичення на прикладі Товарів на складах

//de.enote.link/05e4719e-ac83-11e4-ab99-00163ee5d2d3/odata/standard.odata/AccumulationRegister_ТоварыНаСкладах/Balance(Condition=’%D0%A1%D0%BA%D0%BB%D0%B0%D0%B4_Key%20eq%20guid’ccc38258-f574-11e7-769e-2e48eb60b70e»)?$format=application/json;odata=nometadata

Імена метаданих Реєстрів накопичення ТУТ

Print this entry

Інтеграція з сайтом/додатком через Rest API Єнота