# Шлюзы vStack Serverspace API

> API шлюзов vStack создаёт ресурсы, подключает изолированные сети, меняет питание и пропускную способность, управляет правилами NAT и Firewall.

- HTML: https://poapi.ru/serverspace/shlyuzy
- Компания: Serverspace
- Страница компании: https://poapi.ru/company/serverspace
- Категории: Администрирование
- Сайт API: https://docs.serverspace.ru/docs/ru/
- Адрес API: https://api.serverspace.ru
- Документация: https://docs.serverspace.ru/docs/ru/

## Подключение и ограничения
- Авторизация: GET шлюза и правил требует ключ проекта с VstackCloud/View (OAuth: vstack:view). Создание, питание, канал, сети и изменение Firewall/NAT требуют VstackCloud/Edit (OAuth: vstack:edit). Передавайте X-API-KEY; ключ ограничен проектом.
- Ограничения: Путь шлюза имеет составной вид l{location_id}e{gateway_id}; оба параметра объявлены integer. GET detail возвращает powered_on, nics, nat_rules и firewall_rules. Создание возвращает task_id и требует подключаемые сети (максимум три); bandwidth_mbps кратен 10 Мбит/с. Правило NAT содержит type, protocol, source, destination, destination_port, translated и translated_port; порты равны 0 или лежат в диапазоне 1–65535. PUT Firewall/NAT заменяет полный набор, пустой массив очищает его.

