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

Добавить позицию в оплату CRM

POST /v1/crm-payments/:id/products

Добавляет в оплату CRM позицию — часть товарной строки объекта, например сделки, в указанном количестве. Сумма оплаты пересчитывается сразу.

Поля передаются плоско в корне JSON, без обёртки fields.

Параметры

Параметр Тип Обяз. Описание
id (path) number да ID оплаты. Список оплат объекта: GET /v1/crm-payments

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

Поле Тип Обяз. Описание
rowId number да ID товарной строки объекта CRM. Список: GET /v1/crm-payments/available-products, поле productRows[].id
quantity number да Количество, положительное целое. Не больше остатка строки — поля productRows[].quantity в доступных товарных строках

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-payments/573/products" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rowId": 2357, "quantity": 2 }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-payments/573/products" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rowId": 2357, "quantity": 2 }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-payments/573/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rowId: 2357, quantity: 2 }),
})

const { data } = await res.json()
console.log('ID позиции:', data.id, 'сумма оплаты:', data.payment.sum)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-payments/573/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rowId: 2357, quantity: 2 }),
})

const { data } = await res.json()

Поля ответа

HTTP-статус успешного ответа — 201.

Поле Тип Описание
success boolean true при успехе
data.id number ID созданной позиции оплаты. Передаётся как itemId в PATCH и DELETE /v1/crm-payments/:id/products/:itemId
data.payment object Оплата после добавления позиции, поля — как в GET /v1/crm-payments/:id
data.payment.id number ID оплаты
data.payment.sum number Сумма оплаты с учётом новой позиции
meta.readbackUnavailable boolean Приходит только со значением true, когда позиция добавлена, а перечитать оплату не удалось. Тогда data.payment содержит только id. Повторять добавление не нужно — проверьте позиции через GET /v1/crm-payments/:id/products

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

JSON 
{
  "success": true,
  "data": {
    "id": 445,
    "payment": {
      "id": 573,
      "accountNumber": "1035/1",
      "paid": "N",
      "datePaid": null,
      "empPaidId": null,
      "paySystemId": 19,
      "sum": 3000,
      "currency": "RUB",
      "paySystemName": "ЮKassa"
    }
  }
}

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

422 — quantity больше остатка товарной строки:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Недостаточно товара для добавления в оплату",
    "b24Code": "0"
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Тело не передано и заголовка Content-Type нет, не передан rowId или quantity, либо значение не положительное целое, например 1.5
400 FST_ERR_CTP_EMPTY_JSON_BODY Передан заголовок Content-Type: application/json, а тело пустое
400 READONLY_FIELD В теле есть поле кроме rowId и quantity, либо тело не JSON-объект, например null или массив
400 INVALID_ID id не положительное целое число
404 ENTITY_NOT_FOUND Оплаты с таким id нет — сообщение Payment has not been found
404 ENTITY_NOT_FOUND Проверка подтвердила, что товарной строки с таким rowId нет — сообщение Product row was not found. на любом языке портала
404 ENTITY_NOT_FOUND Товарная строка существует, но эта оплата не может её оплатить — сообщение Product was not found. для порталов на английском, немецком и казахском языках; Товар не найден для портала на русском языке
422 BITRIX_ERROR quantity больше остатка строки — сообщение Недостаточно товара для добавления в оплату
422 BITRIX_ERROR Битрикс24 отклонил запрос, причина — в error.message
422 BITRIX_NO_EFFECT Позиция не создана, например строка с таким rowId уже есть в этой оплате. Существующая позиция при этом не меняется — количество в ней меняют через PATCH /v1/crm-payments/:id/products/:itemId
403 BITRIX_ACCESS_DENIED У пользователя ключа нет доступа к объекту CRM или оплате в Битрикс24
403 WRITE_BLOCKED_READONLY_KEY Ключу запрещена запись
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
401 MISSING_API_KEY Не передан X-Api-Key

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

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

Добавленное количество уходит из остатка строки. После добавления 2 единиц из строки на 3 единицы quantity этой строки в доступных товарных строках становится 1.

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