Cria um IP elástico

POST /cloud/network/elastic-ips

Escopo do token: ips:write · aceita Idempotency-Key · continua em segundo plano. Recurso: IPs elásticos.

O próximo endereço livre dos blocos de IP flutuante da região, opcionalmente já num servidor da mesma região. Com preço, é cobrado no ato como um servidor: contrato com o produto do bloco e a primeira fatura no cartão salvo; recusa libera o endereço e nada é cobrado (422 cloud.payment_refused). Sem resposta da operadora fica pending_payment. O job cloud-network escreve a rota no gateway (configuring → active). Limite de 10 por conta (422 cloud.quota_exceeded). Numa região sem routed_by_gateway (ou sem gateway) é recusado antes de qualquer cobrança (409 cloud.elastic_ips_unavailable). Aceita Idempotency-Key: repetir a mesma chave nunca cobra de novo.

Exemplo de requisição

Os exemplos leem o token da variável de ambiente HALVER_API_TOKEN (um token sc_live_… criado em Desenvolvedores › Tokens de API). Nunca escreva o token no código.

curl -X POST "https://dash.halver.com.br/api/v1/cloud/network/elastic-ips" \
  -H "Authorization: Bearer $HALVER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "region_id": "7991b4f0-3bd8-47f3-bd3c-30b5d9ac664e"
}'

package main

import (
  "crypto/rand"
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
  "time"
)

func main() {
  body := strings.NewReader(`{
  "region_id": "7991b4f0-3bd8-47f3-bd3c-30b5d9ac664e"
}`)
  req, err := http.NewRequest(http.MethodPost, "https://dash.halver.com.br/api/v1/cloud/network/elastic-ips", body)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer "+os.Getenv("HALVER_API_TOKEN"))
  req.Header.Set("Content-Type", "application/json")
  // Guarde a chave e repita a mesma numa nova tentativa desta operação.
  req.Header.Set("Idempotency-Key", rand.Text())
  client := &http.Client{Timeout: 2 * time.Minute}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  out, err := io.ReadAll(resp.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(resp.Status)
  fmt.Println(string(out))
}

import os
import uuid

import requests

resp = requests.post(
    "https://dash.halver.com.br/api/v1/cloud/network/elastic-ips",
    headers={
        "Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}",
        # Guarde a chave e repita a mesma numa nova tentativa desta operação.
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "region_id": "7991b4f0-3bd8-47f3-bd3c-30b5d9ac664e",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

Parâmetros

Cabeçalhos

Idempotency-Key string
Chave de idempotência (draft-ietf-httpapi-idempotency-key-header-07): de 1 a 255 caracteres ASCII visíveis, como string de Structured Field ("…") ou texto puro; gere uma nova (um UUID) para cada operação. Vale por 24 horas, por conta e credencial (o token, ou o usuário no painel). A mesma chave com a mesma requisição (método, caminho, query e corpo) repete a resposta guardada (status e corpo) com Idempotent-Replayed: true, sem cobrar nem criar de novo; com outra requisição responde 422 idempotency.key_reused; enquanto a primeira roda, 409 idempotency.in_progress com Retry-After. Toda resposta fica guardada, inclusive 5xx (uma falha pode vir depois de uma cobrança); só 401, 403, 409 e 429, que dizem que nada rodou, liberam a chave. Uma chave presa por uma requisição que morreu é liberada depois de 10 minutos. Veja Idempotência.

Corpo da requisição

application/json, obrigatório.

region_id string (uuid) obrigatório
server_id string (uuid) pode ser nulo

{
  "region_id": "7991b4f0-3bd8-47f3-bd3c-30b5d9ac664e"
}

Respostas

201

IP elástico.

Cabeçalhos:

Idempotent-Replayed: true quando a resposta foi repetida de uma requisição anterior com a mesma Idempotency-Key. Convenção desta API, como a de outras; o rascunho da IETF não define cabeçalho de repetição.
Retry-After: Segundos sugeridos até consultar de novo (GET /cloud/operations/{id} ou o recurso): a operação segue em segundo plano e avança a cada 10 s.

Campos da resposta

address string obrigatório
IPv4 público (/32).
apply_error string obrigatório
Última resposta do gateway a uma mudança que não passou (“” quando não há).
contract_id string (uuid) obrigatório pode ser nulo
created_at string (date-time) obrigatório
first_invoice_id string (uuid) obrigatório pode ser nulo
id string (uuid) obrigatório
monthly_cents integer (int64) obrigatório
region object obrigatório
- code string obrigatório
- id string (uuid) obrigatório
- name string obrigatório
server_hostname string obrigatório
server_id string (uuid) obrigatório pode ser nulo
Servidor para onde o IP vai (null = sem servidor).
status string obrigatório
pending_payment = primeira fatura em cobrança; configuring/moving/releasing = mudança indo para o gateway; failed = o gateway recusou ou não aplicou a tempo (veja apply_error). Um de: pending_payment, configuring, active, moving, releasing, failed.
suspended_at string (date-time) obrigatório pode ser nulo
Rota retirada por falta de pagamento; o endereço continua reservado e a rota volta quando a fatura é paga.

{
  "address": "198.51.100.20",
  "apply_error": "",
  "contract_id": "751e7c9a-fae2-4027-9be3-5728dfce8982",
  "created_at": "2026-10-20T18:00:00Z",
  "first_invoice_id": "36d56e13-ffa3-4af3-acc1-14aa538fb0ab",
  "id": "576fc46b-b2e5-41e7-b9a9-af387899f09a",
  "monthly_cents": 79900,
  "region": {
    "code": "br-mg-1",
    "id": "8c48d558-f6ba-472a-b7f4-e834d7d06d10",
    "name": "Minas Gerais"
  },
  "server_hostname": "web-01",
  "server_id": "307d7f63-0f00-4d4b-bc28-839d359e13a3",
  "status": "active",
  "suspended_at": null
}

Erros

Todo erro vem como application/problem+json (RFC 9457), com um code estável, a mensagem em português em detail, o motivo de cada campo em errors (nos erros de validação) e o request_id, que você informa ao suporte. Veja a lista completa de códigos.

Status	Quando	Códigos
400	Requisição inválida (JSON malformado, campo desconhecido, parâmetro inválido ou falha de validação).	`validation_failed`, `request.invalid_json`, `idempotency.invalid_key`
401	Não autenticado (token ausente, inválido ou expirado; credenciais inválidas).	`auth.unauthorized`
403	Autenticado, mas sem permissão para a área ou a operação.	`api_token.insufficient_scope`
409	Conflito (unicidade ou operação concorrente em andamento).	`idempotency.in_progress`, `cloud.elastic_ips_unavailable`
422	Entrada válida, mas viola uma regra de negócio.	`idempotency.key_reused`, `cloud.payment_refused`, `cloud.quota_exceeded`
503	Dependência (gateway de pagamento, consulta de CEP) temporariamente indisponível.	—

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "o token não tem o escopo ips:write; crie um token com esse escopo em Desenvolvedores › Tokens de API",
  "code": "api_token.insufficient_scope",
  "request_id": "6f1c0b2a9e4d7c3b5a8f0e1d"
}