Para agentes de IA: markdown desta página — /docs-content-en/entities/requisite-links.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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
entityTypeId number yes Link owner type. Values — Link fields
entityId number yes Owner entity ID. The source depends on the type — see the same reference
requisiteId number yes Client requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
bankDetailId number yes Client bank detail ID. Source: GET /v1/bank-details. Pass 0 to skip linking
mcRequisiteId number yes Your company's requisite ID. Source: GET /v1/requisites. Pass 0 to skip linking
mcBankDetailId number yes Your 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 app

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 app

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
success boolean Always true on success
data object Registration result
data.entityTypeId number The entity type that was passed
data.entityId number The entity ID that was passed
data.registered boolean Always 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
400 MISSING_FIELDS One or more of the six required fields is missing
400 INVALID_REQUEST The request body is not an object
404 ENTITY_NOT_FOUND No requisite or bank detail exists with the given ID
422 BITRIX_ERROR The link was rejected — for example, a requisite cannot be linked to a deal that has no client selected
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API 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