Получение данных из приложения

1. Получатель запрашивает для себя изменения
2. Получатель проверяет готовность запрошенных данных
3. Получатель загружает данные к себе
4. Получатель обрабатывает данные и подтверждает, что изменения загружены и обработаны.

Запросы выполняются парами POST → PUT или GET → GET. Первый запрос открывает сессию передачи/получения данных с авторизацией. Второй запрос выполняет непосредственную передачу/получение данных. Пары запросов должны выполняться в одном соединении.

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

В самой учетной системе определены правила регистрации к выгрузке. Например, при записи и проведении, документы по определенным правилам регистрируются к выгрузке.

После регистрации к выгрузке документы могут быть получены внешним сервисом через программный интерфейс передачи данных.

Запрос на формирование данных

Запрос – POST {{baseURL}}/integration/get

В ответ возвращается информация о созданном задании на формирование данных.

Поля ответа:

• result - Структура - результат
  • storage - Строка - идентификатор объектного хранилища (в данном случае – jobs)
  • id - Строка - идентификатор объекта хранилища (в данном случае – идентификатор задания)

{
  "general": {
    "response": 10200,
    "error": false,
    "message": ""
  },
  "result": {
    "storage": "jobs",
    "id": "47e7efd6-ddb6-11e7-819b-0050568925e0"
  }
}

Если к отправке нет данных, то при запросе на получение данных система вернет ответ с кодом 10404

{
  "general": {
    "response": 10404,
    "error": false,
    "message": ""
  }
}

По идентификатору задания выполняется дальнейшее отслеживание подготовки данных с помощью запроса GET {{baseURL}}/jobs/{id}

При запросе данных, в приложении выполняются следующие действия:

1. Формируется список объектов к выгрузке
2. Формируются файлы для каждого объекта с именем равным идентификатору объекта.
3. Формируется файл описания данных manifest.json
4. Файлы упаковываются в архив zip
5. Ссылка на архив возвращается в ответе.

{
  "general": {
    "response": 10202,
    "error": false,
    "message": ""
  }
}

После формирования данных будет получен ответ с идентификатором файла собранных данных.

Поля ответа:

• result - Структура - результат
  • storage - Строка - идентификатор объектного хранилища (в данном случае – files)
  • id - Строка - идентификатор объекта хранилища (в данном случае – идентификатор файла)

{
  "general": {
    "response": 10200,
    "error": false,
    "message": ""
  },
  "result": {
    "storage": "files",
    "id": "0cdf3084-90e4-49aa-8a57-735514cf5670"
  }
}

Получение файла данных 

Запрос – GET {{baseURL}}/files/{id}

Данные возвращаются в виде zip-архива. В составе архива обязательно содержится файл  manifest.json, описывающий файлы данных в этом архиве.

Структура файла manifest.json:

• upload - Структура- список файлов данных
  • file - Строка - имя файла (идентификатор данных)
  • version - Строка - версия
  • handler - Строка - обработчик

{
  "upload": [
    {
      "file": "75a49f73-15ba-11e8-b5bd-0050568908e4.json",
      "handler": "example-sync",
      "version": "426900129"
    },
    {
      "file": "8ee44925-160d-11e8-b5bd-0050568908e4.json",
      "handler": "example-sync",
      "version": "2117101459"
    }
  ]
}

Подтверждение получения данных 

Запрос –  POST {{baseURL}}/integration/confirm

В теле запроса передаются подтверждение в формате JSON

Поля подтверждения:

• result - Структура - результат обработки
  • file - Строка - имя файла (идентификатор данных)
  • version - Строка - версия подтверждаемого файла (передается в манифесте), нужна для проверки необходимости повторной отправки данных.
  • handler  - Строка - обработчик данных
  • response  - Число - код ответа (коды определяются в учетной системе)
  • error - Булево- признак ошибки обработки
  • message  - Строка - описание в случае ошибки.

{
  "result": [
    {
      "file": "75a49f73-15ba-11e8-b5bd-0050568908e4.json",
      "version": "426900129",
      "handler": "example-sync",
      "response": 10200,
      "error": false,
      "message": ""
    },
    {
      "file": "8ee44925-160d-11e8-b5bd-0050568908e4.json",
      "version": "2117101459",
      "handler": "example-sync",
      "response": 10200,
      "error": false,
      "message": ""
    }
  ]
}

Обработка подтверждения выполняется синхронно.

{
    "general": {
        "response": 10200,
        "error": false,
        "message": ""
    }
}

После получения данных синхронизируемые документы будут исключены из списка к отправке.

Данные также могут быть отклонены получателем.

{
    "result": [
        {
            "file": "54ff1341-d9c5-11e7-819b-0050568925e0.json",
            "version": "2015273148",
            "handler": "example",
            "response": 10400,
            "error": true,
            "message": "Не корректные данные."
        }
    ]
}

Коды возврата должны быть определены во внешней учетной системе и согласованы с разработчиком прикладного решения. 

Рекомендуемые коды возврата учетной системы при отправке подтверждений

Рекомендуется использовать такие-же коды возврата, что используются при подтверждении обработки полученных от учетной системы данных приложением.