Operações assíncronas

Instalar um servidor leva minutos. Por isso contratar, reinstalar, apagar o sistema e remover respondem na hora e continuam em segundo plano. A resposta traz o servidor com operation_id e o cabeçalho Retry-After; a partir daí, você acompanha a operação até um estado final.

Operação	Resposta	Tipo da operação
POST /cloud/servers	201	deploy
POST /cloud/servers/{id}/reinstall	200	reinstall
POST /cloud/servers/{id}/wipe	202	wipe
DELETE /cloud/servers/{id}?release=immediate	202	delete

Um DELETE /cloud/servers/{id} sem release=immediate só agenda o cancelamento para o fim do período pago (cancel_at): não abre operação na hora.

Acompanhar

GET /cloud/operations/{id}, com o operation_id do servidor:

curl https://dash.halver.com.br/api/v1/cloud/operations/38b54c25-1f8d-40fe-8cb1-649ddb710f23 \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

{
  "id": "38b54c25-1f8d-40fe-8cb1-649ddb710f23",
  "server_id": "307d7f63-0f00-4d4b-bc28-839d359e13a3",
  "type": "deploy",
  "status": "running",
  "error": "",
  "steps": [
    { "name": "prepare", "status": "done", "message": "", "started_at": "2026-10-20T18:00:04Z", "finished_at": "2026-10-20T18:00:40Z" },
    { "name": "erase", "status": "running", "message": "", "started_at": "2026-10-20T18:00:40Z", "finished_at": null }
  ],
  "requested_at": "2026-10-20T18:00:00Z",
  "started_at": "2026-10-20T18:00:04Z",
  "finished_at": null
}

status	Quer dizer	Final
pending	Registrada; ainda não começou	não
running	Uma etapa em andamento	não
succeeded	Terminou bem	sim
failed	Falhou; error resume a etapa que falhou	sim

As etapas (steps) são prepare, erase, install, configure, reboot, ready e release, cada uma pending, running, done ou failed. Nem toda operação passa por todas.

Enquanto a operação está em pending ou running, a resposta traz Retry-After com os segundos até consultar de novo (hoje, 10: as operações avançam a cada 10 segundos). Quando ela termina, o cabeçalho some.

import os
import time

import requests

def wait_operation(op_id, max_wait=2 * 60 * 60):
    url = f"https://dash.halver.com.br/api/v1/cloud/operations/{op_id}"
    headers = {"Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}"}
    deadline = time.monotonic() + max_wait
    while True:
        resp = requests.get(url, headers=headers, timeout=30)
        resp.raise_for_status()
        op = resp.json()
        if op["status"] in ("succeeded", "failed"):
            return op
        if time.monotonic() > deadline:
            raise TimeoutError(f"operação {op_id} ainda em {op['status']}")
        time.sleep(int(resp.headers.get("Retry-After", "10")))

GET /cloud/operations?server_id=… lista o histórico de um servidor, em ordem de pedido.

Prazos

• Se o motor de provisionamento não aceitar a operação, ou continuar falhando, ela termina em failed depois de 90 minutos contados do pedido, em vez de esperar para sempre.
• Uma contratação cujo pagamento ainda não foi confirmado fica em pending_payment. Sem pagamento em 1 hora, a máquina é liberada.
• Ponha no seu cliente um limite de espera generoso (o exemplo usa 2 horas). Ao estourar, consulte a operação e o servidor antes de decidir: nunca repita a contratação às cegas (veja Idempotência).

O servidor acompanha a operação

Estado do servidor
pending_payment, deploying, wiping, deleting	De passagem: uma operação em andamento
active	Instalado e no ar
empty	Sem sistema (depois de wipe); a máquina continua reservada para você
failed	A última operação falhou: reinstale ou abra um chamado

Durante uma operação, energia, reinstalação, limpeza e cancelamento respondem 409 (cloud.server_busy ou cloud.operation_running). Depois de uma remoção, GET /cloud/servers/{id} responde 404.

Rede: o estado fica no recurso

IPs elásticos e redes privadas não abrem operação: o estado fica no próprio recurso, que você consulta com GET respeitando o Retry-After da resposta.

Recurso	De passagem	Final
IP elástico	pending_payment, configuring, moving, releasing	active, failed (com apply_error)
Rede privada	configuring, deleting	active, failed
Servidor numa rede privada	connecting, removing	active, failed

Uma mudança de rede que o gateway ou o switch não aplica em 15 minutos termina em failed; uma remoção continua tentando até sair.

Webhooks

A API não envia webhooks. Para saber quando algo terminou, consulte a operação ou o recurso como acima.