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

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

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

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

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

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

Запрос: 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 - обработчик

Пример manifest.json

{
  "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": "Не корректные данные."
        }
    ]
}

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

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

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