Для AI-агентов: markdown этой страницы — /docs-content/entities/addresses/get.md индекс документации — /llms.txt

Получить адрес

GET /v1/addresses/:typeId/:entityTypeId/:entityId

Возвращает один адрес по составному ключу из трёх параметров: тип адреса, тип владельца и ID владельца.

Параметры

Параметр Тип Обяз. Описание
typeId (path) number да Тип адреса, коды с 1 по 12: 1 — фактический (в англоязычном интерфейсе Битрикс24 — Street address), 2 — второй, 3 — третий, 4 — адрес регистрации, 5 — рабочий, 6 — юридический, 7 — дополнительный, 8 — для корреспонденции, 9 — бенефициара, 10 — адрес банка, 11 — доставки, 12 — платёжный. Какие из них доступны порталу, зависит от его страновой зоны, поэтому часть кодов конкретный портал может не вернуть никогда
entityTypeId (path) number да Тип владельца: 8 — реквизит, 3 — контакт, 4 — компания, 1 — лид
entityId (path) number да ID владельца адреса. Для реквизита — ID из GET /v1/requisites
select (query) string нет Поля через запятую: city, postalCode и остальные из таблицы ответа ниже. Принимаются и исходные имена Битрикс24 — CITY проецирует city. Значение * возвращает все поля. Без select приходит полная запись. Составной ключ typeId, entityTypeId, entityId приходит всегда, даже если его не перечислили

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/addresses/1/3/9" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/addresses/1/3/9" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses/1/3/9', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Город:', data.city, 'Индекс:', data.postalCode)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses/1/3/9', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Объект адреса
data.typeId number Тип адреса
data.entityTypeId number Тип владельца
data.entityId number ID владельца
data.address1 string | null Улица, дом, корпус, строение
data.address2 string | null Квартира, офис
data.city string | null Город
data.postalCode string | null Почтовый индекс
data.region string | null Район
data.province string | null Область
data.country string | null Страна
data.countryCode string | null Код страны
data.locAddrId number Идентификатор адреса местоположения
data.anchorTypeId number Тип сущности, к которой привязан адрес (только чтение)
data.anchorId number ID сущности, к которой привязан адрес (только чтение)
meta.warnings array Приходит, когда рядом с * в select стоит имя, которого нет в схеме адресов: запись возвращается, а поля в ней нет. Каждое предупреждение — объект с полями code, field и message, код — UNKNOWN_SELECT_FIELD. Без * такое имя отклоняет весь запрос

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "typeId": 1,
    "entityTypeId": 3,
    "entityId": 9,
    "address1": null,
    "address2": null,
    "city": null,
    "postalCode": null,
    "region": null,
    "province": null,
    "country": null,
    "countryCode": null,
    "locAddrId": 0,
    "anchorTypeId": 3,
    "anchorId": 9
  }
}

Пример ответа при ошибке

404 — адрес не найден:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Address (typeId=1, entityTypeId=3, entityId=99999999) not found"
  }
}

Ошибки

HTTP Код Описание
404 NOT_FOUND Адрес с таким составным ключом не найден
400 INVALID_COMPOSITE_KEY Один из параметров пути не является положительным целым числом
400 UNKNOWN_SELECT_FIELD В select передано имя, которого нет в схеме адресов. Запрос отклоняется до чтения записи, и message перечисляет допустимые имена после слова Available. Доступные имена — Поля адреса
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Имя id в select здесь отдаёт составной ключ, а в списке и поиске его отклоняет Битрикс24. Получение по составному ключу читает запись целиком и отбирает поля на стороне Вайбкод, поэтому select=id возвращает typeId, entityTypeId и entityId. Список и поиск передают id дальше, и оттуда приходит 422 BITRIX_ERROR с текстом Unknown field definition. Имя, которого в схеме адресов нет вовсе, все три двери отклоняют одинаково — 400 UNKNOWN_SELECT_FIELD до вызова Битрикс24.

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