[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-infra\u002Flifecycle\u002Frefresh":3,"docs-tabs-infra\u002Flifecycle\u002Frefresh":6},{"content":4,"lastmod":5},"\n## Обновить статус\n\n`POST \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Frefresh`\n\nПринудительно опрашивает облачного провайдера, получает актуальный статус и IP сервера, и обновляет запись в базе, если что-то изменилось. Полезно, когда статус в платформе расходится с реальностью — например, после провайдерских работ, зависания в `provisioning` или ручной остановки виртуальной машины через панель провайдера.\n\n## Параметры\n\n| Параметр | В | Тип | Обяз. | Описание |\n|----------|---|-----|:-----:|----------|\n| `id` | path | string (UUID) | да | ID сервера |\n\nТело запроса пустое.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Frefresh\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002FSERVER_ID\u002Frefresh\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Frefresh`,\n  { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } }\n)\nconst { data: status } = await res.json()\nconsole.log(`Актуальный статус: ${status}`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nawait fetch(\n  `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Finfra\u002Fservers\u002F${serverId}\u002Frefresh`,\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n    },\n  }\n)\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|----------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | string | Актуальный статус в верхнем регистре: `PROVISIONING`, `RUNNING`, `SLEEPING`, `ERROR` |\n| `currentState` | object | Снимок состояния — те же поля, что в `error.currentState` для 422 SERVER_WRONG_STATE: `status`, `blackholeStatus`, `hasExternalId`, `lastSeenAt` |\n| `availableActions` | string[] | Подмножество `['wake','start','reboot','sleep-now','repair','delete']` — действия, которые имеет смысл вызывать в текущем состоянии |\n\n> Поле `data` — это строка со статусом для обратной совместимости. Снимок состояния и список действий вынесены в соседние поля `currentState` и `availableActions`. Для полного снимка сервера (IP, политика и т. п.) запросите [`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id`](\u002Fdocs\u002Finfra\u002Fservers\u002Fget).\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": \"RUNNING\",\n  \"currentState\": {\n    \"status\": \"RUNNING\",\n    \"blackholeStatus\": \"CONNECTED\",\n    \"hasExternalId\": true,\n    \"lastSeenAt\": null\n  },\n  \"availableActions\": [\"reboot\", \"sleep-now\", \"delete\"]\n}\n```\n\n## Пример ответа при ошибке\n\n404 — сервер не существует:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SERVER_NOT_FOUND\",\n    \"message\": \"Server not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|----------|\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Неверный или просроченный API-ключ |\n| 404 | `SERVER_NOT_FOUND` | Сервер не существует, удалён или принадлежит другому API-ключу |\n| 429 | `RATE_LIMITED` | Превышен общий лимит запросов платформы |\n| 502 | `PROVIDER_ERROR` | Облачный провайдер вернул ошибку при опросе виртуальной машины |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n- **Может переписать статус в базе.** Если провайдер сообщает статус, отличный от текущего в базе (например, `stopped` у провайдера при `running` в базе), запись обновляется: `running → sleeping`, `sleeping → running`, появляется IP и т. п. Это главный способ «самолечения» записи в `error`.\n- **Подводный камень сравнения:** `data === 'RUNNING'`, а не `data.status === 'RUNNING'` — поле `data` намеренно сохранено как строка ради обратной совместимости. Снимок состояния и список доступных действий — соседние поля `currentState` и `availableActions`. Это отличается от [`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id`](\u002Fdocs\u002Finfra\u002Fservers\u002Fget), где вся информация внутри `data`.\n- **Идемпотентно и безопасно.** Частые вызовы не создают записи, не запускают виртуальную машину, не финализируют биллинг. Подходит для ad-hoc сверки. Для циклов опроса готовности лучше подходит [`GET \u002Fv1\u002Finfra\u002Fservers\u002F:id`](\u002Fdocs\u002Finfra\u002Fservers\u002Fget) — он даёт полный объект.\n- **Не сбивает таймер фонового монитора.** Если провайдер вернул тот же статус и IP, что уже в базе, `\u002Frefresh` не обновляет `updatedAt` — чтобы не сбить таймер внутреннего монитора, который отсчитывает таймауты `provisioning` (10 минут).\n\n## Смотрите также\n\n- [Получить сервер](\u002Fdocs\u002Finfra\u002Fservers\u002Fget) — `GET \u002Fv1\u002Finfra\u002Fservers\u002F:id` — полная картина (автоматически дёргает refresh, если статус `provisioning`).\n- [Восстановить туннель](.\u002Frepair.md) — если статус `running`, но `blackholeStatus: DISCONNECTED`.\n- [Запустить сервер](.\u002Fstart.md) — если `\u002Frefresh` показал `sleeping` неожиданно.\n","2026-06-16",{}]