# Оплаты

Управление оплатами заказов: создание, получение, обновление, удаление, поиск, агрегация. Оплата — отдельная сущность, привязанная к заказу по полю `orderId`. У одного заказа может быть несколько оплат (например, частичная предоплата + доплата при доставке), каждая со своей платёжной системой и статусом.

Битрикс24 API: `sale.payment.*`
Скоуп: `sale`

## Операции

- [Создать оплату](./payments/create.md) — `POST /v1/payments`
- [Список оплат](./payments/list.md) — `GET /v1/payments`
- [Получить оплату](./payments/get.md) — `GET /v1/payments/:id`
- [Обновить оплату](./payments/update.md) — `PATCH /v1/payments/:id`
- [Удалить оплату](./payments/delete.md) — `DELETE /v1/payments/:id`
- [Поиск оплат](./payments/search.md) — `POST /v1/payments/search`
- [Поля оплаты](./payments/fields.md) — `GET /v1/payments/fields`
- [Агрегация оплат](./payments/aggregate.md) — `POST /v1/payments/aggregate`

## Ключевые поля

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор оплаты (только чтение) |
| `accountNumber` | string | Порядковый номер оплаты на портале (только чтение) |
| `orderId` | number | Идентификатор заказа. Источник: [`GET /v1/orders`](./orders/list.md) |
| `paySystemId` | number | Идентификатор платёжной системы. На каждом портале свой набор систем. Узнать ID можно из существующих оплат: `GET /v1/payments` или `POST /v1/payments/aggregate` с `groupBy: "paySystemId"` |
| `paySystemName` | string | Название платёжной системы (только чтение, приходит из карточки платёжной системы) |
| `sum` | number | Сумма оплаты |
| `currency` | string | Валюта оплаты. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `paid` | boolean | Помечена ли оплата как поступившая |
| `datePaid` | datetime | Дата отметки оплаты |
| `dateBill` | datetime | Дата выставления счёта |
| `responsibleId` | number | Ответственный сотрудник. Источник: [`GET /v1/users`](/docs/entities/users) |
| `isReturn` | string | Признак возврата: `"N"` (обычная оплата), `"Y"` (возврат), `"P"` (частичный возврат) |
| `comments` | string | Комментарий к оплате |
| `xmlId` | string | Внешний идентификатор для синхронизации |

Полный список полей — [Поля оплаты](./payments/fields.md).

## Что нужно знать перед работой

1. **Оплата всегда привязана к заказу.** Поле `orderId` обязательно при создании — без существующего заказа оплату создать нельзя, сначала вызовите [`POST /v1/orders`](./orders/create.md). На один заказ можно зарегистрировать несколько оплат (предоплата, доплата при доставке) — каждая отдельным `POST /v1/payments`.
2. **Тело запроса плоское.** При создании и обновлении передавайте поля прямо в корне JSON: `{"orderId": 19, "paySystemId": 11, ...}`. Обёртка `fields` не нужна.
3. **Поле `isReturn` — строка, а не boolean.** Принимает три значения: `"N"` (обычная оплата), `"Y"` (возврат) и `"P"` (частичный возврат) — фильтр и обновление работают по этим строкам.
4. **Сумма заказа не пересчитывается при создании оплаты.** Регистрация оплаты не меняет статус заказа (`orders.payed`, `orders.statusId`) — обновите их отдельным [`PATCH /v1/orders/:id`](./orders/update.md), если нужно отметить заказ как оплаченный.

## Связанные сущности

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Заказы | [`GET /v1/orders/:id`](./orders/get.md) | Родительский заказ — `orderId` указывается при создании оплаты. |
| Позиции корзины | [`GET /v1/basket-items?filter[orderId]=:id`](./basket-items/list.md) | Товары в том же заказе. |
| Сотрудники | [`GET /v1/users`](/docs/entities/users) | Источник `responsibleId`. |

## Типичный сценарий

Регистрация оплаты от внешнего платёжного шлюза:

1. Найти заказ: [`GET /v1/orders?filter[xmlId]=:externalOrderId`](./orders/list.md) — например, по внешнему идентификатору заказа.
2. Создать оплату: [`POST /v1/payments`](./payments/create.md) с `orderId`, `paySystemId`, `sum`, `paid: true`, `xmlId` платёжной транзакции.
3. Обновить статус заказа после оплаты: [`PATCH /v1/orders/:id`](./orders/update.md) с `payed: true`, `statusId: "F"` (или другим финальным статусом).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Автоматическая пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Поля оплаты](./payments/fields.md)
- [Заказы](./orders.md)
- [Позиции корзины](./basket-items.md)
- [Статусы заказов](./order-statuses.md)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)