Поиск связей реквизитов

POST /v1/requisite-links/search

Поиск связей реквизитов с фильтрами и авто-пагинацией. Аналогичен GET /v1/requisite-links, но параметры передаются в теле запроса — удобнее для сложных фильтров с большим количеством условий и для программной сборки запросов.

Поля запроса (body)

Параметр Тип По умолч. Описание
filter object — Фильтрация. Допустимые ключи: entityTypeId, entityId, requisiteId, bankDetailId, mcRequisiteId, mcBankDetailId. Поддерживаются операторы сравнения ($gt/$gte/$lt/$lte), множества ($in/$nin). Логические $or/$and не поддерживаются.
Синтаксис фильтрации. Пример: { "entityTypeId": 2, "entityId": 3773 }
sort string — Поле сортировки — один из ключей фильтра
order string | object asc Направление для sort (asc/desc), либо форма { "поле": "asc|desc" }
limit number 50 Количество записей (до 5000)
offset number 0 Пропустить N записей

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/requisite-links/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityTypeId": 2, "requisiteId": 45 },
    "limit": 20
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/requisite-links/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityTypeId": 2, "requisiteId": 45 },
    "limit": 20
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/requisite-links/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityTypeId: 2, requisiteId: 45 },
    limit: 20,
  }),
})

const { success, data } = await res.json()
console.log('Найдено:', data.length)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/requisite-links/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { entityTypeId: 2, requisiteId: 45 },
    limit: 20,
  }),
})

const { success, data } = await res.json()

Другие сценарии

Все связи по конкретной сделке:

JSON 
{ "filter": { "entityTypeId": 2, "entityId": 3773 } }

Все связи по конкретному реквизиту (найти, к каким сущностям привязан реквизит с ID 45):

JSON 
{ "filter": { "requisiteId": 45 } }

Все связи счетов, entityTypeId равен 31:

JSON 
{
  "filter": { "entityTypeId": 31 },
  "limit": 100
}

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив связей
data[].ENTITY_TYPE_ID string Тип владельца: "2" — сделка, "31" — счёт
data[].ENTITY_ID string ID владельца. Источник: GET /v1/deals или GET /v1/invoices
data[].REQUISITE_ID string ID реквизита; "0" — не привязан. Источник: GET /v1/requisites
data[].BANK_DETAIL_ID string ID банковского реквизита; "0" — не привязан. Источник: GET /v1/bank-details
data[].MC_REQUISITE_ID string ID реквизита вашей компании; "0" — не привязан
data[].MC_BANK_DETAIL_ID string ID банковского реквизита вашей компании; "0" — не привязан

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

JSON 
{
  "success": true,
  "data": [
    {
      "ENTITY_TYPE_ID": "2",
      "ENTITY_ID": "3773",
      "REQUISITE_ID": "45",
      "BANK_DETAIL_ID": "0",
      "MC_REQUISITE_ID": "0",
      "MC_BANK_DETAIL_ID": "0"
    },
    {
      "ENTITY_TYPE_ID": "2",
      "ENTITY_ID": "3825",
      "REQUISITE_ID": "0",
      "BANK_DETAIL_ID": "0",
      "MC_REQUISITE_ID": "0",
      "MC_BANK_DETAIL_ID": "0"
    }
  ],
  "meta": {
    "total": 68,
    "hasMore": true
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING Не передан X-Api-Key
400 INVALID_FILTER Ошибка в синтаксисе фильтра
400 UNKNOWN_FILTER_FIELD Неизвестное поле фильтра (в ответе — список допустимых)
400 UNKNOWN_SORT_FIELD Неизвестное поле сортировки
400 INVALID_FILTER_OPERATOR Логический оператор верхнего уровня ($or/$and) не поддерживается
400 MISSING_ENTITY_TYPE_ID Фильтр по entityId без entityTypeId

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

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

Поля ответа — в исходных именах Битрикс24. Все поля возвращаются в верхнем регистре — ENTITY_TYPE_ID, ENTITY_ID, REQUISITE_ID и т. д.; значения числовых идентификаторов приходят строками, например "REQUISITE_ID": "45", "BANK_DETAIL_ID": "0". Ключи фильтра при этом принимаются в camelCase: entityTypeId, entityId, requisiteId, bankDetailId.

Значение "0" означает отсутствие привязки. Для REQUISITE_ID, BANK_DETAIL_ID, MC_REQUISITE_ID, MC_BANK_DETAIL_ID строка "0" означает, что соответствующий реквизит не привязан, а не что привязан объект с ID 0.

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