Для AI-агентов: markdown этой страницы — /docs-content/entities/recurring-deals.md индекс документации — /llms.txt

Регулярные сделки

Настройки регулярности описывают автоматическое создание сделок, например каждый месяц по абонентке. ID настройки отличается от ID сделки-шаблона. Доступность зависит от тарифа Битрикс24.

Bitrix24 API: crm.deal.recurring.*

Скоуп: crm

Список регулярных сделок

GET /v1/recurring-deals

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

Параметры

Поле Тип Обязательный Описание
filter object нет Фильтрация по полям из описания полей регулярной сделки.
Синтаксис фильтрации. Пример: ?filter[active]=false или JSON-строка
sort string / object / string[] нет Поля сортировки. id — по возрастанию, -id — по убыванию
order object нет Альтернатива sort, например {"id":"desc"}
select string / string[] нет Поля ответа. Строка через запятую или массив имён
limit number нет Размер выборки, по умолчанию 50, максимум 5000
offset number нет Смещение от начала выборки
withTotal boolean нет Запрос общего количества. При false поле meta.total также возвращается

Пагинация. При limit > 50 сервер читает несколько страниц, до 5000 записей за запрос. Для продолжения используйте offset и meta.hasMore.

Примеры

curl — личный ключ

Terminal 
curl -X GET "https://vibecode.bitrix24.tech/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl -X GET "https://vibecode.bitrix24.tech/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth-приложение

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Поля ответа

Поле Тип Описание
success boolean Признак успешного запроса
data object[] Настройки повторения. См. поля регулярной сделки
meta.total number Общее число подходящих настроек, если возвращено
meta.hasMore boolean Есть ли следующая часть выборки
meta.warnings object[] Предупреждения, если возвращены. Неизвестные поля select могут быть проигнорированы при успешном запросе

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "active": false
    },
    {
      "id": 9,
      "active": false
    }
  ],
  "meta": {
    "total": 4,
    "hasMore": true
  }
}

Пример ответа при ошибке

400 — неизвестное поле фильтра:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'unknownField' for entity 'recurring-deals'. Available: id, dealId, basedId, active, nextExecution, lastExecution, counterRepeat, startDate, categoryId, isLimit, limitRepeat, limitDate"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по неизвестному полю. Допустимые поля — в сообщении ошибки и описании полей
400 INVALID_FILTER_FIELD Имя поля начинается с неподдерживаемого префикса @ или !@
400 INVALID_FILTER_OPERATOR Неизвестный оператор, пустой объект условия или логическое условие $or либо $and
400 INVALID_DUPLICATE_FILTER_FIELD Два условия сводятся к одному условию фильтра. Передайте одно из них
400 INVALID_SORT_FIELD В сортировке передано запрещённое имя __proto__, constructor или prototype
400 UNKNOWN_SORT_FIELD Сортировка по неизвестному полю
400 INVALID_SORT_DIRECTION Направление в объекте сортировки не из списка строк asc, desc, ASC, DESC или чисел 1, -1
400 INVALID_FILTER filter не является объектом или JSON-строкой с объектом, либо смешаны две формы записи фильтра
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Нет настроенных токенов доступа к Битрикс24
403 SCOPE_DENIED API-ключ не имеет скоупа crm
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе, в том числе из-за отсутствия нужного скоупа
422 BITRIX_ERROR Бизнес-отказ Битрикс24 или ограничение тарифа. Причина — в error.message
503 BITRIX_TIMEOUT Битрикс24 не ответил вовремя. Повторите после срока из Retry-After
502 BITRIX_UNAVAILABLE Нет соединения с Битрикс24
429 RATE_LIMITED Превышен лимит запросов. Точное значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

Полный список общих ошибок API — Коды ошибок.

Известные особенности

В ответе могут присутствовать настройки с active: false. Если нужны только активные расписания, задайте фильтр active: true.

Смотрите также