Описание API Облачной части Т-Обмена. Версия 1.0 (с использованием файлового сервера)

1. Методы API со стороны УД 

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

URL: agentplus.online/api/my/distributors/ 

Метод: GET 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: JSON-массив, состоящий из объектов, содержащих следующие поля: 

  • Id – идентификатор дистрибьютора; 

  • CompanyId – идентификатор компании; 

  • DistributorCode – код дистрибьютора; 

  • Name – название дистрибьютора; 

  • City – город, в котором располагается дистрибьютор; 

  • ContactPersonFullName – ФИО контактного лица; 

  • ContactPhoneNumber – контактный номер телефона; 

  • ContactEmail – контактный почтовый адрес. 

1.2. Получение информации об устройствах дистрибьютора 

URL: agentplus.online/api/my/distributors/{distributorId}/devices/ 

Метод: GET 

Параметры запроса: 

  • distributorId – передающийся в GUID-идентификатор дистрибьютора. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: JSON-массив, состоящий из объектов, содержащих следующие поля: 

  • Identifier – Идентификатор устройства; 

  • MDMId – MDM-идентификатор устройства; 

  • HardwareId - Идентификатор, генерируемый в устройстве на основе IMEI или AndroidId; 

  • SerialNumber – Серийный номер устройства; 

  • LastActivityDate – Дата последней активности; 

  • Manufacturer – Производитель; 

  • DeviceModel – Модель устройства; 

  • Name – Название устройства; 

  • Employee – Имя сотрудника, использующего устройство. 

1.3. Получение информации о количестве доступных файлов для загрузки в УД 

URL: disc.agentplus.online/ api/texchange/v1/supplier/files/{distributorId} 

Метод: HEAD 

Параметры запроса: 

  • distributorId – GUID-идентификатор дистрибьютора, по которому необходимо получить информацию о количестве доступных файлов (необязателен). Если не передаётся, то возвращается количество доступных файлов по всем дистрибьюторам. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: тело ответа пустое. Количество файлов возвращается в заголовке ответа Count. 

1.4. Получение списка файлов для загрузки в УД 

URL: disc.agentplus.online/ api/texchange/v1/supplier/files/{distributorId}?count={count} 

Метод: GET 

Параметры запроса: 

  • distributorId – GUID-идентификатор дистрибьютора, список файлов которого необходимо получить (необязателен). Если не передаётся, то возвращается список файлов от всех дистрибьюторов. 

  • count - максимальное возможное количество файлов, возвращаемых в списке (необязателен). Передаётся в queryString. Если не передаётся, то задаётся значение файлов по умолчанию, равное 100. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: JSON-массив, состоящий из объектов, содержащих следующие поля: 

  • FileName – Имя файла выгрузки; 

  • DistributorId – Идентификатор дистрибьютора; 

  • DeviceId – MDM-идентификатор устройства; 

  • Timestamp – Время выгрузки файла на Диск (время сервера в облаке); 

  • FileSize – Размер файла в байтах; 

  • CheckSum – Контрольная сумма файла (значение не обязательное; имеет форма <алгоритм хеширования><пробел><хеш>); 

  • DownloadURL – Ссылка для загрузки файла (направляет на файловый сервер). 

1.5. Получение файла выгрузки 

URL: используется URL полученный в ответе на запрос Получение списка файлов для загрузки в УД (см п. 1.2). URL направляет на файловый сервер и действителен в течение 1 часа. 

Метод: GET 

Параметры запроса: отсутствуют. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: запрошенный файл. Название файла можно получить из заголовка ответа Content Disposition. Так же можно загрузить файл частями и/или запросить контрольную сумму файла, для проверки корректности получения файла (см. раздел 3) 

1.6. Подтверждение получения файла выгрузки 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/download/complete 

Метод: POST / PUT 

Параметры запроса: передаются в виде JSON-объекта 

  • DistributorId – GUID-идентификатор дистрибьютора; 

  • DeviceId – MDM-идентификатор устройства; 

  • FileName – Имя файла (берётся из списка файлов для загрузки в УД, см. п. 1.3). 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ:  

  • При успешном запросе (HTTP 200) – тело пустое. 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки. 

1.7. Получение ссылки для выгрузки файла в адрес МУ из УД 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/upload/url 

Метод: GET 

Параметры запроса: отсутствуют. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ:  

  • При успешном запросе (HTTP 200) – тело ответа содержит строчку с URL, который направляет на файловый сервер, по этому URL необходимо осуществить выгрузку файла. 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки.

1.8. Подтверждение и фиксация выгрузки файла из УД в адрес МУ 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/upload/complete 

Метод: POST / PUT 

