# Счета

Управление счетами CRM: создание, получение, обновление, удаление, фильтрация. Счёт — документ на оплату: к нему привязываются плательщик, своя компания-продавец и товарные позиции, а стадия показывает, где счёт в цикле выставления и оплаты.

Битрикс24 API: `crm.item.*`, `entityTypeId` равен `31`
Скоуп: `crm`

## Операции

- [Создать счёт](./invoices/create.md) — `POST /v1/invoices`
- [Список счетов](./invoices/list.md) — `GET /v1/invoices`
- [Получить счёт](./invoices/get.md) — `GET /v1/invoices/:id`
- [Обновить счёт](./invoices/update.md) — `PATCH /v1/invoices/:id`
- [Удалить счёт](./invoices/delete.md) — `DELETE /v1/invoices/:id`
- [Поиск счетов](./invoices/search.md) — `POST /v1/invoices/search`
- [Поля счёта](./invoices/fields.md) — `GET /v1/invoices/fields`
- [Агрегация счетов](./invoices/aggregate.md) — `POST /v1/invoices/aggregate`
- [Получить товары](./invoices/products-get.md) — `GET /v1/invoices/:id/products`
- [Установить товары](./invoices/products-set.md) — `PUT /v1/invoices/:id/products`
- [Добавить товар](./invoices/products-add.md) — `POST /v1/invoices/:id/products`
- [Удалить товар](./invoices/products-delete.md) — `DELETE /v1/invoices/:id/products/:rowId`
- [Получить товар](./invoices/products-get-single.md) — `GET /v1/invoices/:id/products/:rowId`
- [Обновить товар](./invoices/products-update.md) — `PATCH /v1/invoices/:id/products/:rowId`
- [Поля товаров](./invoices/products-fields.md) — `GET /v1/invoices/:id/products/fields`
- [Импорт записей](../import.md) — `POST /v1/invoices/import`

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор счёта, только чтение |
| `title` | string | Название счёта. Без него подставляется `Счёт #<id>` |
| `stageId` | string | Стадия, формат `DT31_{categoryId}:{stage}`. Список: [`GET /v1/statuses?filter[entityId]=SMART_INVOICE_STAGE_{categoryId}`](./statuses/list.md) |
| `categoryId` | number | Идентификатор воронки счетов. Набор воронок портальный, узнать — `GET /v1/invoices?limit=1&select=categoryId` |
| `opportunity` | number | Сумма счёта |
| `currencyId` | string | Валюта. Список: [`GET /v1/currencies`](/docs/entities/currencies) |
| `contactId` | number | Контакт-плательщик. Поиск: [`GET /v1/contacts`](/docs/entities/contacts) |
| `companyId` | number | Компания-плательщик. Поиск: [`GET /v1/companies`](/docs/entities/companies) |
| `mycompanyId` | number | Своя компания-продавец, выставляющая счёт. Поиск: [`GET /v1/companies`](/docs/entities/companies) |
| `assignedById` | number | Ответственный. Список: [`GET /v1/users`](/docs/entities/users) |
| `accountNumber` | string | Печатный номер счёта |

Полный список полей — [`GET /v1/invoices/fields`](./invoices/fields.md).

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

1. **Обязательных полей при создании нет.** Пустое тело отклоняется с `400 EMPTY_CREATE_BODY`, но любого одного поля достаточно: остальное заполняется значениями портала по умолчанию, название становится `Счёт #<id>`, стадия — первой стадией воронки.
2. **Стадии портальные.** Идентификатор стадии несёт в себе воронку — `DT31_5:N` читается как «воронка 5, стадия N». Стадии одной воронки не подходят другой, а набор различается от портала к порталу, поэтому подставлять значение из примера нельзя: сначала запросите список стадий.
3. **Поля только для чтения отклоняются, неизвестные — игнорируются.** Попытка записать `id`, `createdBy`, `createdTime` и другие поля с пометкой «только чтение» даёт `400 READONLY_FIELD` и на создании, и на обновлении. Имя, которого у сущности нет вовсе, принимается и не сохраняется.
4. **Товарные позиции — отдельный ресурс.** Они не приходят в теле счёта и не записываются вместе с ним: у позиций свои операции `products-*`, причём `PUT /v1/invoices/:id/products` заменяет весь список целиком.
5. **Пользовательские поля приходят наравне со стандартными.** Поля `ufCrm_*` есть и в ответах списка, и в схеме `GET /v1/invoices/fields`, и принимаются на запись.

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

1. Найти плательщика: [`GET /v1/contacts`](./contacts/list.md) или [`GET /v1/companies`](./companies/list.md).
2. Взять воронку и её стадии: [`GET /v1/invoices?limit=1&select=categoryId`](./invoices/list.md), затем [`GET /v1/statuses?filter[entityId]=SMART_INVOICE_STAGE_5`](./statuses/list.md).
3. Создать счёт: [`POST /v1/invoices`](./invoices/create.md).
4. Наполнить товарными позициями: [`PUT /v1/invoices/:id/products`](./invoices/products-set.md).
5. Двигать по стадиям и следить за суммами: [`PATCH /v1/invoices/:id`](./invoices/update.md), [`POST /v1/invoices/aggregate`](./invoices/aggregate.md).

## Лимиты

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

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

- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Контакты](./contacts.md)
- [Компании](./companies.md)
- [Предложения](./quotes.md)