Список связей реквизитов

GET /v1/requisite-links

Возвращает список связей реквизитов с поддержкой фильтрации и авто-пагинации. Каждая связь соединяет реквизит и банковский реквизит с конкретной сделкой или счётом.

Параметры

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

Пагинация: при limit > 50 Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе. Максимум — 5000 записей за вызов.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/requisite-links?filter[entityTypeId]=2&filter[entityId]=3773" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/requisite-links?filter[entityTypeId]=2&filter[entityId]=3773" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/requisite-links?filter[entityTypeId]=2&filter[entityId]=3773',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
    },
  }
)

const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} связей`)

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/requisite-links?filter[entityTypeId]=2&filter[entityId]=3773',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

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

Поля ответа

Поле Тип Описание
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" — не привязан
meta.total number Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit

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

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"
    },
    {
      "ENTITY_TYPE_ID": "2",
      "ENTITY_ID": "3827",
      "REQUISITE_ID": "0",
      "BANK_DETAIL_ID": "0",
      "MC_REQUISITE_ID": "0",
      "MC_BANK_DETAIL_ID": "0"
    }
  ],
  "meta": {
    "total": 410,
    "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".

У связи нет отдельного числового id. Каждая связь определяется парой значений владельца — entityTypeId и entityId; именно они используются для получения и удаления записи.

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

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