Параметры запроса: передаются в виде JSON-объекта 

  • DistributorId – GUID-идентификатор дистрибьютора; 

  • DeviceId – MDM-идентификатор устройства; 

  • Hash – строка хэша, полученного от файлового сервера в результате успешной выгрузки файла. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: 

  • При успешном запросе (HTTP 200) – тело пустое. 

  • При ошибке (HTTP 400, либо 500) – в теле запроса находится описание ошибки. 

2. Методы API со стороны МТ 

2.1. Получение ссылки для скачивания файла, адресованного МУ из УД 

URL: disc.agentplus.online/api/texchange/v1/distributor/files/fromSupplier/url 

Метод: GET 

Параметры запроса: параметры отсутствуют 

Аутентификация: стандартная подпись запроса при обращении к облачным ресурсам. 

Ответ: 

  • При успешном запросе: 

  • Если файл для МУ имеется, то статус ответа будет HTTP 200, а в теле ответа будет строка URL, который направляет на файловый сервер 

  • Если файла для МУ нет, то статус ответа будет HTTP 404, тело ответа будет пустым 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки.

2.2. Получение файла, адресованного МУ из УД 

URL: используется URL полученный в ответе на запрос Получение ссылки для скачивания файла адресованного МУ из УД (см п. 2.1). URL направляет на файловый сервер и действителен в течение 1 часа. 

Метод: GET 

Параметры запроса: отсутствуют. 

Аутентификация: стандартная подпись запроса при обращении к облачным ресурсам. 

Ответ: запрошенный файл. Название файла можно получить из заголовка ответа Content Disposition. Так же можно загрузить файл частями и/или запросить контрольную сумму файла, для проверки корректности получения файла (см. раздел 3). 

2.3. Подтверждение получения файла 

URL: disc.agentplus.online/api/texchange/v1/distributor/files/fromSupplier/complete 

Метод: POST / PUT 

Параметры запроса: параметры отсутствуют 

Аутентификация: стандартная подпись запроса при обращении к облачным ресурсам 

Ответ: 

  • При успешном запросе (HTTP 200) 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки.

3. Возможности файлового сервера и работа с ним 

3.1. Общая концепция 

При разработке файлового сервера преследовались две цели: 

  • Повышение надёжности загрузки и выгрузки файлов 

  • Балансировка нагрузки и масштабирование облачных ресурсов 

Повышение надёжности передачи данных обеспечивает поддержкой загрузки и дозагрузки файлов частями (то же доступно и для выгрузки файла). 

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

Любой запрос к файловому серверу должен иметь авторотационный заголовок (Authorization) стандартного для каждого типа приложений формата. Например, для учётных систем, в том числе и УД, это схема token и пара: ключ и токен, а для МТ – это схема token и пара из идентификатора МУ и подписи запроса. 

Чтобы получить информацию о текущих возможностях Файлового сервера, необходимо по полученному URL выполнить запрос использованием HTTP-метода OPTIONS. В ответ сервер вернёт следующий набор данных (JSON-объект): 

  • Dup-Version – текущая версия протокола обмена, реализуемая данным сервером; 

  • Dup-Version-Min – минимальная версия протокола обмена, реализуемая сервером; 

  • Accept-Range – если параметр представлен в ответе, то сервер поддерживает выгрузку и загрузку файлов частями, параметр перечисляет через пробел поддерживаемые единицы измерения частей файла. Если параметр не представлен, то сервер не поддерживает загрузку и выгрузку по частям. 

  • Dup-Checksum – если параметр представлен, то сервер поддерживает работу с контрольными суммами файлов целиком и их частями. Параметр перечисляет через пробел поддерживаемые алгоритмы хеширования, которые можно использовать для контроля целостности передачи данных файла. 

  • Dup-Range – рекомендуемый размер части файла для передачи частями (если 0, то решение о размере части принимает клиентское приложение). 

3.2. Загрузка и выгрузка файла целиком 

Загрузка файла целиком в клиентское приложение происходит обращением методом GET по полученному URL. Если представленный в URL параметр sid валиден и запрошенный файл существует, то клиент в ответ получит содержимое файла. Имя файла можно извлечь из заголовка Content Disposition ответа. Статус ответа HTTP 200. 

Выгрузка файла целиком из клиентского приложения на Файловый сервер происходит обращением методами POST или PUT по полученному URL. URL так же валидируется. 

При этом в теле запроса нужно передать контент файла. Имя файла так же обязательно передать в заголовке запроса Content Disposition. 

При успешной выгрузке сервер возвращает статус HTTP 201. 

3.3. Загрузки и выгрузка файла частями 

3.4. Работа с контрольной суммой файла 

Если клиентскому приложению необходимо контролировать целостность передачи данных, то оно может указать следующие заголовки: 

Dup-Content-Checksum - [algorithm] (пока поддерживаем только MD5) 


3.5. Выгрузка треков передвижений 

