Схема получения данных

  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}

Получение данных с помощью запросов GET выполняется в соответствие с описанием операции Download, т.е. выполняется 2 последовательных запроса GET.

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

Второй GET запрос с сессионными cookie авторизации не требует.

На первый запрос будет получен 302 редирект с адресом Location. Большинство библиотек обрабатывают 302-редирект как браузер, таким образом сразу будет получен результат второго GET запроса.

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

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

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

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

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

Код возврата

Это ошибка

Описание

110200
Выполнено
210240
Выполнено с предупреждениями. Предупреждения в сообщении.
310400ДаОшибка данных. Описание ошибок в сообщении.
410404
Данные не найдены
510500ДаВнутренняя ошибка. Описание ошибки в сообщении.