
## Заменить сервер приложения

`POST /v1/applications/:id/replace-server`

Переносит приложение на другой сервер: на существующий сервер владельца или на новый, который метод создаёт сам. Старый сервер не удаляется. Приложение отвязывается от него, а сервер остаётся у владельца. Перед вызовом узнайте, возможна ли замена, и выберите сервер через [`GET /v1/applications/:id/available-servers`](./available-servers.md).

Метод доступен только владельцу карточки и только его ключам. Администратор портала, который приложением не владеет, заменяет сервер в кабинете.

**Авторизация:** `X-Api-Key` со скоупом `vibe:infra`.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `id` (path) | string | да | Идентификатор приложения. Список: [`GET /v1/applications`](./list.md) |
| `Idempotency-Key` (header) | string | нет | Только для формы `new`, в форме `{ serverId }` игнорируется. От 1 до 255 символов из `A-Z`, `a-z`, `0-9`, `_`, `.`, `:`, `-`, пробелы по краям отбрасываются. Ключ действует в пределах API-ключа вызова. Как работает повтор — в «Известных особенностях» |

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

Тело принимает одну из двух форм. Поля из разных форм смешивать нельзя, лишние поля дают `400 VALIDATION_ERROR`.

**Свой существующий сервер.**

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `serverId` | string | да | Идентификатор сервера из `servers[].id` метода [`GET /v1/applications/:id/available-servers`](./available-servers.md) |

**Новый сервер.**

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `provider` | string | да | Идентификатор провайдера, как в [`POST /v1/infra/servers`](/docs/infra/servers/create) |
| `plan` | string | да | Идентификатор тарифа провайдера, как в [`POST /v1/infra/servers`](/docs/infra/servers/create) |
| `region` | string | нет | Идентификатор региона провайдера |

## Примеры

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

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server
```

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

```bash
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "srv_new"}' \
  https://vibecode.bitrix24.tech/v1/applications/cmsw806qi0000tdskiw2aegii/replace-server
```

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

```javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()

for (const warning of data.warnings) {
  console.warn('Нужно доделать вручную:', warning)
}
```

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

```javascript
const id = 'cmsw806qi0000tdskiw2aegii'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/applications/${id}/replace-server`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ serverId: 'srv_new' }),
})
const { data } = await res.json()
```