URL: disc.agentplus.online/api/textchange/v1/supplier/files/download/tracks 

Метод: POST 

Параметры запроса: передаются в виде JSON-объекта 

  • MDMIDs – MDM-идентификаторы устройств; 

  • DateFrom – дата, с начала которой (включительно) необходимо выгрузить точки (необязательный параметр); 

  • DateTo – дата, по конец которой (включительно) необходимо выгрузить точки (необязательный параметр); 

  • FormingTrackWay – формат данных, в который будет выгружаться файл (“JSON”, “OneC8”). 

Аутентификация: Заголовок: Authorization: token <key>: <token>, где: 

  • key – ключ учётной системы;

  • token – токен учётной системы.

Ответ: 

  • При успешном запросе (HTTP 200) – тело ответа содержит URL для выгрузки файла и последнее время запроса выгрузки треков передвижений. Файл, который будет выгружаться по выданному URL, содержит в себе следующую информацию:  

  • Lat – широта точки 

  • Long – долгота точки 

  • TimeBase – время снятия точки с указанием часового пояса 

  • Time – время снятия точки без указания часового пояса 

  • DeviceId – MDM-идентификатор устройства 

  • Source 

  • Accuracy 

  • GPSServiceIsEnabled – Флаг, указывающий на включенный/выключенный gps 

3.6. Подтверждение получения файла при выгрузке треков 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/ tracks/complete 

Метод: POST / PUT  

Параметры запроса: передаются в виде строки – названия файла с треками с расширением передвижений 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где:  

  • key – ключ учётной системы;  

  • token – токен учётной системы.  

Ответ:   

  • При успешном запросе (HTTP 200) – тело пустое. 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки.  

4. Метод для получения количества фото (эскизов и оригиналов) 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/photos/count 

Метод: POST 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Параметры запроса: передаются в виде JSON-объекта 

  • DistributorId – GUID-идентификатор дистрибьютора (необязательный параметр) 

  • DeviceId – GUID-идентификатор устройства (необязательный параметр) 

Если параметр запроса не указан, то возвращаются данные по всем дистрибьюторам и МУ 

Ответ: JSON-массив, состоящий из объектов, содержащих следующие поля: 

  • SketchCount – Количество эскизов; 

  • OriginalCount – Количество оригиналов фото. 

 

  1. Метод для получения списка фото для загрузки в УД 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/photos 

Метод: POST 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Параметры запроса: передаются в виде JSON-объекта 

  • DistributorId – GUID-идентификатор дистрибьютора (необязательный параметр) 

  • DeviceId – GUID-идентификатор устройства (необязательный параметр) 

  • Count – Количество фото (необязательный параметр, по умолчанию 100) 

  • PhotoType – Тип фото (1 – эскиз, 2 - оригинал), по умолчанию установлено 1 (эскиз). 

Если в параметрах запроса не указано DeviceId и DistributorId, то возвращаются данные по всем дистрибьюторам и МУ 

Ответ: JSON-массив, состоящий из объектов, содержащих следующие поля: 

  • FileName – Имя файла выгрузки; 

  • DistributorId – Идентификатор дистрибьютора; 

  • DeviceId – MDM-идентификатор устройства; 

  • Timestamp – Время выгрузки файла на Диск (время сервера в облаке); 

  • FileSize – Размер файла в байтах; 

  • CheckSum – Контрольная сумма файла (значение не обязательное; имеет форма <алгоритм хеширования><пробел><хеш>); 

  • DownloadURL – Ссылка для загрузки файла (направляет на файловый сервер). 

 

Получение фото 

URL: используется URL полученный в ответе на запрос Получение списка фото для загрузки в УД. URL направляет на файловый сервер и действителен в течение 1 часа. 

Метод: GET 

Параметры запроса: отсутствуют. 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: запрошенный файл. Название файла можно получить из заголовка ответа Content Disposition. Так же можно загрузить файл частями и/или запросить контрольную сумму файла, для проверки корректности получения файла. 

  1. Подтверждение получения фото 

URL: disc.agentplus.online/api/texchange/v1/supplier/files/download/photos/complete 

Метод: POST / PUT 

Параметры запроса: передаются в виде JSON-объекта

  • DistributorId – GUID-идентификатор дистрибьютора; 

  • DeviceId – MDM-идентификатор устройства; 

  • FileName – Имя файла (берётся из списка файлов для загрузки в УД, см. п. 1.3). 

 

Аутентификация: Заголовок: Authorization: token <key>:<token>, где: 

  • key – ключ учётной системы; 

  • token – токен учётной системы. 

Ответ: 

  • При успешном запросе (HTTP 200) – тело пустое. 

  • При ошибке (HTTP 400 либо 500) – в теле запроса находится описание ошибки.