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

Связи реквизитов

Указывает, какой реквизит компании и какой банковский счёт использовать в счёте, предложении или сделке. Нужно компаниям, у которых несколько реквизитов. У связи нет отдельного числового id: она задаётся парой значений — тип владельца entityTypeId и его ID entityId.

Битрикс24 API: crm.requisite.link.* Скоуп: crm

Зарегистрировать связь реквизита

POST /v1/requisite-links

Создаёт или обновляет привязку реквизита к сущности-владельцу. Если связь для указанной пары entityTypeId и entityId уже существует, она перезаписывается целиком.

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

Поле Тип Обяз. Описание
entityTypeId number да Тип владельца связи. Значения — Поля связи
entityId number да ID сущности-владельца. Источник зависит от типа — см. тот же справочник
requisiteId number да ID реквизита клиента. Источник: GET /v1/requisites. Передайте 0, чтобы не привязывать
bankDetailId number да ID банковского реквизита клиента. Источник: GET /v1/bank-details. Передайте 0, чтобы не привязывать
mcRequisiteId number да ID реквизита вашей компании. Источник: GET /v1/requisites. Передайте 0, чтобы не привязывать
mcBankDetailId number да ID банковского реквизита вашей компании. Источник: GET /v1/bank-details. Передайте 0, чтобы не привязывать

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/requisite-links" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 3773,
    "requisiteId": 45,
    "bankDetailId": 12,
    "mcRequisiteId": 3,
    "mcBankDetailId": 7
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/requisite-links" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 2,
    "entityId": 3773,
    "requisiteId": 45,
    "bankDetailId": 12,
    "mcRequisiteId": 3,
    "mcBankDetailId": 7
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/requisite-links', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 3773,
    requisiteId: 45,
    bankDetailId: 12,
    mcRequisiteId: 3,
    mcBankDetailId: 7,
  }),
})

const { success, data } = await res.json()
console.log('Зарегистрирована связь для entityId:', data.entityId)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/requisite-links', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityTypeId: 2,
    entityId: 3773,
    requisiteId: 45,
    bankDetailId: 12,
    mcRequisiteId: 3,
    mcBankDetailId: 7,
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Результат регистрации
data.entityTypeId number Переданный тип сущности
data.entityId number Переданный ID сущности
data.registered boolean Всегда true при успехе

Сами привязки в ответе не возвращаются. Чтобы увидеть сохранённые значения, прочитайте связь через GET /v1/requisite-links/:entityTypeId/:entityId.

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

HTTP-статус: 201 Created

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 2,
    "entityId": 3773,
    "registered": true
  }
}

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

400 — переданы не все шесть полей:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_FIELDS",
    "message": "POST /v1/requisite-links requires entityTypeId, entityId, requisiteId, bankDetailId, mcRequisiteId and mcBankDetailId in the body (use 0 for ids you don't want to link). Missing: requisiteId, bankDetailId, mcRequisiteId, mcBankDetailId. Raw UPPER_SNAKE names are accepted too: ENTITY_TYPE_ID, ENTITY_ID, REQUISITE_ID, BANK_DETAIL_ID, MC_REQUISITE_ID, MC_BANK_DETAIL_ID."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_FIELDS Не переданы один или несколько из шести обязательных полей
400 INVALID_REQUEST Тело запроса не является объектом
404 ENTITY_NOT_FOUND Реквизита или банковского реквизита с указанным ID не существует
422 BITRIX_ERROR Привязка отклонена — например, реквизит нельзя привязать к сделке, у которой не выбран клиент
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

0 — это «не привязывать», а не ссылка на объект с нулевым ID. Все шесть полей обязаны присутствовать в теле, но значение 0 в любом из четырёх идентификаторов означает пустую привязку. Связь, у которой все четыре равны 0, регистрируется и возвращает 201.

Регистрация перезаписывает связь целиком. Повторный вызов заменяет весь набор из четырёх привязок значениями из тела запроса: там, где передан 0, привязка снимается. Чтобы изменить одну привязку и сохранить остальные, используйте PATCH /v1/requisite-links/:entityTypeId/:entityId.

Реквизит клиента должен принадлежать клиенту сделки. Чтобы привязать requisiteId к сделке, у неё должен быть выбран контакт или компания — владелец этого реквизита. Реквизиты вашей компании — mcRequisiteId и mcBankDetailId — от клиента сделки не зависят.

При отказе прежняя связь остаётся нетронутой. Если хотя бы один идентификатор не прошёл проверку, не применяется ни одно из значений запроса.

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