Введение

Система Агроаналитика FMS, далее АА, может взаимодействовать с произвольными внешними системами, далее, в тексте, для удобства, внешние системы будут именоваться 1С.

Взаимодействие АА и 1С осуществляется посредством программного интерфейса, далее API. Мастер системой в М2М обмене выступает 1С, АА в работе М2М обмена всегда выступает ведомой системой.

Общая схема выполнения 1 запроса приведена на рис. 1:

Рисунок 1 - Общая схема обмена данными между АА и 1С.

Требования к реализации API соединения между системами

Все данные участвующие в обмене между системами должны иметь глобальный и уникальный идентификатор. В имеющейся реализации таким идентификатором выступает GUID. Идентификация записей происходит через GUID. Синхронность GUID в двух системах достигается через одну точку формирования таких идентификаторов. В имеющейся реализации мастер система является генератором GUID. Это означает, что местом создания данных по всем сущностям является мастер Система, она передает созданные записи по всем сущностям участвующим в обмене в ведомую систему, ведомая система в свою очередь производит необходимые манипуляции с данными мастер системы и возвращает результаты мастер системе.

Точка доступа к методам API

Вызовы методов реализованы посредством передачи JSON объекта в теле запроса, который передается в АА в Body запроса. Запросы передаются методом POST. 

Запросы имеют четкую структуру, см. рис. 2 В обязательном порядке передается команда запроса, токен сессии, остальные параметры являются дополнительными и передаются для уточнения параметров запроса.

Рисунок 2 - Структура запроса в API

Сущности API

Токен

Ключ в объекте запроса "token".

Уникальный идентификатор API сессии М2М обмена информацией. Состоит из букв латинского алфавита и чисел. Каждый токен имеет ограниченное время жизни, по истечению которого он считается невалидным и работать с ним будет нельзя. Потребуется повторная аутентификация. Однако, механик работы с сессиями реализован таким

Команда

Ключ в объекте запроса "cmd".

Идентификатор запрашиваемой на выполнении команды. Состоит из букв латинского алфавита.

GUID

Ключ в объекте запроса "guid".

Формат шестнадцетиричное число записанное строкой. Пример: A62061DDC4C311E581E6000C2979F4AE

Статистически уникальный 128-битный идентификатор сущностей. Используется для однозначной идентификации объектов в рамках Системы. 

Параметры

Ключ в объекте запроса для каждой команды свой.

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

Основные ответы API на запросы связанные с данными и не подразумевающие возврат набора данных объекта

SUCCESS

Успешное выполнение метода

возврат: { "res_code":-X ,"res_desc":"result description" }

res_code: код результата

res_desc: описание результата

FAIL

Неуспешное выполнение метода

возврат: { "err_code":-X ,"err_desc":"error description" }

err_code: код ошибки

err_desc: описание ошибки