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

Поля оплаты

GET /v1/payments/fields

Возвращает схему полей оплаты: типы, флаги только-для-чтения, список агрегируемых полей.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/payments/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/payments/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Поля оплаты:', Object.keys(data.fields))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/payments/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
id number Идентификатор оплаты (только чтение)
orderId number Идентификатор заказа. Источник: GET /v1/orders
paySystemId number Идентификатор платёжной системы. Узнать ID можно из существующих оплат: GET /v1/payments или POST /v1/payments/aggregate с groupBy: "paySystemId"
paySystemName string Название платёжной системы (только чтение, заполняется из карточки платёжной системы)
paySystemIsCash boolean Принимает ли платёжная система наличные (только чтение)
paySystemXmlId string Внешний идентификатор платёжной системы для синхронизации (только чтение)
sum number Сумма оплаты
currency string Валюта оплаты. Список: GET /v1/currencies
paid boolean Помечена ли оплата как поступившая
datePaid datetime | null Дата отметки оплаты. null, если оплата не отмечена
empPaidId number | null Сотрудник, отметивший оплату (только чтение). Источник: GET /v1/users
comments string | null Комментарий к оплате. null, если не задан
accountNumber string Порядковый номер оплаты на портале (только чтение)
dateBill datetime Дата выставления счёта
datePayBefore datetime | null Срок оплаты — только дата. Время в ответе всегда полночь по времени портала, отдельного значения не имеет. Битрикс24 помечает поле устаревшим: оно ещё хранится и отдаётся, но новой интеграции опираться на него не стоит. null, если не задан
xmlId string Внешний идентификатор для синхронизации
responsibleId number | null Ответственный сотрудник. Источник: GET /v1/users. null, если не назначен
empResponsibleId number | null Сотрудник, ответственный за оплату (только чтение). Источник: GET /v1/users
dateResponsibleId datetime | null Дата назначения ответственного сотрудника (только чтение). null, если ответственный не назначен
isReturn string Признак возврата: "N" обычная оплата, "Y" возврат, "P" частичный возврат
marked boolean Помечена ли оплата как проблемная
reasonMarked string | null Причина пометки. null, если пометки нет
empMarkedId number | null Сотрудник, поставивший пометку (только чтение). Источник: GET /v1/users
dateMarked datetime | null Дата пометки оплаты как проблемной (только чтение). null, если пометки нет
psStatus string | null Флаг статуса платёжной системы: "Y" — подтвердила оплату, "N" — не подтвердила. Не текст статуса. null, если оплата не проводилась через платёжную систему
psStatusCode string | null Код статуса от платёжной системы
psStatusDescription string | null Описание статуса от платёжной системы
psStatusMessage string | null Сообщение от платёжной системы
psSum number | null Сумма оплаты по данным платёжного шлюза
psCurrency string | null Валюта оплаты по данным платёжного шлюза
psResponseDate datetime | null Дата ответа платёжного шлюза
psInvoiceId string | null Идентификатор счёта на стороне платёжного шлюза
payVoucherNum string | null Номер платёжного поручения. null, если поручения нет
payVoucherDate datetime | null Дата платёжного поручения. null, если поручения нет
payReturnNum string | null Номер документа возврата. null, если возврата не было
payReturnDate datetime | null Дата возврата. null, если возврата не было
payReturnComment string | null Комментарий к возврату. null, если возврата не было
empReturnId number | null Сотрудник, оформивший возврат (только чтение). Источник: GET /v1/users
priceCod number Сумма наложенного платежа. 0, если наложенный платёж не задан
companyId number | null Компания-плательщик из CRM. Источник: GET /v1/companies. Битрикс24 принимает поле при создании и обновлении, но не использует его, поэтому значение не влияет на оплату. null, если не задана
externalPayment boolean Оплата создана во внешней системе
id1c string | null Идентификатор оплаты в 1С. null, если оплата не синхронизирована с 1С
version1c string | null Версия оплаты в 1С. null, если оплата не синхронизирована с 1С
updated1c boolean Обновлена ли оплата через 1С

Массив aggregatable перечисляет поля, доступные для числовых функций и groupBy в POST /v1/payments/aggregate: sum, currency, paid, paySystemId, orderId, responsibleId. Массив batch — операции для POST /v1/batch: create, update, delete.

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

Каждое поле, помимо type и readonly, содержит label (короткое название) и description (пояснение) на русском языке. Заголовками запроса язык не переключается. В примере ниже они опущены для краткости.

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "orderId": { "type": "number", "readonly": false },
      "paySystemId": { "type": "number", "readonly": false },
      "paySystemName": { "type": "string", "readonly": true },
      "paySystemIsCash": { "type": "boolean", "readonly": true },
      "paySystemXmlId": { "type": "string", "readonly": true },
      "sum": { "type": "number", "readonly": false },
      "currency": { "type": "string", "readonly": false },
      "paid": { "type": "boolean", "readonly": false },
      "datePaid": { "type": "datetime", "readonly": false },
      "empPaidId": { "type": "number", "readonly": true },
      "comments": { "type": "string", "readonly": false },
      "accountNumber": { "type": "string", "readonly": true },
      "dateBill": { "type": "datetime", "readonly": false },
      "datePayBefore": { "type": "datetime", "readonly": false },
      "xmlId": { "type": "string", "readonly": false },
      "responsibleId": { "type": "number", "readonly": false },
      "empResponsibleId": { "type": "number", "readonly": true },
      "dateResponsibleId": { "type": "datetime", "readonly": true },
      "isReturn": { "type": "string", "readonly": false },
      "marked": { "type": "boolean", "readonly": false },
      "reasonMarked": { "type": "string", "readonly": false },
      "empMarkedId": { "type": "number", "readonly": true },
      "dateMarked": { "type": "datetime", "readonly": true },
      "psStatus": { "type": "string", "readonly": false },
      "psStatusCode": { "type": "string", "readonly": false },
      "psStatusDescription": { "type": "string", "readonly": false },
      "psStatusMessage": { "type": "string", "readonly": false },
      "psSum": { "type": "number", "readonly": false },
      "psCurrency": { "type": "string", "readonly": false },
      "psResponseDate": { "type": "datetime", "readonly": false },
      "psInvoiceId": { "type": "string", "readonly": false },
      "payVoucherNum": { "type": "string", "readonly": false },
      "payVoucherDate": { "type": "datetime", "readonly": false },
      "payReturnNum": { "type": "string", "readonly": false },
      "payReturnDate": { "type": "datetime", "readonly": false },
      "payReturnComment": { "type": "string", "readonly": false },
      "empReturnId": { "type": "number", "readonly": true },
      "priceCod": { "type": "number", "readonly": false },
      "companyId": { "type": "number", "readonly": false },
      "externalPayment": { "type": "boolean", "readonly": false },
      "id1c": { "type": "string", "readonly": false },
      "version1c": { "type": "string", "readonly": false },
      "updated1c": { "type": "boolean", "readonly": false }
    },
    "aggregatable": ["sum", "currency", "paid", "paySystemId", "orderId", "responsibleId"],
    "batch": ["create", "update", "delete"]
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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