لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/requisite-links.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Requisite links

A requisite link specifies which company requisite and which bank account to use in an invoice, a quote or a deal. Needed by companies that have several requisites. A link has no separate numeric id: it is defined by a pair of values — the owner type entityTypeId and its ID entityId.

Bitrix24 API: crm.requisite.link.* Scope: crm

POST /v1/requisite-links

Creates or updates the link between a requisite and an owner entity. If a link for the given entityTypeId and entityId pair already exists, it is overwritten in full.

Request fields (body)

Field Type Required Description
FieldentityTypeId Typenumber Requiredyes DescriptionLink owner type. Values — Link fields
FieldentityId Typenumber Requiredyes DescriptionOwner entity ID. The source depends on the type — see the same reference
FieldrequisiteId Typenumber Requiredyes DescriptionClient requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
FieldbankDetailId Typenumber Requiredyes DescriptionClient bank detail ID. Source: GET /v1/bank-details. Pass 0 to skip linking
FieldmcRequisiteId Typenumber Requiredyes DescriptionYour company's requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
FieldmcBankDetailId Typenumber Requiredyes DescriptionYour company's bank detail ID. Source: GET /v1/bank-details. Pass 0 to skip linking

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Registered link for entityId:', data.entityId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionRegistration result
Fielddata.entityTypeId Typenumber DescriptionThe entity type that was passed
Fielddata.entityId Typenumber DescriptionThe entity ID that was passed
Fielddata.registered Typeboolean DescriptionAlways true on success

The links themselves are not returned in the response. To see the stored values, read the link via GET /v1/requisite-links/:entityTypeId/:entityId.

Response example

HTTP status: 201 Created

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

Error response example

400 — not all six fields were provided:

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."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_FIELDS DescriptionOne or more of the six required fields is missing
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo requisite or bank detail exists with the given ID
HTTP422 CodeBITRIX_ERROR DescriptionThe link was rejected — for example, a requisite cannot be linked to a deal that has no client selected
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

Known specifics

0 means "do not link", not a reference to an object with ID zero. All six fields must be present in the body, but a value of 0 in any of the four identifiers means an empty link. A link whose four identifiers are all 0 is registered and returns 201.

Registration overwrites the link in full. A repeat call replaces all four links with the values from the request body: wherever 0 is passed, the link is cleared. To change one link and keep the rest, use PATCH /v1/requisite-links/:entityTypeId/:entityId.

The client requisite must belong to the deal's client. To link requisiteId to a deal, the deal must have a contact or company selected — the owner of that requisite. Your company's own requisites — mcRequisiteId and mcBankDetailId — do not depend on the deal's client.

On rejection, the previous link stays untouched. If at least one identifier fails validation, none of the request values are applied.

See also