Começando com a API

Em cinco minutos você cria um token, confere que ele funciona e lista os seus servidores.

1. Crie um token

1. Entre no portal e abra Desenvolvedores › Tokens de API.
2. Clique em Criar token.
3. Dê um nome que diga para que ele serve (“deploy no CI”, “inventário”).
4. Escolha a validade: 30, 90 ou 365 dias, ou sem validade (não recomendamos).
5. Marque só os escopos de que a integração precisa. O padrão é só leitura.
6. Copie o token. Ele aparece uma única vez: a Halver guarda só um hash e não consegue mostrá-lo de novo.

Guarde o token num cofre de segredos ou numa variável de ambiente, nunca no código:

export HALVER_API_TOKEN=sc_live_...

Contratar servidores e IPs elásticos gera cobrança.

Tokens sc_live_ e sc_test_

O prefixo diz onde o token vale:

Prefixo	Onde vale
sc_live_	Produção (dash.halver.com.br). É o token que você cria no portal.
sc_test_	Ambientes de teste. Não vale em produção.

Um token de um ambiente é recusado no outro com 401 auth.unauthorized (“token de teste (sc_test_) não vale em produção”). O prefixo também deixa scanners de segredos, como o secret scanning do GitHub, reconhecerem um token vazado. Veja Autenticação e escopos.

Escopos

Cada operação da referência diz o escopo de que precisa. Escrita inclui a leitura do mesmo recurso.

Escopo	Permite
servers:read	Listar e ver servidores, operações, planos, estoque e sistemas; ver se o console serial e a VPN da IPMI estão disponíveis
servers:write	Contratar servidores (gera cobrança), ligar, desligar, reiniciar, escolher o próximo boot, mudar hostname, tags, descrição e as referências do revendedor, desfazer um cancelamento
servers:delete	Cancelar no fim do período pago, apagar o sistema e reinstalar (apaga os dados)
servers:console	Acesso de teclado ao servidor: abrir, ler, digitar e encerrar o console serial; abrir e encerrar a VPN da IPMI
ssh_keys:read / ssh_keys:write	Ver / cadastrar, renomear e remover chaves SSH
networks:read / networks:write	Ver a rede da conta e as redes privadas / criar, alterar e apagar redes privadas e colocar ou tirar servidores delas
ips:read / ips:write	Ver / contratar (gera cobrança), mover e liberar IPs elásticos
invoices:read	Listar e ver faturas e comprovantes
payment_methods:read	Ver os cartões salvos (bandeira, final e validade)
support:read / support:write	Ver / abrir, responder e resolver chamados

GET /me responde a qualquer token.

2. Confira o token

GET /me devolve o usuário dono do token:

curl https://dash.halver.com.br/api/v1/me \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

Resposta (trecho)

{
  "user": {
    "id": "57f03ce6-f16e-4f97-a32a-418adfbf6517",
    "kind": "customer",
    "role": "owner",
    "name": "Ana Souza",
    "email": "ana@exemplo.com.br"
  },
  "permissions": ["portal:read", "portal:payments", "cloud:operate", "portal:support"]
}

permissions são as do seu papel na conta (owner, o responsável, ou viewer, só consulta). O token pode no máximo o que o papel permite, e só dentro dos escopos dele.

Um 401 quer dizer token ausente, inválido, expirado ou revogado. Veja Erros.

3. Liste os seus servidores

Com um token com servers:read:

curl "https://dash.halver.com.br/api/v1/cloud/servers?limit=50" \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

A resposta traz items e next_cursor. Veja Paginação e filtros.

4. Contrate um servidor

O caminho de um deploy pela API:

1. GET /cloud/catalog: escolha o local (site_id), o plano (plan_id) e o sistema (os_image_id). O preço mensal está em monthly_cents.
2. POST /cloud/ssh-keys: cadastre a sua chave pública, se ainda não cadastrou.
3. POST /cloud/servers com um Idempotency-Key: a instalação começa. A resposta traz operation_id.
4. GET /cloud/operations/{id} até status ser succeeded ou failed, respeitando o Retry-After. Veja Operações assíncronas.

curl -X POST https://dash.halver.com.br/api/v1/cloud/servers \
  -H "Authorization: Bearer $HALVER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"site_id":"…","plan_id":"…","os_image_id":"…","hostname":"web-01","ssh_key_ids":["…"]}'

Numa nova tentativa da mesma contratação (erro de rede, tempo esgotado), repita a mesma Idempotency-Key: a API devolve a primeira resposta sem contratar de novo. Veja Idempotência.