Новый сервер создаётся телом `{"provider": "bitrix-cloud", "plan": "bc-small", "region": "ru-central1-b"}`. Такой вызов платный. Чтобы повтор не создал второй сервер, передавайте заголовок `Idempotency-Key`, см. «Известные особенности».

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.serverId` | string | Идентификатор сервера, на который теперь указывает приложение |
| `data.oldServerId` | string \| null | Идентификатор прежнего сервера. `null`, если у приложения сервера не было |
| `data.branch` | string | `existing` — перенос на свой сервер, `new` — создан новый сервер |
| `data.appUrlMoved` | boolean | Перенесён ли адрес приложения на новый сервер |
| `data.warnings` | array | Что не удалось довести до конца после переноса. Пустой массив, если всё прошло. Значения — в таблице ниже |
| `data.callerKeyManagesServer` | boolean \| null | Управляет ли новым сервером ключ, которым сделан вызов. `null`, если платформа не смогла это прочитать |

Значения `data.warnings`:

| Значение | Что произошло и что делать |
|----------|---------------------------|
| `KEY_ASSIGN_FAILED` | Новый сервер не удалось передать ключу приложения. Приложение указывает на новый сервер, но ключ для управления им назначен не был |
| `APP_URL_MOVE_FAILED` | Адрес приложения не перенесён на новый сервер. Перенесите его вручную |
| `APP_URL_MANUAL` | У приложения свой адрес, платформа оставила его как есть |
| `CATALOG_STALE` | У прежнего сервера была опубликованная карточка каталога. Опубликуйте карточку заново |
| `SERVER_KEY_STALE` | На выбранном существующем сервере в окружении остался ключ приложения, который отозван или истёк. Обновите ключ в окружении сервера |
| `LOGIN_SECRET_ROTATED` | У приложения встроенный вход, а прежний сервер принадлежал другому человеку, поэтому замена сменила секрет входа. Пользователи приложения выйдут из аккаунтов, админку приложения открывают только владельцы. Настройки почты (SMTP) в админке приложения введите заново |

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

```json
{
  "success": true,
  "data": {
    "serverId": "srv_new",
    "oldServerId": "srv_old",
    "branch": "existing",
    "appUrlMoved": true,
    "warnings": [],
    "callerKeyManagesServer": true
  }
}
```

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

409 — сервер уже привязан к другому приложению:

```json
{
  "success": false,
  "error": {
    "code": "SERVER_ALREADY_LINKED",
    "message": "Server is linked to another application"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `VALIDATION_ERROR` | Тело не совпадает ни с `{ serverId }`, ни с `{ provider, plan, region? }` или содержит лишние поля |
| 400 | `INVALID_IDEMPOTENCY_KEY` | Только форма `new`: заголовок `Idempotency-Key` пустой, длиннее 255 символов или содержит недопустимые символы |
| 400 | `SERVER_ALREADY_CURRENT` | Сервер уже привязан к этому приложению |
| 400 | `INVALID_PLAN` | Только форма `new`: тарифа из `plan` нет в каталоге провайдера |
| 400 | `INVALID_REGION` | Только форма `new`: региона из `region` нет в каталоге провайдера |
| 400 | `PROVIDER_DEPRECATED` | Только форма `new`: провайдер выведен из работы |
| 400 | `KEY_NOT_ELIGIBLE` | Только форма `new`: ключ больше не может владеть сервером |
| 401 | `NO_PORTAL` | Ключ не привязан к порталу |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан: такой строки на платформе нет |
| 402 | `ACCOUNT_FROZEN` | Баланс портала заморожен. Если закрыты только платные вызовы, перенос на свой существующий сервер работает, а форма `new` получает этот отказ с `userMessage` и `alternatives` |
| 402 | `COMMERCIAL_PLAN_REQUIRED` | Только форма `new`: платформа не нашла запись портала, к которому привязан ключ, и не может проверить доступ |
| 402 | `TRIAL_PORTAL_LIMIT` | Только форма `new`: исчерпана квота серверов портала на пробном доступе |
| 402 | `PLAN_NOT_ALLOWED_ON_TRIAL` | Только форма `new`: тариф из `plan` недоступен на пробном периоде. Разрешённые тарифы — в `error.details.allowedPlans` |
| 402 | `MARKETPLACE_REQUIRED` | Только форма `new`: на портале нет активной подписки BitrixGPT + Маркетплейс, а доступ к платформе открывает она |
| 402 | `KZ_PAID_ONLY` | Только форма `new`: портал из региона KZ, доступ открывает платный или демо-тариф Битрикс24 |
| 402 | `UZ_PAID_ONLY` | Только форма `new`: портал из региона UZ, доступ открывает платный или демо-тариф Битрикс24 |
| 402 | `BY_PAID_ONLY` | Только форма `new`: портал из Беларуси, доступ открывает платный или демо-тариф Битрикс24 либо подписка Битрикс24 Маркет Плюс |
| 402 | `INT_TARIFF_REQUIRED` | Только форма `new`: аккаунт получает доступ по тарифу Битрикс24, нужен коммерческий тариф |
| 402 | `INT_VIBE_PLUS_REQUIRED` | Только форма `new`: на аккаунте Битрикс24 нужен тариф Vibe+ |
| 402 | `SELFHOSTED_NOT_AVAILABLE` | Только форма `new`: коробочный Битрикс24 пока не доступен на этой установке. Покупка тарифа отказ не снимает |
| 403 | `INFRA_SCOPE_REQUIRED` | У ключа нет скоупа `vibe:infra` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Ключ со скоупом `vibe:cowork` работает только с данными |
| 403 | `FORBIDDEN` | Приложение принадлежит не владельцу ключа |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | Управляющий ключ: нужен личный ключ или ключ авторизации |
| 403 | `PORTAL_KEY_REQUIRED` | Запись ключа повреждена и не имеет владельца |
| 403 | `INFRA_NOT_PERMITTED` | Только форма `new`: инфраструктура отключена на платформе или на портале |
| 403 | `SERVER_CREATION_DISABLED` | Только форма `new`: создание серверов запрещено политикой портала |
| 403 | `SERVER_CREATION_ADMINS_ONLY` | Только форма `new`: политика портала разрешает создавать серверы только администраторам |
| 403 | `VIBE_DEMO_EXPIRED` | Только форма `new`: тариф Vibe+ или пробный период закончился |
| 404 | `APPLICATION_NOT_FOUND` | Приложения нет на портале ключа |
| 404 | `SERVER_NOT_FOUND` | Сервера нет, он чужой или к приложению его привязать нельзя: это сервер агента, бота или хост галактики |
| 404 | `PROVIDER_NOT_FOUND` | Только форма `new`: провайдер неизвестен или закрыт для этого портала |
| 409 | `IDEMPOTENCY_KEY_ALREADY_USED` | Только форма `new`: ключ `Idempotency-Key` уже использован с другим приложением или телом, приложение с тех пор перенесено на другой сервер, либо исход прежнего вызова неизвестен |
| 409 | `IDEMPOTENCY_CONCURRENT_RETRY` | Только форма `new`: параллельный запрос занял тот же ключ `Idempotency-Key` |
| 409 | `SERVER_ALREADY_LINKED` | Сервер привязан к другому приложению |
| 409 | `APPLICATION_OP_IN_PROGRESS` | Привязку сервера к приложению меняет другая операция, либо она изменилась во время запроса. Повторите позже |
| 409 | `REISSUE_IN_PROGRESS` | Ключ приложения или его привязка к серверу заняты перевыпуском ключа, доставкой секретов или удалением. Повторите позже |
| 409 | `APPLICATION_KEY_RECOVERY_REQUIRED` | Незавершённая замена ключа блокирует перенос. Завершите или восстановите её |
| 409 | `PORTAL_ORIGIN_CUTOVER_BUSY` | Адрес портала меняет другая операция, повторите позже |
| 409 | `APPLICATION_MOVE_ACTIVE` | Приложение переезжает на новый сервер. В теле — `moveId`, `status` и `retryAfter` (секунды), тот же срок в заголовке `Retry-After`. Не создавайте новый сервер: подождите и повторите |
| 409 | `APPLICATION_MOVE_RETAINING` | После переезда прежний сервер хранится для возврата до `keepOldUntil`. Сначала удалите прежний сервер или дождитесь срока |
| 409 | `APP_LOGIN_SDK_NOT_CONFIRMED` | Приложение со встроенным входом, прежний сервер принадлежит другому человеку, а приложение переведено со входа 0.3 и запуск на SDK 0.4 не подтверждён. Ничего не изменилось. Переведите приложение на SDK 0.4 и повторите |
| 429 | `RATE_LIMITED` | 10 запросов в минуту на владельца карточки, каким бы ключом он ни вызывал |
| 429 | `SERVER_LIMIT` | Только форма `new`: достигнут лимит серверов на ключ |
| 429 | `USER_SERVER_LIMIT` | Только форма `new`: достигнут лимит серверов на человека |
| 502 | `APPLICATION_SERVER_ATTACH_FAILED` | Новый сервер создан, но привязать его не удалось. Сервер удалён, приложение осталось на старом |
| 502 | `PROVIDER_ERROR` | Только форма `new`: сбой обращения к облачному провайдеру. В ответе приходит `error.incidentCode`, назовите его поддержке |
| 502 | `PROVIDER_NOT_CONFIGURED` | Только форма `new`: провайдер не настроен на платформе — у него нет учётных данных или цены для выбранного тарифа. В ответе приходит `error.incidentCode` |
| 503 | `PORTAL_ORIGIN_CUTOVER_UNAVAILABLE` | Защита адреса портала недоступна, повторите позже |

Текст `error.message` английский и предназначен для журналов: тексты для интерфейса стройте по `error.code`. Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- **Сбой после записи связи не превращается в ошибку.** Как только приложение указывает на новый сервер, метод отвечает `200`, а то, что довести не удалось, перечисляет в `warnings`. Ошибкой ответа бывает только то, что случилось до записи связи. Клиент, который смотрит лишь на статус ответа, пропустит предупреждения: читайте `warnings` всегда.
- **Повтор формы `new` с `Idempotency-Key`.** Повтор с тем же ключом и тем же телом в течение 24 часов после первого вызова второй сервер не создаёт. Если замена завершилась, ответ `200` повторяет прежние `data.serverId`, `data.oldServerId` и `data.appUrlMoved` с пустым `data.warnings` и несёт заголовок `Idempotent-Replayed: true`. Если исход неизвестен или приложение уже перенесено на другой сервер, приходит `409 IDEMPOTENCY_KEY_ALREADY_USED`. Тогда прочитайте [`GET /v1/applications/:id`](./get.md), где `server.id` — текущий сервер приложения, и проверьте в кабинете, не появился ли отвязанный сервер, прежде чем повторять покупку. Через 24 часа защита от повтора может пропасть. Без заголовка повтор может создать второй сервер.
- **Ключ вызова не переназначается.** Управляющий ключ нового сервера — собственный ключ приложения: ключ авторизации, если он есть, иначе личный ключ. Ключ, которым вы сделали вызов, остаётся прежним. Управляет ли он новым сервером, говорит `callerKeyManagesServer`. Это `false`, когда у приложения есть ключ авторизации или целевой сервер — контейнер галактики.
- **Сервер создаётся за владельцем карточки.** Лимиты и платёжные условия применяются к нему, а не к администратору портала.
- **Старый сервер остаётся.** Он отвязан от приложения и работает у владельца. Если он вам не нужен, удалите его отдельно через [`DELETE /v1/infra/servers/:id`](/docs/infra/servers/delete).
- **Приложение со встроенным входом и чужой прежний сервер.** Если прежний сервер принадлежит не владельцу карточки, замена вместе с переносом меняет секрет входа: секрет в окружении прежнего сервера перестаёт действовать. Сессии пользователей приложения завершаются, а админка входа открыта только его владельцам: администраторы без отметки владельца в неё не попадают. База входа на диске прежнего сервера и в его резервных копиях остаётся. О смене говорит значение `LOGIN_SECRET_ROTATED` в `data.warnings`. Если прежний сервер ваш, секрет не меняется.
- **Показывать кнопку или нет, решает `available-servers`.** Он же заранее называет причину отказа для формы `new`. Остальные причины приходят кодами ошибок из таблицы выше.

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

- [Серверы для переноса приложения](./available-servers.md)
- [Карточка приложения](./get.md)
- [Создать сервер](/docs/infra/servers/create)
- [Витрина приложений](/docs/applications)
- [Ошибки](/docs/errors)
