Пакетная отправка

Метод /batch выполняет до 50 запросов за одно обращение. Он нужен при первой выгрузке базы и при потоке событий: вместо сотен отдельных запросов вы отправляете пачки и получаете результат по каждому.

Это тот же набор методов, что и при обычной отправке, — /batch только упаковывает их.

---

Запрос

POST /batch

{
  "requests": [
    {
      "request_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "endpoint": "users/sync",
      "method": "POST",
      "data": { "users": [ { "ID": "1042", "EMAIL": "ivanov@example.ru" } ] }
    },
    {
      "request_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "endpoint": "products/sync",
      "method": "POST",
      "data": { "products": [ { "ID": "5501", "NAME": "Куртка зимняя Аврора" } ] }
    }
  ]
}

Поле	Обязательно	Описание
endpoint	да	Путь метода без ведущей косой черты: users/sync, а не /users/sync
method	нет	HTTP-метод. По умолчанию POST
data	нет	Тело запроса. Для GET-методов сюда кладутся параметры выборки
request_id	нет	Ваш идентификатор запроса, по которому вы найдёте его результат в ответе. Настоятельно рекомендуется

Требования и особенности:

• requests — непустой массив, не больше 50 элементов; при превышении возвращается HTTP 400;
• регистр имён полей конверта не важен: REQUESTS, Requests и requests — одно и то же;
• общий размер тела — до 10 МБ;
• запросы выполняются последовательно, в том порядке, в котором вы их передали. Это позволяет в одной пачке отправить сначала разделы, потом товары;
• request_id должен быть уникален в пределах пачки. Подойдёт UUID.

---

Ответ

{
  "success": true,
  "results": [
    {
      "request_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "success": true,
      "data": {
        "success": true,
        "code": 200,
        "data": { "results": [ { "xml_id": "1042", "status": "updated", "user_id": 317 } ] }
      }
    },
    {
      "request_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "success": false,
      "error": { "success": false, "error": "Не переданы данные товаров", "code": 400 }
    }
  ]
}

Успех пачки не означает успех запросов

success: true на верхнем уровне означает, что пачка принята и обработана. Результат каждого запроса — в его элементе results: поле success, а при ошибке — error. Внутри data лежит обычный ответ метода, включая массив results с результатом по каждой сущности.

Ошибка одного запроса не прерывает остальные: пачка выполняется до конца.

---

Ошибки уровня пачки

HTTP-код	Причина
400	requests пуст, не является массивом или содержит больше 50 элементов
401	Ключ коннектора не передан или не найден
503	Инстанс проекта недоступен

Если проект в момент запроса обновляется, пачка целиком ставится в очередь и применяется после обновления. Ответ в этом случае — {"success": true, "queued": true} без массива results. Считайте такие запросы доставленными и не отправляйте их повторно.

---

Как построить отправку

Схема, по которой работает готовый коннектор 1С-Битрикс. Её стоит воспроизвести — она закрывает обрывы связи и недоступность проекта:

1. Пишите события в свою таблицу. Каждое событие — строка с полями: свой идентификатор запроса, путь метода, тело, состояние (новый, отправлен, ошибка), счётчик попыток, время следующей попытки.
2. Отправляйте пачками до 50 записей в состоянии «новый».
3. Разбирайте results по request_id. Успешные записи помечайте отправленными. Ответ "queued": true без results означает, что принята вся пачка. Записи с ошибкой в данных — "success": false и код 4xx — сразу помечайте ошибкой: их нужно исправить, а не повторять.
4. Повторяйте недоставленное с растущей паузой. Недоставленное — это сетевые ошибки, таймауты и HTTP 5xx. Паузы: 30 секунд для первых трёх попыток, затем 5 минут, 15 минут, час, 6 часов. После 20 попыток помечайте запись окончательно неотправленной и разбирайтесь вручную.
5. Чистите очередь: отправленные и окончательно неотправленные записи старше недели удаляйте.

Повторы безопасны

Методы синхронизации (*/sync, /products/syncSections, /tracking/basket-sync) работают по принципу «создать или обновить» по вашему идентификатору. Если не уверены, дошёл ли такой запрос, — отправьте его снова, дубликата не будет. А вот визит, добавление в корзину и достижение цели при повторе запишутся второй раз.

---

Когда пакетная отправка не нужна

Одиночные запросы уместны там, где событие единично и важна скорость:

• проверка ключа — GET /sync/check;
• связывание сессии с клиентом в момент входа в аккаунт;
• достижение цели;
• получение команд и ответы на них.