Passa al contenuto principale

UC-016 — Monitorare Credito e Abbonamento

CampoValore
IDUC-016
ObiettivoVerificare abbonamento, credito residuo e quota contatti
CanaleTutti
ComplessitàBase
Tempo stimato5 minuti
API coinvolteGET /api/partner-gateway/v1/subscription, GET /api/partner-gateway/v1/subscription/contacts, 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 scende sotto i 50 EUR, evitando interruzioni di servizio.
  • Verifica quota contatti: Prima di importare 10.000 nuovi contatti, il team verifica che il piano attuale abbia capienza sufficiente.

Flusso di monitoraggio​

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

Prerequisiti​

  • API Key attiva con permessi di lettura billing
  • Abbonamento attivo sulla piattaforma Qlara

Step 1 — Verifica lo stato dell'abbonamento​

Recupera i dettagli del piano attivo e la data di scadenza.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Abbonamento attivo​

{
  "subscriptionId": "sub_abc123def456",
  "plan": "Business Pro",
  "status": "ACTIVE",
  "startDate": "2026-01-01T00:00:00+01:00",
  "endDate": "2026-12-31T23:59:59+01:00",
  "autoRenew": true,
  "features": {
    "sms": true,
    "rcs": true,
    "whatsapp": true,
    "maxContacts": 50000,
    "webhooks": true
  }
}

:::info Piano e funzionalita Il campo features indica quali canali e funzionalita sono inclusi nel tuo piano. Se un canale risulta false, le chiamate API per quel canale restituiranno 403 Forbidden. :::

Dietro le quinte — Come funziona il billing
  1. Piano: Ogni account ha un piano associato che definisce i canali abilitati, il numero massimo di contatti e il credito mensile incluso.
  2. Rinnovo: Se autoRenew e true, il piano si rinnova automaticamente alla scadenza. In caso di mancato pagamento, l'account passa in stato SUSPENDED dopo 7 giorni di grazia.
  3. Upgrade/Downgrade: Le modifiche al piano sono immediate per gli upgrade, applicate al ciclo successivo per i downgrade.
  4. Credito: Il credito viene scalato ad ogni messaggio inviato. Il costo varia per canale e destinazione.

Step 2 — Controlla il credito residuo​

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

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

Response — Credito disponibile​

{
  "balance": 1250.75,
  "currency": "EUR",
  "lastRechargeDate": "2026-04-01T00:00:00+02:00",
  "lastRechargeAmount": 500.00,
  "estimatedMessagesRemaining": {
    "sms": 35735,
    "rcs": 25015,
    "whatsapp": 17867
  }
}

:::warning Imposta alert automatici Configura un job periodico che interroga questo endpoint e invia una notifica quando balance scende sotto una soglia critica per evitare interruzioni di servizio. :::

Step 3 — Verifica la quota contatti​

Controlla quanti contatti hai utilizzato rispetto al limite del piano.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/subscription/contacts \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Quota contatti​

{
  "used": 32450,
  "total": 50000,
  "percentage": 64.9,
  "lists": 12
}
Dietro le quinte — Calcolo quota contatti
  1. Conteggio: Ogni contatto unico (per numero di telefono) viene contato una sola volta, anche se presente in più liste.
  2. Deduplicazione: Il sistema deduplica automaticamente i contatti con lo stesso numero normalizzato (es. +39347... e 0347... sono lo stesso contatto).
  3. Soglie: Al raggiungimento dell'80% della quota, la piattaforma invia una email di avviso. Al 100%, le importazioni vengono bloccate ma l'invio ai contatti esistenti resta attivo.

Risultato atteso​

StepAzioneRisultato
1GET /subscriptionPiano attivo, canali abilitati, scadenza
2GET /subscription/creditSaldo in EUR, stima messaggi rimanenti
3GET /subscription/contactsContatti usati vs. totale disponibili

Esempio completo end-to-end​

Scenario TechStore: script di monitoraggio con alert.

# 1. Verifica abbonamento attivo
echo "=== Stato Abbonamento ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{plan: .plan, status: .status, endDate: .endDate}'

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

echo "Saldo: EUR $BALANCE"

# 3. Alert se credito basso
if (( $(echo "$BALANCE < 50" | bc -l) )); then
  echo "ATTENZIONE: Credito sotto soglia critica!"
fi

# 4. Verifica quota contatti
echo "=== Quota Contatti ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/subscription/contacts \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{used: .used, total: .total, percentage: .percentage}'

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 mancante​

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e valido.

403 Forbidden — Permessi billing non abilitati​

{
  "status": "fail",
  "data": {
    "authorization": "API key does not have billing read permissions"
  }
}

Soluzione: La tua API Key deve avere i permessi di lettura billing. Contatta l'admin per abilitarli o crea una nuova chiave con i permessi corretti.

Prossimi passi​

Riferimenti​