Пакетные запросы

В работе с REGOS:API часто возникает необходимость последовательно выполнить несколько методов, передавая результат одного шага в другой. Для этого предусмотрен специальный механизм — пакетные запросы (batch). Он позволяет объединить до пятидесяти отдельных вызовов API в один запрос, отправить его на сервер и получить структурированный ответ со всеми результатами. Такой подход экономит сетевые ресурсы и делает интеграцию предсказуемой и удобной.

Как выполнять пакетные запросы (batch)

[POST] …/v1/batch

Запрос к batch-методу всегда отправляется на единый endpoint …/v1/batch и представляет собой JSON-массив шагов. Каждый шаг описывается ключом key, который идентифицирует его внутри пакета, путем path и телом payload.

Можно объединять в один пакет как полностью независимые шаги, так и связанные друг с другом. Связь строится через плейсхолдеры — специальные ссылки на результат предыдущих шагов. Они записываются в формате ${stepKey.property} и позволяют подставлять значения прямо из ответа сервера. Благодаря этому нет необходимости вручную обрабатывать промежуточные данные на стороне клиента: система сама передаст их в нужный шаг.

Например, если в первом запросе был создан новый поставщик, его идентификатор можно использовать в следующем шаге так:

${ProducerAdd.result.new_id}

А если метод вернул массив объектов, то доступ к элементам выполняется по индексу. Чтобы взять идентификатор первого поставщика в списке, используется запись:

${ProducerList.result.0.id}

В теле запроса доступен параметр stop_on_error. Если его значение равно true, выполнение пакета прервётся на первом неуспешном шаге. Если установлено false, все шаги будут выполнены до конца, даже если некоторые из них вернут ошибку. Это полезно, когда важна максимальная полнота обработки.

Каждый шаг выполняется с ограничением по времени — десять секунд. Если за это время метод не успел завершиться, в ответ вернётся ошибка таймаута. Отдельно стоит учитывать ограничения: нельзя вызывать batch изнутри batch, а также заблокированы некоторые методы, которые вызывают чрезмерную нагрузку на систему, например Item/Import.

Ответ на batch-запрос всегда содержит массив responses. Внутри каждого элемента находится ключ шага, HTTP-статус выполнения и тело ответа. Если метод завершился успешно, в поле response будет стандартный объект API с полями ok и result. Если произошла ошибка, то внутри будет возвращён объект ErrorResult с кодом и описанием. Это обеспечивает единый контракт и позволяет обрабатывать пакетные вызовы так же, как одиночные.

Ниже приведён пример простого пакета. Сначала создаётся производитель с помощью метода Producer/Add, а затем в следующем шаге сразу же выполняется его выборка через Producer/Get. При этом идентификатор нового производителя передаётся во второй шаг динамически, через плейсхолдер:

{
  "stop_on_error": false,
  "requests": [
    {
      "key": "ProducerAdd",
      "path": "Producer/Add",
      "payload": { "name": "Coca-Cola" }
    },
    {
      "key": "ProducerGet",
      "path": "Producer/Get",
      "payload": { "ids": ["${ProducerAdd.result.new_id}"] }
    }
  ]
}

Сервер вернёт ответ, где в блоке responses будут результаты обоих шагов. В первом видно, что создан производитель с new_id, а во втором — что он тут же успешно найден по этому идентификатору:

{
  "responses": [
    {
      "key": "ProducerAdd",
      "status": 200,
      "response": {
        "ok": true,
        "result": {
          "new_id": 4
        }
      }
    },
    {
      "key": "ProducerGet",
      "status": 200,
      "response": {
        "ok": true,
        "result": [
          {
            "id": 4,
            "name": "Coca-Cola",
            "last_update": 1758289402
          }
        ],
        "next_offset": 0,
        "total": 1
      }
    }
  ]
}