Создать адрес

POST /v1/addresses

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

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

Поле Тип Обяз. Описание
typeId number да Тип адреса. Список: GET /v1/addresses/fields (поле TYPE_ID). Примеры: 1 — регистрационный, 8 — доставки, 9 — фактический, 11 — бенефициар
entityTypeId number да Тип владельца адреса. 8 — реквизит. Другие значения возможны для контактов, компаний, лидов
entityId number да ID владельца адреса. Для реквизита — ID из GET /v1/requisites
address1 string нет Улица и дом
address2 string нет Дополнительная строка адреса
city string нет Город
region string нет Район или регион
province string нет Область или штат
postalCode string нет Почтовый индекс
country string нет Страна (текстовое название)
countryCode string нет Код страны (ISO 3166-1 alpha-2, например RU)

Полный список полей — `GET /v1/addresses/fields`.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/addresses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "city": "Москва",
    "address1": "ул. Ленина, 10",
    "postalCode": "101000"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/addresses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "city": "Москва",
    "address1": "ул. Ленина, 10"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 11,
    entityTypeId: 8,
    entityId: 1,
    city: 'Москва',
    address1: 'ул. Ленина, 10',
    postalCode: '101000',
  }),
})

const { success, data } = await res.json()
console.log('Создан адрес:', data.typeId, data.entityTypeId, data.entityId)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/addresses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 11,
    entityTypeId: 8,
    entityId: 1,
    city: 'Москва',
    address1: 'ул. Ленина, 10',
  }),
})

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

Поля ответа

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

Ответ возвращает только ключ. Поля адреса — city, address1, postalCode и другие — в ответ не включаются. Прочитать сохранённый адрес — `GET /v1/addresses/:typeId/:entityTypeId/:entityId`.

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

HTTP-статус: 201 Created

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

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

400 — не передан один из ключевых параметров:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_COMPOSITE_KEY",
    "message": "POST /v1/addresses requires typeId, entityTypeId and entityId in the body. Example: { \"typeId\": 1, \"entityTypeId\": 8, \"entityId\": 42, \"city\": \"...\" }"
  }
}

Ошибки

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

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

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

Ключ — в теле, не в пути. В отличие от обновления и удаления, при создании три значения — typeId, entityTypeId, entityId — передаются в теле запроса, а не в URL.

Ответ — только ключ. Ответ 201 возвращает только переданные typeId, entityTypeId и entityId. Сохранённых полей адреса в нём нет.

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