Saldo y eventos

GET /api/v1/balance

Alcance billing:read. La recarga se hace en el panel.

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

GET /api/v1/transactions

Alcance billing:read. Parámetros: offset, limit, type.

El orden es fijo y no se puede configurar: los más nuevos primero, por created_at y, si coinciden, por id. No hay parámetro de ordenación.

type: deposit, purchase, refund, commission, bonus; qué significa cada uno, en Recargas y bonos.

external_reference es el evento externo que originó el movimiento, no el identificador de la transacción (que es id).

promo_code tiene valor en las filas de tipo bonus: es el código por el que se acreditó el bono. En los demás tipos es null.

Eventos

GET /api/v1/events, alcance events:read. Se lee hacia delante desde ?after=<id>, los más antiguos primero. 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	Cuándo	data
order.provisioning	el pedido pasó a entrega	family, client_reference
order.completed	la entrega se completó; también llega al prolongar direcciones	family, client_reference
order.failed	el pedido no se completó	+ refunded
order.refunded	el dinero se devolvió	+ refunded
package.traffic_low	el saldo restante bajó del 10%	purchased_gb, left_gb
package.traffic_exhausted	el volumen se agotó	purchased_gb, left_gb
package.expired	el plazo del paquete de direcciones fijas terminó, las direcciones no responden	expired_at, cut_off (true: la contraseña se desactivó, la prolongación emitirá una nueva)
topup.credited	la recarga se acreditó	amount, external_reference
api_key.revoked	la clave se revocó	api_key_id, name

En los eventos package.*, el campo order_id es el pedido con el que se compró el paquete.

• Entrega at-least-once: deduplique por id.
• next_after es la posición para la siguiente solicitud; null significa que no hay eventos nuevos.
• Un events vacío significa que ya alcanzó el final del registro.
• Los eventos se conservan 30 días.

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)

La entrega es solo mediante consulta del registro.