Обновить адрес

PATCH /v1/addresses/:typeId/:entityTypeId/:entityId

Обновляет поля существующего адреса. Передавайте только те поля, которые нужно изменить. Полный список полей — `GET /v1/addresses/fields`.

Параметры

Параметр Тип Обяз. Описание
typeId (path) number да Тип адреса. Примеры: 1 — регистрационный, 8 — доставки, 9 — фактический, 11 — бенефициар
entityTypeId (path) number да Тип владельца: 8 — реквизит, 3 — контакт, 4 — компания, 1 — лид
entityId (path) number да ID владельца адреса. Для реквизита — ID из GET /v1/requisites

Поля запроса (body)

Поле Тип Описание
address1 string Улица и дом
address2 string Дополнительная строка адреса
city string Город
region string Район или регион
province string Область или штат
postalCode string Почтовый индекс
country string Страна (текстовое название)
countryCode string Код страны (ISO 3166-1 alpha-2, например RU)

Поля typeId, entityTypeId, entityId в теле запроса игнорируются — ключ задаётся только в пути.

Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/addresses/11/8/1" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Санкт-Петербург",
    "address1": "Невский пр., 28",
    "postalCode": "191186"
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/addresses/11/8/1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Санкт-Петербург",
    "address1": "Невский пр., 28"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses/11/8/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    city: 'Санкт-Петербург',
    address1: 'Невский пр., 28',
    postalCode: '191186',
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses/11/8/1', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    city: 'Санкт-Петербург',
    address1: 'Невский пр., 28',
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Подтверждение обновления с эхом ключа
data.typeId number Тип адреса из пути
data.entityTypeId number Тип владельца из пути
data.entityId number ID владельца из пути
data.updated boolean Всегда true при успешном обновлении

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

JSON 
{
  "success": true,
  "data": {
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "updated": true
  }
}

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

403 — нет скоупа crm:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_COMPOSITE_KEY Один или несколько параметров пути typeId, entityTypeId, entityId не являются положительными целыми числами
400 INVALID_REQUEST Тело запроса не является объектом
404 NOT_FOUND Адрес с таким составным ключом не найден
422 BITRIX_ERROR Битрикс24 отклонил обновление существующего адреса
403 SCOPE_DENIED Ключу не хватает скоупа crm. This endpoint requires 'crm' scope
401 TOKEN_MISSING Не передан X-Api-Key или ключ не имеет настроенных токенов

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

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

Ключ в пути, не в теле. Адрес определяется тройкой /:typeId/:entityTypeId/:entityId в URL. Если передать typeId, entityTypeId или entityId в теле, они будут проигнорированы — приоритет у значений из пути.

Адрес компании или контакта хранится в реквизите. Для компании (4) и контакта (3) адрес привязан к их реквизиту. Обновление по составному ключу компании или контакта автоматически применяется к нужному реквизиту, поэтому обновлять адрес можно по тому же ключу, по которому он был создан и читается. Для реквизита (8) и лида (1) ключ совпадает с местом хранения.

Адрес не найден — 404. Если адреса с таким составным ключом нет, эндпоинт возвращает 404 NOT_FOUND и не выполняет обновление.

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