Saldo e eventos

GET /api/v1/balance

Permissão billing:read. A recarga é feita no painel.

{
  "balance": "124.30",
  "currency": "USD"
}

GET /api/v1/transactions

Permissão billing:read. Parâmetros: offset, limit, type.

A ordem é fixa e não configurável: os mais novos primeiro, por created_at, e em caso de empate por id. Não há parâmetro de ordenação.

type: deposit, purchase, refund, commission, bonus - o que cada um significa, veja Recarga e bônus.

external_reference é o evento externo que gerou a movimentação, e não o identificador da transação (que é o id).

promo_code vem preenchido nas linhas do tipo bonus - é o código pelo qual o bônus foi creditado. Nos demais tipos é null.

Eventos

GET /api/v1/events, permissão events:read. É lido para a frente a partir de ?after=<id>, os mais antigos primeiro. Parâmetros: after, limit, type.

{
  "events": [
    {
      "id": 881,
      "type": "order.completed",
      "occurred_at": "2026-08-28T12:00:04+00:00",
      "order_id": 128,
      "package_id": 42,
      "data": {
        "family": "traffic_gateway",
        "client_reference": "deal-8891"
      }
    },
    {
      "id": 882,
      "type": "package.traffic_low",
      "occurred_at": "2026-08-28T18:31:00+00:00",
      "order_id": 128,
      "package_id": 42,
      "data": {
        "purchased_gb": "35.000",
        "left_gb": "3.410"
      }
    }
  ],
  "next_after": 882
}

Tipo	Quando	data
order.provisioning	o pedido entrou em entrega	family, client_reference
order.completed	a entrega foi concluída; também chega no prolongamento de endereços	family, client_reference
order.failed	o pedido não foi concluído	+ refunded
order.refunded	o dinheiro foi devolvido	+ refunded
package.traffic_low	o tráfego restante ficou abaixo de 10%	purchased_gb, left_gb
package.traffic_exhausted	o volume foi consumido	purchased_gb, left_gb
package.expired	o período do pacote de endereços fixos terminou, os endereços não respondem	expired_at, cut_off (true - a senha foi desativada, o prolongamento emitirá uma nova)
topup.credited	a recarga foi creditada	amount, external_reference
api_key.revoked	a chave foi revogada	api_key_id, name

Nos eventos package.*, o campo order_id é o pedido com que o pacote foi comprado.

• Entrega at-least-once: deduplique por id.
• next_after é a posição para a próxima requisição; null significa que não há eventos novos.
• events vazio significa que você alcançou o fim do log.
• Os eventos são guardados por 30 dias.

after = load_position()

while True:
    params = {"limit": 200} | ({"after": after} if after else {})
    body = session.get(f"{BASE}/api/v1/events", params=params, headers=AUTH).json()

    for event in body["events"]:
        if not already_handled(event["id"]):
            handle(event)
            mark_handled(event["id"])

    if body["next_after"] is not None:
        after = body["next_after"]
        save_position(after)

    if not body["events"]:
        sleep(15)

A entrega é feita só por consulta ao log.