# Оплаты CRM

Оплаты объекта CRM, например сделки: создание оплаты, наполнение её товарами из товарных строк объекта, отметка «оплачена» и её снятие.

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

## Операции

- [Создать оплату CRM](./crm-payments/create.md) — `POST /v1/crm-payments`
- [Список оплат CRM](./crm-payments/list.md) — `GET /v1/crm-payments`
- [Получить оплату CRM](./crm-payments/get.md) — `GET /v1/crm-payments/:id`
- [Обновить оплату CRM](./crm-payments/update.md) — `PATCH /v1/crm-payments/:id`
- [Удалить оплату CRM](./crm-payments/delete.md) — `DELETE /v1/crm-payments/:id`
- [Поставить отметку «оплачена»](./crm-payments/pay.md) — `POST /v1/crm-payments/:id/pay`
- [Снять отметку «оплачена»](./crm-payments/unpay.md) — `POST /v1/crm-payments/:id/unpay`
- [Доступные товарные строки](./crm-payments/available-products.md) — `GET /v1/crm-payments/available-products`
- [Список позиций оплаты](./crm-payments/products-list.md) — `GET /v1/crm-payments/:id/products`
- [Добавить позицию](./crm-payments/products-add.md) — `POST /v1/crm-payments/:id/products`
- [Удалить позицию](./crm-payments/products-delete.md) — `DELETE /v1/crm-payments/:id/products/:itemId`
- [Изменить количество в позиции](./crm-payments/products-update.md) — `PATCH /v1/crm-payments/:id/products/:itemId`

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | ID оплаты. Тот же ID у оплаты в разделе [оплат заказов](./payments.md) |
| `accountNumber` | string | Номер оплаты: номер связанного заказа и порядковый номер оплаты через `/`, например `1035/1` |
| `paid` | string | Отметка оплаты: `Y` — оплачена, `N` — нет |
| `sum` | number | Сумма оплаты. Складывается из позиций, напрямую не задаётся |
| `paySystemId` | number | ID платёжной системы. Список: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `entityTypeId`, `entityId` | number | Объект CRM, к которому относится оплата. Для сделки `entityTypeId` равен `2`, `entityId` — ID из [`GET /v1/deals`](/docs/entities/deals/list) |
| `rowId` | number | ID товарной строки объекта при добавлении позиции. Список: [`GET /v1/crm-payments/available-products`](./crm-payments/available-products.md) |
| `itemId` | number | ID позиции оплаты для изменения и удаления. Список: [`GET /v1/crm-payments/:id/products`](./crm-payments/products-list.md) |

Полей оплаты немного, отдельного метода со схемой полей нет — полный состав в [`GET /v1/crm-payments/:id`](./crm-payments/get.md).

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

1. **Оплата всегда относится к объекту CRM.** Список оплат, создание оплаты и доступные товарные строки требуют `entityTypeId` и `entityId`. При создании оплаты по сделке у сделки появляется связанный заказ — создавать его отдельно не нужно.
2. **Сумма складывается из позиций.** Новая оплата создаётся с суммой `0`. Позиция — это часть товарной строки объекта в целом количестве, и одна товарная строка входит в оплату одной позицией. Добавленное в оплаты количество уходит из остатка строки и возвращается при удалении или уменьшении позиции.
3. **Тот же ID — в оплатах заказов.** Оплата CRM видна и в [`GET /v1/payments/:id`](./payments/get.md) со скоупом `sale`, но в другом формате: там `paid` — `true` или `false`, а ID заказа — в `orderId`. Для оплат существующего заказа, не связанного с объектом CRM, используйте [оплаты заказов](./payments.md).
4. **Отметка «оплачена» не переводит деньги.** [`POST /v1/crm-payments/:id/pay`](./crm-payments/pay.md) только ставит отметку и может запустить автоматизации, письмо или онлайн-чек. Оплату с отметкой удалить нельзя — сначала снимите её через [`POST /v1/crm-payments/:id/unpay`](./crm-payments/unpay.md).
5. **Запись подтверждается перечитанной оплатой.** Ответ на создание и изменение оплаты, отметку и её снятие, добавление позиции и изменение количества в ней содержит оплату, прочитанную после записи. Если перечитать её не удалось, приходит `meta.readbackUnavailable: true`, а `data` содержит только ID — оплаты или, при добавлении позиции, позиции и оплаты. Запись при этом уже выполнена: повторять вызов не нужно, проверьте результат по ID.

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

1. Найти товарные строки сделки с остатком: [`GET /v1/crm-payments/available-products?entityTypeId=2&entityId=:dealId`](./crm-payments/available-products.md).
2. Создать оплату по сделке: [`POST /v1/crm-payments`](./crm-payments/create.md) с `entityTypeId` и `entityId`.
3. Добавить позиции: [`POST /v1/crm-payments/:id/products`](./crm-payments/products-add.md) с `rowId` строки и целым `quantity`.
4. Проверить сумму: [`GET /v1/crm-payments/:id`](./crm-payments/get.md).
5. Когда деньги получены, поставить отметку: [`POST /v1/crm-payments/:id/pay`](./crm-payments/pay.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Пагинация списков | нет — оплаты объекта и позиции оплаты приходят все за один вызов |
| `filter` и `order` в списке оплат | только поля оплаты и точное совпадение значения |
| Количество в позиции | целое положительное. При добавлении — не больше остатка товарной строки, при изменении — не больше текущего количества позиции плюс остаток строки |
| Позиций одной товарной строки в оплате | одна |
| Пакетные вызовы | не поддерживаются: [`POST /v1/batch`](/docs/batch) отвечает `UNKNOWN_ENTITY` на `crm-payments`, эндпоинты раздела вызываются по одному |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Оплаты заказов](./payments.md)
- [Сделки](./deals.md)
- [Платёжные системы](./pay-systems.md)
- [Позиции корзины](./basket-items.md)
- [Справочник сущностей](/docs/entity-api)