Passa al contenuto principale

UC-016 — Monitorare Credito e Abbonamento

CampoValore
IDUC-016
ObiettivoVerificare abbonamento e credito residuo
CanaleTutti
ComplessitàBase
Tempo stimato5 minuti
API coinvolteGET /api/partner-gateway/v1/subscription, GET /api/partner-gateway/v1/subscription/credit

Scenari reali​

  • Dashboard billing: Il CFO di MarketingPro integra i dati di abbonamento nella dashboard interna per monitorare i costi mensili di messaggistica.
  • Alert credito basso: Il sistema di TechStore invia un alert Slack automatico quando il credito disponibile scende sotto una soglia, evitando interruzioni di servizio.

Flusso di monitoraggio​

Il diagramma mostra le due query principali per avere una visione completa dello stato del tuo account.

Prerequisiti​

  • API Key che include l'operazione SUBSCRIPTION (vedi UC-014)
  • Abbonamento attivo sulla piattaforma Qlara

Step 1 — Verifica lo stato dell'abbonamento​

Recupera il piano attivo, il suo stato e il periodo di fatturazione corrente.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Abbonamento attivo​

{
  "planCode": "annual_business",
  "status": "active",
  "billingPeriodStart": "2026-10-02T16:12:17+02:00",
  "billingPeriodEnd": "2027-10-02T01:59:59+02:00",
  "nextRenew": "2026-11-01T23:00:00Z",
  "canceled": false,
  "nextPlan": null
}
Come leggere la risposta

billingPeriodStart e billingPeriodEnd delimitano il periodo di fatturazione corrente. In un piano annuale nextRenew è il prossimo azzeramento mensile dei contatori di utilizzo, quindi cade molto prima di billingPeriodEnd. Quando canceled è true e status è ancora active, il piano resta utilizzabile fino a billingPeriodEnd e non si rinnova; nextPlan indica il piano che subentra in quel momento, oppure è null se non ne è previsto nessuno.

Dietro le quinte — Come funziona il billing
  1. Piano: Ogni account ha un solo piano attivo, identificato da planCode.
  2. Rinnovo: Il piano si rinnova alla fine di ogni periodo di fatturazione, a meno che non sia stato cancellato.
  3. Cambi di piano: Un cambio programmato per il prossimo rinnovo valorizza nextPlan e segna il piano corrente come canceled, che resta utilizzabile fino alla fine del suo periodo.
  4. Credito: Il credito viene scalato a ogni messaggio inviato. Il costo varia per canale e destinazione. Il credito riservato a operazioni ancora in corso, come una campagna programmata, è conteggiato in frozenCredit finché non si completano.

Step 2 — Controlla il credito residuo​

Verifica quanto credito è disponibile per l'invio di messaggi.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription/credit \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Credito disponibile​

{
  "credit": 50000,
  "frozenCredit": 5000,
  "availableCredit": 45000
}

Tutti e tre i valori sono in crediti: availableCredit è quanto puoi spendere subito, credit meno frozenCredit, la parte riservata alle operazioni ancora in corso.

Imposta alert automatici

Configura un job periodico che interroga questo endpoint e invia una notifica quando availableCredit scende sotto una soglia critica per evitare interruzioni di servizio.

Risultato atteso​

StepAzioneRisultato
1GET /subscriptionCodice piano, stato, periodo di fatturazione
2GET /subscription/creditCredito totale, congelato e disponibile

Esempio completo end-to-end​

Scenario TechStore: script di monitoraggio con alert.

# 1. Verifica abbonamento attivo
echo "=== Stato Abbonamento ==="
curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{planCode, status, billingPeriodEnd, canceled}'

# 2. Controlla credito residuo
echo "=== Credito Residuo ==="
AVAILABLE=$(curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription/credit \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.availableCredit')

echo "Credito disponibile: $AVAILABLE"

# 3. Alert se credito basso (soglia in crediti)
THRESHOLD=10000
if [ "$AVAILABLE" -lt "$THRESHOLD" ]; then
  echo "ATTENZIONE: Credito sotto soglia critica!"
fi

Varianti​

Monitoraggio programmato con cron​

Integra lo script in un cron job per verifiche automatiche giornaliere:

# crontab -e
# Ogni giorno alle 8:00 - verifica credito
0 8 * * * /opt/scripts/check-credit.sh >> /var/log/credit-monitor.log 2>&1

Errori comuni​

401 Unauthorized — API Key non valida o operazione non abilitata​

{
  "error": "Invalid API Key"
}

Soluzione: Verifica che l'header X-Api-Key sia presente e valido, e che la chiave includa l'operazione SUBSCRIPTION: l'API risponde 401 con lo stesso body in entrambi i casi. Per controllare le operazioni di una chiave, vedi UC-014.

Prossimi passi​

Riferimenti​