Paginação e filtros

Listas por cursor

Servidores, chaves SSH, redes privadas, IPs elásticos e operações são paginados por cursor:

Lista	Operação
Servidores	GET /cloud/servers
Chaves SSH	GET /cloud/ssh-keys
Redes privadas	GET /cloud/network/private-networks
IPs elásticos	GET /cloud/network/elastic-ips
Operações	GET /cloud/operations

Mande limit (de 1 a 100) e, nas páginas seguintes, o cursor que veio em next_cursor:

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

{
  "items": [{ "id": "307d7f63-0f00-4d4b-bc28-839d359e13a3", "hostname": "web-01", "status": "active" }],
  "next_cursor": "c2VydmVyc3wxNzYwOTc..."
}

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

As regras:

• A página vem em ordem de criação (o mais antigo primeiro; empate pelo id). Um recurso criado enquanto você pagina aparece numa página seguinte e nunca desloca os já lidos.
• next_cursor nulo é a última página.
• Com cursor e sem limit, as páginas têm 50 itens.
• O cursor é opaco (até 200 caracteres) e vale só para a mesma lista: um cursor de outra lista responde 400 invalid_cursor. Mantenha os mesmos filtros em todas as páginas.
• Sem limit nem cursor, a lista vem inteira, na ordem do painel, com next_cursor nulo. Para automação, prefira sempre paginar.

Para ler tudo:

import os

import requests

url = "https://dash.halver.com.br/api/v1/cloud/servers"
headers = {"Authorization": f"Bearer {os.environ['HALVER_API_TOKEN']}"}
params = {"limit": 100}
servers = []
while True:
    page = requests.get(url, headers=headers, params=params, timeout=30)
    page.raise_for_status()
    body = page.json()
    servers.extend(body["items"])
    if not body.get("next_cursor"):
        break
    params["cursor"] = body["next_cursor"]
print(len(servers))

Filtros de servidores

GET /cloud/servers aceita, junto com a paginação:

Parâmetro	Filtra
status	Um ou mais estados, separados por vírgula: pending_payment, deploying, active, failed, wiping, empty, deleting
site_id	O local
plan_id	O plano
hostname_prefix	O começo do hostname (até 63 caracteres)
tag	Uma tag (até 64 caracteres), como env=prod
external_id	O id do pedido do revendedor (no máximo um servidor)
end_customer_ref	O id do cliente final do revendedor

curl "https://dash.halver.com.br/api/v1/cloud/servers?limit=50&status=active,failed&tag=env%3Dprod" \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

Codifique os caracteres especiais na URL (= vira %3D). GET /cloud/operations filtra por servidor com server_id e pelas referências do revendedor com external_id e end_customer_ref.

external_id e end_customer_ref são ids do sistema de quem revende, gravados no deploy ou no PATCH /cloud/servers/{id}: de 1 a 128 caracteres entre letras sem acento, números e . _ : -. São ids opacos: não use nome, CPF, e-mail nem outro dado pessoal. O external_id é único na conta entre os servidores não removidos; repetido, o deploy responde 409 cloud.external_id_taken com o id do servidor existente em existing_id (Erros).

Faturas por página

GET /portal/invoices é paginada por limit (padrão 50, máximo 200) e offset, e aceita os filtros status, q (busca), contract_id, due_from e due_to (vencimento, AAAA-MM-DD), competence (AAAA-MM) e external_id e end_customer_ref (as faturas dos servidores com essa referência):

curl "https://dash.halver.com.br/api/v1/portal/invoices?limit=20&offset=40&status=open" \
  -H "Authorization: Bearer $HALVER_API_TOKEN"

{
  "data": [{ "id": "…", "number": "FAT-0000123", "amount_cents": 89900 }],
  "meta": { "limit": 20, "offset": 40, "total": 57 }
}

Para ler tudo, avance offset de limit em limit enquanto offset for menor que meta.total.

Listas inteiras

Os chamados (GET /portal/support/tickets, até os 200 mais recentes, com filtro status) e os cartões (GET /portal/payment-methods) vêm inteiros em data.