## Список оплат CRM

`GET /v1/crm-payments`

Возвращает все оплаты одного объекта CRM, например сделки, с фильтром и сортировкой по полям оплаты.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `entityTypeId` (query) | number | да | Тип объекта CRM. Для сделки — `2` |
| `entityId` (query) | number | да | ID объекта CRM. Для сделки — ID из [`GET /v1/deals`](/docs/entities/deals/list) |
| `filter` (query) | object | нет | Отбор по полям оплаты из таблицы «Поля ответа» — только точное совпадение значения, ключ без операторов сравнения.<br>[Синтаксис фильтрации](/docs/filtering). Пример: `?filter[paid]=Y` |
| `order` (query) | object | нет | Сортировка по полям оплаты из таблицы «Поля ответа»: `asc`, `desc`, `ASC` или `DESC`. Пример: `?order[id]=desc` |

Пагинации нет: ответ содержит все оплаты объекта за один вызов. Других query-параметров метод не принимает, `limit` и `offset` тоже отклоняются.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-payments?entityTypeId=2&entityId=8761&order[id]=asc" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/crm-payments?entityTypeId=2&entityId=8761&order[id]=asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const params = new URLSearchParams({ entityTypeId: '2', entityId: '8761', 'order[id]': 'asc' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/crm-payments?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data, meta } = await res.json()
console.log(`Оплат: ${meta.total}`, data.map(p => `${p.accountNumber} — ${p.paid}`))
```

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

```javascript
const params = new URLSearchParams({ entityTypeId: '2', entityId: '8761', 'order[id]': 'asc' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/crm-payments?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data, meta } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | `true` при успехе |
| `data` | array | Оплаты объекта. Пустой массив, если оплат нет |
| `data[].id` | number | ID оплаты |
| `data[].accountNumber` | string | Номер оплаты: номер связанного заказа и порядковый номер оплаты через `/`, например `1029/2` |
| `data[].paid` | string | Отметка оплаты: `Y` — оплачена, `N` — нет |
| `data[].datePaid` | string \| null | Время последней отметки «оплачена», ISO 8601 со смещением часового пояса. `null`, если отметки не было |
| `data[].empPaidId` | number \| null | ID сотрудника, который последним отметил оплату. Список: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].paySystemId` | number | ID платёжной системы. Список: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `data[].sum` | number | Сумма оплаты. Складывается из позиций оплаты, у новой оплаты — `0` |
| `data[].currency` | string | Код валюты. Список: [`GET /v1/currencies`](/docs/entities/currencies/list) |
| `data[].paySystemName` | string | Название платёжной системы |
| `meta.total` | number | Число оплат в `data` |

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

```json
{
  "success": true,
  "data": [
    {
      "id": 563,
      "accountNumber": "1029/1",
      "paid": "N",
      "datePaid": null,
      "empPaidId": null,
      "paySystemId": 19,
      "sum": 3000,
      "currency": "RUB",
      "paySystemName": "ЮKassa"
    },
    {
      "id": 565,
      "accountNumber": "1029/2",
      "paid": "Y",
      "datePaid": "2026-10-05T09:29:34+03:00",
      "empPaidId": 1317,
      "paySystemId": 3,
      "sum": 0,
      "currency": "RUB",
      "paySystemName": "Банковский перевод (Контакты)"
    }
  ],
  "meta": {
    "total": 2
  }
}
```

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

400 — фильтр или сортировка по полю, которого нет в ответе:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Filter and order support only payment response fields."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_FIELDS` | Не передан `entityTypeId` или `entityId`, либо значение не положительное целое |
| 400 | `UNKNOWN_FILTER_FIELD` | В `filter` или `order` поле не из таблицы «Поля ответа», ключ с оператором сравнения, направление сортировки не из `asc`, `desc`, `ASC`, `DESC`, либо передан другой query-параметр |
| 404 | `ENTITY_NOT_FOUND` | Объекта CRM с таким `entityTypeId` и `entityId` нет |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос, причина — в `error.message` |
| 403 | `BITRIX_ACCESS_DENIED` | У пользователя ключа нет доступа к объекту CRM или оплате в Битрикс24 |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Снятие отметки не очищает время и автора последней отметки.** После снятия отметки поля `datePaid` и `empPaidId` сохраняют значения последней отметки. Признак текущего состояния — только `paid`.

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

- [Получить оплату CRM](/docs/entities/crm-payments/get)
- [Создать оплату CRM](/docs/entities/crm-payments/create)
- [Доступные товарные строки](/docs/entities/crm-payments/available-products)
- [Оплаты CRM](/docs/entities/crm-payments)
- [Синтаксис фильтрации](/docs/filtering)