# Адреса

Адреса CRM-сущностей: фактический, юридический, для корреспонденции, доставки. Чаще всего привязаны к реквизиту, но тот же эндпоинт работает для контактов, компаний и лидов. У адреса нет отдельного числового `id`: конкретный адрес задаётся тремя значениями — тип адреса `typeId`, тип владельца `entityTypeId` и ID владельца `entityId`.

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

## Операции

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

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

| Поле | Описание |
|------|---------|
| `typeId` | Тип адреса, коды с `1` по `12`. Для фактического — `1`, для юридического — `6`, для корреспонденции — `8`, для доставки — `11`. Полный справочник — [Получить адрес](./addresses/get.md) |
| `entityTypeId` | Тип владельца: `8` — реквизит (также контакт, компания, лид) |
| `entityId` | ID владельца адреса |
| `address1` | Улица, дом |
| `city` | Город |
| `postalCode` | Почтовый индекс |

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

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

1. **У адреса нет отдельного числового `id`.** Адрес определяется тремя значениями: `typeId`, `entityTypeId`, `entityId`. Получение, обновление и удаление используют их в пути. Создание передаёт их в теле запроса.
2. **`typeId` — тип адреса, `entityTypeId` — тип владельца.** Один владелец может иметь несколько адресов разных типов. Для реквизита `entityTypeId` равен `8`.
3. **Набор доступных типов зависит от страновой зоны портала.** Всего кодов двенадцать, но часть из них конкретный портал не вернёт никогда — состав определяет его страна. Выбирайте нужный тип из того, что реально пришло в ответе, а не по фиксированному номеру. Для юридического адреса это `typeId` `6`, запасной вариант при его отсутствии — `1`, фактический.
4. **Имена полей — camelCase везде.** Список и получение возвращают `address1`, `city`, `postalCode`. Схема `GET /v1/addresses/fields` отдаёт те же имена: `typeId`, `address1`, `postalCode`. В `filter` и в теле запроса передавайте их же.
5. **Адреса вызываются собственными маршрутами.** Составной ключ не укладывается в общую форму Entity API, поэтому операции идут по путям `/v1/addresses/...` — по одному вызову на адрес. В сводном [`POST /v1/batch`](/docs/batch) сущность `addresses` не участвует: такой вызов отклоняется до Битрикс24 с кодом `ENTITY_CUSTOM_ROUTES` в `data.errors` по идентификатору вызова. Если в пакете есть другие рабочие вызовы, ответ остаётся `200`, а `400` приходит только когда отклонены все.

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

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Реквизиты | `GET /v1/requisites` | Владелец адреса: `entityTypeId` равен `8`, а `entityId` — это `id` реквизита. |
| Шаблоны реквизитов | `GET /v1/requisite-presets` | Шаблон набора полей реквизита-владельца. |
| Банковские реквизиты | `GET /v1/bank-details` | Банковские счета того же реквизита. |

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

1. Найти реквизит компании: [`GET /v1/requisites?filter[entityTypeId]=4&filter[entityId]=15`](./requisites/list.md).
2. Создать адрес на него: [`POST /v1/addresses`](./addresses/create.md) с `typeId`, `entityTypeId: 8` и `entityId` реквизита.
3. Прочитать или обновить адрес по тройке: [`GET /v1/addresses/:typeId/:entityTypeId/:entityId`](./addresses/get.md).

## Лимиты

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

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

- [Реквизиты компании для генерации документа](/docs/recipes/document-requisites)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)