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

POST /v1/requisite-links

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

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

Поле Тип Обяз. Описание
entityTypeId number да Тип владельца связи: 2 — сделка, 31 — счёт. Список: GET /v1/requisite-links/fields
entityId number да ID сущности-владельца. Источник: GET /v1/deals или GET /v1/invoices
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 при успехе

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

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 from /v1/requisite-links/fields (ENTITY_TYPE_ID, …) are accepted too."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_FIELDS Не переданы один или несколько из шести обязательных полей
422 BITRIX_ERROR Битрикс24 отклонил операцию — например, реквизит не принадлежит клиенту сделки
403 SCOPE_DENIED API-ключ не имеет скоупа crm. Требуемое сообщение: This endpoint requires 'crm' scope
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

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

Реквизит должен принадлежать клиенту сделки. Чтобы зарегистрировать связь для сделки, у неё должен быть выбран контакт или компания — владелец реквизита. Без выбранного клиента привязка возвращает 422 BITRIX_ERROR.

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