# Типы плательщиков

Справочник типов плательщиков интернет-магазина. Идентификатор типа передаётся в `personTypeId` заказа и свойства заказа.

Типы с кодами `CRM_CONTACT` и `CRM_COMPANY` защищены от удаления. При изменении любого типа передавайте `name`, даже если меняете только другие поля.

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

## Операции

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

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | ID типа плательщика. Список: [`GET /v1/person-types`](./person-types/list.md) |
| `name` | string | Название. Передаётся при создании и при каждом изменении |
| `code` | string \| null | Уникальный код. Значения `CRM_CONTACT` и `CRM_COMPANY` обозначают системные типы |
| `active` | boolean | Активность типа |
| `sort` | number | Порядок сортировки |
| `xmlId` | string \| null | Внешний идентификатор |

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

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

1. **Выбирайте тип для заказа из справочника.** Поле `personTypeId` используется в [заказах](/docs/entities/orders) и [свойствах заказов](/docs/entities/order-properties).
2. **Код должен быть уникальным.** Создание или изменение с уже занятым `code` отклоняется с `422 BITRIX_ERROR`.
3. **Название нужно при каждом изменении.** Если оно должно сохраниться, прочитайте его через [`GET /v1/person-types/:id`](./person-types/get.md) и передайте в [`PATCH`](./person-types/update.md) вместе с меняемыми полями. Без `name` Битрикс24 возвращает `422 BITRIX_ERROR`.
4. **Системные типы нельзя удалить.** [`DELETE`](./person-types/delete.md) для `code: "CRM_CONTACT"` или `code: "CRM_COMPANY"` отклоняется с `422 BITRIX_ERROR`, `b24Code: "200750000003"`. Для отключения своего типа передайте в [`PATCH`](./person-types/update.md) его название и `active: false`.
5. **Сайт назначается отдельно от возвращаемых данных.** Поле `lid` есть в [описании полей](./person-types/fields.md), но отсутствует в объектах ответа. Запись `id` и `lid` запрещена с `400 READONLY_FIELD`.

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

1. Проверить существующие типы: [`GET /v1/person-types`](./person-types/list.md) или [`POST /v1/person-types/search`](./person-types/search.md).
2. Создать свой тип с названием и уникальным кодом: [`POST /v1/person-types`](./person-types/create.md).
3. Передать полученный `id` в `personTypeId` при [создании заказа](/docs/entities/orders/create) или [создании свойства заказа](/docs/entities/order-properties/create).
4. При изменении типа передать его `name` и новые значения: [`PATCH /v1/person-types/:id`](./person-types/update.md).
5. Если свой тип больше не нужен, отключить его через `active: false`. Для удаления использовать [`DELETE /v1/person-types/:id`](./person-types/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей на запрос списка или поиска | до 5000 (`limit`), по умолчанию 50. Следующие записи запрашиваются через `offset` |
| Агрегация | до 5 выражений, функции `count`, `sum`, `avg`, `min`, `max`. Для вычислений и группировки читается до 5000 записей |
| Группировка | по `active` и `code`, до 5 измерений. `groupLimit` от 1 до 1000 |
| Пакетная запись | `create`, `update`, `delete` — см. [Batch](/docs/batch) |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Заказы](/docs/entities/orders)
- [Свойства заказов](/docs/entities/order-properties)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)