## Поля оплаты `GET /v1/payments/fields` Возвращает схему полей оплаты: типы, флаги только-для-чтения, список агрегируемых полей. ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/payments/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash 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`](../orders/list.md) | | `paySystemId` | number | Идентификатор платёжной системы. Узнать ID можно из существующих оплат: [`GET /v1/payments`](./list.md) или [`POST /v1/payments/aggregate`](./aggregate.md) с `groupBy: "paySystemId"` | | `paySystemName` | string | Название платёжной системы (только чтение, заполняется из карточки платёжной системы) | | `paySystemIsCash` | boolean | Принимает ли платёжная система наличные (только чтение) | | `paySystemXmlId` | string | Внешний идентификатор платёжной системы для синхронизации (только чтение) | | `sum` | number | Сумма оплаты | | `currency` | string | Валюта оплаты. Список: [`GET /v1/currencies`](/docs/entities/currencies) | | `paid` | boolean | Помечена ли оплата как поступившая | | `datePaid` | datetime \| null | Дата отметки оплаты. `null`, если оплата не отмечена | | `empPaidId` | number \| null | Сотрудник, отметивший оплату (только чтение). Источник: [`GET /v1/users`](/docs/entities/users) | | `comments` | string \| null | Комментарий к оплате. `null`, если не задан | | `accountNumber` | string | Порядковый номер оплаты на портале (только чтение) | | `dateBill` | datetime | Дата выставления счёта | | `datePayBefore` | datetime \| null | Срок оплаты — только дата. Время в ответе всегда полночь по времени портала, отдельного значения не имеет. Битрикс24 помечает поле устаревшим: оно ещё хранится и отдаётся, но новой интеграции опираться на него не стоит. `null`, если не задан | | `xmlId` | string | Внешний идентификатор для синхронизации | | `responsibleId` | number \| null | Ответственный сотрудник. Источник: [`GET /v1/users`](/docs/entities/users). `null`, если не назначен | | `empResponsibleId` | number \| null | Сотрудник, ответственный за оплату (только чтение). Источник: [`GET /v1/users`](/docs/entities/users) | | `dateResponsibleId` | datetime \| null | Дата назначения ответственного сотрудника (только чтение). `null`, если ответственный не назначен | | `isReturn` | string | Признак возврата: `"N"` обычная оплата, `"Y"` возврат, `"P"` частичный возврат | | `marked` | boolean | Помечена ли оплата как проблемная | | `reasonMarked` | string \| null | Причина пометки. `null`, если пометки нет | | `empMarkedId` | number \| null | Сотрудник, поставивший пометку (только чтение). Источник: [`GET /v1/users`](/docs/entities/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`](/docs/entities/users) | | `priceCod` | number | Сумма наложенного платежа. `0`, если наложенный платёж не задан | | `companyId` | number \| null | Компания-плательщик из CRM. Источник: [`GET /v1/companies`](/docs/entities/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`](./aggregate.md): `sum`, `currency`, `paid`, `paySystemId`, `orderId`, `responsibleId`. Массив `batch` — операции для [`POST /v1/batch`](/docs/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 — [Ошибки](/docs/errors). ## Смотрите также - [Создать оплату](./create.md) - [Обновить оплату](./update.md) - [Список оплат](./list.md) - [Агрегация оплат](./aggregate.md) - [Заказы](../orders.md) - [Entity API](/docs/entity-api)