## Зарегистрировать связь реквизита `POST /v1/requisite-links` Создаёт или обновляет привязку реквизита к сущности-владельцу. Если связь для указанной пары `entityTypeId` и `entityId` уже существует, она перезаписывается целиком. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `entityTypeId` | number | да | Тип владельца связи. Значения — [Поля связи](/docs/entities/requisite-links/fields) | | `entityId` | number | да | ID сущности-владельца. Источник зависит от типа — см. тот же справочник | | `requisiteId` | number | да | ID реквизита клиента. Источник: [`GET /v1/requisites`](/docs/entities/requisites/list). Передайте `0`, чтобы не привязывать | | `bankDetailId` | number | да | ID банковского реквизита клиента. Источник: [`GET /v1/bank-details`](/docs/entities/bank-details/list). Передайте `0`, чтобы не привязывать | | `mcRequisiteId` | number | да | ID реквизита вашей компании. Источник: [`GET /v1/requisites`](/docs/entities/requisites/list). Передайте `0`, чтобы не привязывать | | `mcBankDetailId` | number | да | ID банковского реквизита вашей компании. Источник: [`GET /v1/bank-details`](/docs/entities/bank-details/list). Передайте `0`, чтобы не привязывать | ## Примеры ### curl — личный ключ ```bash 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-приложение ```bash 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`](/docs/entities/requisite-links/get). ## Пример ответа 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 — [Ошибки](/docs/errors). ## Известные особенности **`0` — это «не привязывать», а не ссылка на объект с нулевым ID.** Все шесть полей обязаны присутствовать в теле, но значение `0` в любом из четырёх идентификаторов означает пустую привязку. Связь, у которой все четыре равны `0`, регистрируется и возвращает `201`. **Регистрация перезаписывает связь целиком.** Повторный вызов заменяет весь набор из четырёх привязок значениями из тела запроса: там, где передан `0`, привязка снимается. Чтобы изменить одну привязку и сохранить остальные, используйте [`PATCH /v1/requisite-links/:entityTypeId/:entityId`](/docs/entities/requisite-links/update). **Реквизит клиента должен принадлежать клиенту сделки.** Чтобы привязать `requisiteId` к сделке, у неё должен быть выбран контакт или компания — владелец этого реквизита. Реквизиты вашей компании — `mcRequisiteId` и `mcBankDetailId` — от клиента сделки не зависят. **При отказе прежняя связь остаётся нетронутой.** Если хотя бы один идентификатор не прошёл проверку, не применяется ни одно из значений запроса. ## Смотрите также - [Поля связи](/docs/entities/requisite-links/fields) - [Обновить связь](/docs/entities/requisite-links/update) - [Удалить связь](/docs/entities/requisite-links/unregister) - [Список связей](/docs/entities/requisite-links/list) - [Реквизиты](/docs/entities/requisites) - [Банковские реквизиты](/docs/entities/bank-details) - [Batch](/docs/batch)