```bash
# Нужны bash, curl и jq. Сверьте ожидаемое правило с сетевым планом.
# Пример только читает шлюз и не меняет правила или питание.
set -euo pipefail
: "${SERVERSPACE_API_KEY:?Укажите API-ключ проекта}"
: "${LOCATION_ID:?Укажите целое location_id}"
: "${GATEWAY_ID:?Укажите целое gateway_id}"
: "${NETWORK_ID:?Укажите ожидаемый ID изолированной сети}"
: "${NAT_TYPE:?Укажите SNAT, DNAT или BINAT}"
: "${NAT_SOURCE:?Укажите ожидаемый source правила}"
: "${NAT_DESTINATION:?Укажите ожидаемый destination правила}"
: "${NAT_TRANSLATED:?Укажите ожидаемый translated адрес}"
: "${NAT_PROTOCOL:?Укажите ICMP, TCP, UDP или IP}"
: "${NAT_DESTINATION_PORT:?Укажите destination_port правила}"
: "${NAT_TRANSLATED_PORT:?Укажите translated_port правила}"
[[ "$LOCATION_ID" =~ ^[0-9]+$ && "$GATEWAY_ID" =~ ^[0-9]+$ && "$NETWORK_ID" =~ ^l[0-9]+n[0-9]+$ && "$NAT_TYPE" =~ ^(SNAT|DNAT|BINAT)$ && "$NAT_PROTOCOL" =~ ^(ICMP|TCP|UDP|IP)$ && "$NAT_DESTINATION_PORT" =~ ^(0|[1-9][0-9]{0,4})$ && "$NAT_TRANSLATED_PORT" =~ ^(0|[1-9][0-9]{0,4})$ && "$NAT_DESTINATION_PORT" -le 65535 && "$NAT_TRANSLATED_PORT" -le 65535 ]] || { echo "Проверьте ID и тип NAT" >&2; exit 2; }
gateway_id="l${LOCATION_ID}e${GATEWAY_ID}"
response=$(curl --fail-with-body --silent --show-error --max-time 10 --request GET --url "https://api.serverspace.ru/api/v1/gateways/$gateway_id" --header "X-API-KEY: $SERVERSPACE_API_KEY") || exit 2
jq -e --arg network "$NETWORK_ID" --arg type "$NAT_TYPE" --arg source "$NAT_SOURCE" --arg destination "$NAT_DESTINATION" --arg translated "$NAT_TRANSLATED" --arg gateway_id "$gateway_id" --arg protocol "$NAT_PROTOCOL" --argjson destination_port "$NAT_DESTINATION_PORT" --argjson translated_port "$NAT_TRANSLATED_PORT" '.gateway as $g | ($g.id == $gateway_id) and ([$g.nics[]? | select(.network_id == $network)] | length == 1) and $g.powered_on == true and ([$g.nat_rules[]? | select(.type == $type and .source == $source and .destination == $destination and .translated == $translated and .protocol == $protocol and .destination_port == $destination_port and .translated_port == $translated_port)] | length == 1)' <<<"$response" >/dev/null || { echo "Шлюз, сеть, питание или NAT не совпали с планом" >&2; exit 1; }
jq --arg network "$NETWORK_ID" --arg type "$NAT_TYPE" '{gateway:{id:.gateway.id,name:.gateway.name,powered_on:.gateway.powered_on,nics:[.gateway.nics[] | select(.network_id == $network) | {id,network_id,ip_address,bandwidth_mbps}],nat_rules:[.gateway.nat_rules[] | select(.type == $type) | {type,protocol,source,destination,destination_port,translated,translated_port}]}}' <<<"$response"
echo "Подключение и ожидаемое правило NAT подтверждены; трафик проверьте отдельно."
```
- Результат: GET detail возвращает gateway. Код завершения 0 возможен, если ID ответа совпал с запрошенным и powered_on=true, nics содержит ровно одну ожидаемую network_id, а nat_rules — ровно одно правило с заданными type, protocol, source, destination, destination_port, translated и translated_port. Код 1 означает несовпадение плана, код 2 — неверный ввод или HTTP-ошибку. Совпадение конфигурации не подтверждает прохождение пакетов.
- Ошибки: GET detail документирует 401 при недействительном ключе, 403 при недостатке VstackCloud/View и 404 при неизвестном шлюзе. Для создания и изменения конфигурации требуется VstackCloud/Edit; DELETE возвращает ID задачи только при return_task=true.
- Проверено по документации: 2026-11-15
- [Serverspace Public API v1 — шлюзы vStack](https://docs.serverspace.ru/docs/ru/)
- [Serverspace Public API v1 — OpenAPI](https://docs.serverspace.ru/docs/ru/v1/openapi.json)
- [Тарифы и калькулятор Serverspace](https://serverspace.ru/conditions/price/)

## Описание
API шлюзов vStack создаёт и описывает пограничные шлюзы, подключает изолированные сети, меняет пропускную способность и питание, управляет тегами и наборами Firewall/NAT. Создание требует списка подключаемых сетей; один шлюз может подключить до трёх. Firewall и NAT — разные наборы: PUT заменяет весь соответствующий список, а порядок Firewall влияет на итоговое совпадение. VMware Cloud использует отдельные маршруты.

## Проверить сеть и правило NAT

Пример читает один шлюз и сверяет питание, ожидаемую network_id и ровно одно правило NAT с заданными типом, протоколом, адресами и портами. Код завершения 0 подтверждает совпадение этих параметров конфигурации.

Это не проверка маршрутизации пакетов или доступности приложения. После совпадения настроек проверьте путь из сервера и целевой сервис отдельным сетевым тестом.

## Заменять Firewall/NAT правила целиком

GET /firewall и GET /nat читают разные наборы правил. PUT каждого метода заменяет соответствующий массив; пустой список удаляет все записи. До изменения сохраните текущие правила и соберите полный новый список.

Firewall применяется последовательно, приоритет имеет последнее совпавшее правило. Тарифы отдельно учитывают канал и IP по ЦОД; проверяйте ставку для фактической локации, а не переносите её с другого региона.

## Когда использовать
- Перед сетевым тестом подтвердить, что шлюз включён, подключён к ожидаемой изолированной сети и содержит нужное правило NAT.
- Перед заменой правил прочитать текущие Firewall/NAT массивы и проверить, что полный новый набор сохраняет нужные связи.

## Порядок интеграции
1. Подготовьте location_id, gateway_id и ожидаемый network_id шлюза vStack. Для чтения требуется VstackCloud/View.
2. GET /api/v1/gateways/l{location_id}e{gateway_id} возвращает шлюз, его интерфейсы и наборы Firewall/NAT. Сверьте powered_on и network_id с планом.
3. Сверьте тип, протокол, исходный, целевой и подменный адреса, а также целевой и подменный порты правила NAT. После проверки сохранённой конфигурации выполните отдельный сетевой тест.
4. Для изменения правил сначала прочитайте весь набор и подготовьте полный желаемый массив для PUT. Пустой массив удаляет все правила, последнее совпавшее Firewall правило имеет приоритет.

## Что проверить перед запуском
- При создании шлюза укажите подключаемые сети; контракт разрешает не более трёх изолированных сетей на шлюз.
- Firewall правила выполняются последовательно, последнее совпавшее имеет приоритет. Проверяйте порядок вместе с CIDR, протоколами и портами.
- Ставки канала и IP зависят от ЦОД. Сверьте тариф до заказа; конфигурация шлюза включает больше расходов, чем только сам ресурс.

## Связанные API
- [Изолированные сети vStack Serverspace](https://poapi.ru/serverspace/izolirovannye-seti): Создавайте изолированные сети vStack в пределах одного ЦОД, меняйте их описание и проверяйте подсеть, подключённые серверы и шлюзы.
