Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Saldo e ricariche automatiche

Lezione 11 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Monitorare e automatizzare le ricariche
  2. Verificare i dettagli del saldo
  3. Sistema di ricarica automatica
  4. Previsione dei consumi
  5. Dashboard di monitoraggio integrata
  6. Punti chiave

Monitorare e automatizzare le ricariche

Combinare il monitoraggio del saldo prepagato con le analisi di utilizzo ti permette di configurare un sistema di ricarica intelligente. Invece di effettuare ricariche manuali, puoi automatizzare il processo basandoti su soglie e previsioni di consumo.

Verificare i dettagli del saldo

L’endpoint restituisce due elementi che non devi confondere: il saldo istantaneo e lo storico delle transazioni. Il primo risponde alla domanda «Posso ancora chiamare l’API?», il secondo a «Quanto velocemente sto consumando?». È il secondo che ti consente di anticipare gli eventi e, di conseguenza, l’unico su cui puoi basare l’automazione.

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

La risposta contiene il saldo corrente e lo storico delle transazioni (acquisti e consumi).

Sistema di ricarica automatica

Un sistema di ricarica automatica ben configurato si basa su due numeri, uno dei quali viene spesso dimenticato. La soglia di attivazione deve coprire il tuo consumo durante il tempo di reazione: se controlli una volta al giorno, ti serve almeno un giorno di credito in anticipo, altrimenti l’automazione scatterà dopo il superamento del limite. Il tetto mensile è la salvaguardia che manca più spesso: senza di esso, un loop difettoso nella tua applicazione può attivare ricarica dopo ricarica, e i crediti xAI non sono rimborsabili.

Questi due valori non vengono impostati arbitrariamente: la prossima sezione mostra come calcolarli in base al tuo consumo effettivo.

import requests
from datetime import datetime, timedelta

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Configurazione
MIN_BALANCE = 50.00      # Soglia di ricarica
TOP_UP_AMOUNT = 200.00   # Importo della ricarica
MAX_MONTHLY = 1000.00    # Tetto mensile

def get_balance():
    """Ottieni il saldo prepagato corrente."""
    resp = requests.get(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
        headers={"Authorization": f"Bearer {MGMT_KEY}"}
    )
    return resp.json().get("balance", 0)

def get_monthly_top_ups():
    """Calcola il totale delle ricariche per il mese corrente."""
    resp = requests.get(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
        headers={"Authorization": f"Bearer {MGMT_KEY}"}
    )
    # Filtra le transazioni per il mese corrente
    transactions = resp.json().get("transactions", [])
    current_month = datetime.now().strftime("%Y-%m")
    monthly_total = sum(
        t.get("amount", 0)
        for t in transactions
        if t.get("type") == "top-up" and t.get("date", "").startswith(current_month)
    )
    return monthly_total

def top_up(amount):
    """Esegui una ricarica."""
    resp = requests.post(
        f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/top-up",
        headers={
            "Authorization": f"Bearer {MGMT_KEY}",
            "Content-Type": "application/json"
        },
        json={"amount": amount}
    )
    return resp.status_code == 200

# Logica di ricarica
balance = get_balance()
monthly_spent = get_monthly_top_ups()

if balance < MIN_BALANCE:
    remaining_budget = MAX_MONTHLY - monthly_spent
    if remaining_budget >= TOP_UP_AMOUNT:
        if top_up(TOP_UP_AMOUNT):
            print(f"Ricarica di ${TOP_UP_AMOUNT:.2f}. Nuovo saldo stimato: ${balance + TOP_UP_AMOUNT:.2f}")
        else:
            print("Errore durante la ricarica")
    else:
        print(f"Tetto mensile raggiunto (${monthly_spent:.2f} / ${MAX_MONTHLY:.2f})")
else:
    print(f"Saldo sufficiente: ${balance:.2f}")

Previsione dei consumi

La previsione trasforma il monitoraggio in anticipazione. Una media su sette giorni è sufficiente per la maggior parte dei casi d’uso; ti fornisce una data di esaurimento, dandoti così il tempo di agire. Fai però attenzione alla stagionalità del tuo traffico: una media calcolata su una settimana lenta promette un’autonomia che svanirà non appena il traffico aumenterà.

import requests
from datetime import datetime, timedelta

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Consumo negli ultimi 7 giorni
end = datetime.now()
start = end - timedelta(days=7)

usage_resp = requests.post(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
    headers={
        "Authorization": f"Bearer {MGMT_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "analyticsRequest": {
            "timeRange": {
                "startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
                "endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
                "timezone": "Europe/Paris"
            },
            "timeUnit": "DAY",
            "values": [{"name": "cost", "aggregation": "SUM"}]
        }
    }
)

# Calcola la media giornaliera
data_points = usage_resp.json().get("dataPoints", [])
daily_costs = [p.get("value", 0) for p in data_points]
avg_daily_cost = sum(daily_costs) / len(daily_costs) if daily_costs else 0

# Stima i giorni rimanenti
balance_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
current_balance = balance_resp.json().get("balance", 0)

if avg_daily_cost > 0:
    days_remaining = current_balance / avg_daily_cost
    exhaustion_date = datetime.now() + timedelta(days=days_remaining)
    print(f"Consumo medio: ${avg_daily_cost:.2f}/giorno")
    print(f"Saldo corrente: ${current_balance:.2f}")
    print(f"Esaurimento stimato: {exhaustion_date.strftime('%m/%d/%Y')} ({days_remaining:.0f} giorni)")

Dashboard di monitoraggio integrata

La dashboard riunisce ciò che tre diversi endpoint sanno sui tuoi costi: il saldo prepagato, gli addebiti di fatturazione mensili e i limiti configurati. Separati, ognuno racconta una storia incompleta: un saldo confortevole non dice nulla sul consumo postpagato che corre in parallelo. È la riconciliazione a fornire il costo reale del mese corrente.

#!/bin/bash
echo "=== Dashboard xAI - $(date '+%m/%d/%Y %H:%M') ==="

# Saldo prepagato
BALANCE=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('balance', 'N/A'))")
echo "Saldo prepagato: \$${BALANCE}"

# Addebiti postpagati
POSTPAID=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('totalAmount', 'N/A'))")
echo "Addebiti postpagati: \$${POSTPAID}"

# Limite di spesa
LIMIT=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('monthlyLimit', 'N/A'))")
echo "Limite mensile: \$${LIMIT}"

Punti chiave

  • Automatizza le ricariche con una soglia minima e un tetto mensile
  • Usa le analisi per prevedere le date di esaurimento del credito
  • Combina saldo prepagato, addebiti postpagati e limiti in una dashboard unificata
  • I crediti non sono rimborsabili: calibra le ricariche automatiche con cautela
  • Integra questi script nel tuo cron o nella pipeline CI/CD