Добавление данных в приложение

1. Отправитель формирует пакет данных и отправляет файл данных для обработки
2. Отправитель ожидает завершения обработки данных

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

Отправка данных производится из внешнего сервиса (отправителя) в 2 операции:

1. Непосредственно отправка данных запросом –  POST {{baseURL}}/integration/post
   В ответ возвращается Location для отправки данных. Далее нужно выполнить PUT запрос на полученный Location с передачей данных. В ответ возвращается информация о созданном задании обработки загрузки.
2. Получение информации о состоянии загрузки данных запросом –  GET {{baseURL}}/jobs/{id}
   В ответ возвращается Location для отслеживания состояния. Далее нужно выполнить PUT запрос на полученный Location. В ответ возвращается состояние загрузки.

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

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

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

{
  "upload": [
    {
      "file": "base.json",
      "handler": "example-base",
      "version": "83B92336"
    },
    {
      "file": "sync-1.json",
      "handler": "example-sync",
      "version": "51B4E081"
    },
    {
      "file": "sync-2.json",
      "handler": "example-sync",
      "version": "EB28A449"
    }
  ]
}

Примеры файлов данных:

{
  "organization": {
    "name": "ООО Ромашка",
    "tin": "7725895602",
  },
  "bank_accounts": [
    {
      "bank": "044525555",
      "account": "40802810900000003155"
    }
  ]
}

{
  "date": "2018-02-15T10:25:22",
  "number": "1",
  "amount": 100000,
  "account": "40802810900000003155",
  "description": "Оплата по первому счету",
  "recipient_id": "123456789012",
  "recipient_name": "ИП Сергиенко Сергей",
  "recipient_account": "98765432109876543210",
  "recipient_bank": "044525555"
}

{
  "date": "2018-02-14T10:00:00",
  "number": "2",
  "amount": 50000,
  "account": "40802810900000003155",
  "description": "Оплата по второму счету",
  "recipient_id": "123456789012",
  "recipient_name": "ИП Сергиенко Сергей",
  "recipient_account": "98765432109876543210",
  "recipient_bank": "044525555"
}

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

Поля ответа:

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

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

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

Пока файлы не обработаны будет возвращаться ответ:

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

После обработки будет получен ответ с подтверждением:

{
  "general": {
    "response": 10200,
    "error": false,
    "message": ""
  },
  "result": [
    {
      "file": "base.json",
      "version": "83B92336",
      "handler": "example-base",
      "response": 10200,
      "error": false,
      "message": ""
    },
    {
      "file": "sync-1.json",
      "version": "51B4E081",
      "handler": "example-sync",
      "response": 10200,
      "error": false,
      "message": ""
    },
    {
      "file": "sync-2.json",
      "version": "EB28A449",
      "handler": "example-sync",
      "response": 10200,
      "error": false,
      "message": ""
    }
  ]
}

Если в процессе возникнут ошибки, то после их устранения будет необходимо повторить отправку.

Об ошибках будет сообщено в подтверждении обработки файлов данных.

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

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

1. Отправка данных 
2. Ожидание результата

На каждом этапе отправляются пары запросов:

1. Запрос открытия сессии
2. Отправка или получение данных по URL открытой сессии с закрытием сессии, если требуется.

Отправка данных

Отправка выполняется двумя запросами. Первый запрос открывает сессию (передается заголовок IBSession: start) и возвращает Location для загрузки данных с сессионными Cookie, которые нужно использовать для второго запроса. Второй запрос на адрес полученного Location передает данные и закрывает сессию (передается заголовок IBSession: finish).

1. Открытие сессии отправки данных

   Запрос

   POST https://example.com/a/smtl/1/hs/dt/storage/integration/post
   Authorization: Basic base64_encode(user:password) или Bearer access_token
   IBSession: start

   Ответ

   200
   Content-Length: 0
   Accept-Ranges: bytes
   Location: https://example.com:443/a/smtl/1/hs/dt/upload/33188784deb957240da13d737d41c7e4486c0e4616837c16b0c5dcf97cd8a4d8
   Set-Cookie: ibsession=1bb59853-87ce-4b06-a293-b5b7961da9ce;Path=/a/bs/1/;Version=1

2. Отправка данных

   Запрос

   PUT <заголовок Location предыдущего ответа>
   Cookie: <заголовок Set-Cookie предыдущего ответа>
   IBSession: finish
   
   < Двоичные данные >

   Ответ

   201 Created
   Content-Type: application/json; charset=UTF-8
   Content-Length: 156
   
   {
   "general": {
   "response": 10200,
   "error": false,
   "message": ""
   },
   "result": {
   "storage": "jobs",
   "id": "52307619-1fd1-11e9-b87e-0050568908e4"
   }
   }

Ожидание результата

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

1. Открытие сеанса ожидания результата

   Запрос

   GET https://example.com/a/smtl/1/hs/dt/storage/jobs/52307619-1fd1-11e9-b87e-0050568908e4
   Authorization: Basic base64_encode(user:password) или Bearer access_token
   IBSession: start

   Ответ

   302 Redirect
   Content-Length: 0
   Accept-Ranges: bytes
   Location: https://example.com:443/a/smtl/1/hs/dt/download/33340f613a2fb437109c58497633dc1784424750f6e22b30d3439b44542af57b
   Set-Cookie: ibsession=9c9ccb9d-0d83-4d00-a45d-c912047488d2;Path=/a/bs/1/;Version=1

2. Ожидание результата 

   Запрос

   GET https://example.com/a/smtl/1/hs/dt/download/33340f613a2fb437109c58497633dc1784424750f6e22b30d3439b44542af57b/
   Cookie: ibsession=9c9ccb9d-0d83-4d00-a45d-c912047488d2;Path=/a/bs/1/;Version=1
   IBSession: finish

   Ответ - результат еще не получен

   200 OK
   Content-Type: application/octet-stream
   Content-Length: 73
   Content-Disposition: attachment; filename="52307619-1fd1-11e9-b87e-0050568908e4.json"
   
   {
   "general": {
   "response": 10202,
   "error": false,
   "message": ""
   }
   }

   Ответ - результат получен

   200 OK
   Content-Type: application/octet-stream
   Content-Length: 706
   Content-Disposition: attachment; filename="52307619-1fd1-11e9-b87e-0050568908e4.json"
   
   {
   "general": {
   "response": 10200,
   "error": false,
   "message": ""
   },
   "result": [
   {
   "file": "base.json",
   "version": "83B92336",
   "handler": "example-base",
   "response": 10200,
   "error": false,
   "message": ""
   },
   {
   "file": "sync-1.json",
   "version": "51B4E081",
   "handler": "example-sync",
   "response": 10200,
   "error": true,
   "message": ""
   },
   {
   "file": "sync-2.json",
   "version": "EB28A449",
   "handler": "example-sync",
   "response": 10200,
   "error": true,
   "message": ""
   }
   ]
   }