API e webhook

Ogni server Koapanel ha un'API REST pubblica per i sistemi di fatturazione e le integrazioni diverse da WHMCS: account, rivenditori, pacchetti, siti, database, posta, utilizzo, accesso con un clic e webhook. La documentazione completa, con esempi pronti da copiare, è in Chiavi API › Documentazione API; il documento OpenAPI 3.1 è all'indirizzo /api/v1/openapi.json del pannello.

Come si usa

Crea una chiave in Chiavi API e mandala in ogni richiesta: Authorization: Bearer kpk_…. La chiave agisce come il tuo account (un rivenditore vede solo i suoi clienti).
Gli errori hanno sempre la forma {"error":{"code","message","field","requestId"}}.
Gli elenchi sono a pagine: ?limit= e ?cursor=, con nextCursor nella risposta finché ci sono altre pagine (con le chiavi API 100 elementi per pagina se non indichi limit).
Le richieste POST accettano Idempotency-Key: se ripeti la stessa richiesta con la stessa chiave entro 24 ore ricevi la prima risposta, senza creare doppioni.
Ogni chiave può fare 300 richieste al minuto; le risposte indicano quante ne restano (X-RateLimit-Remaining).

Webhook

In Chiavi API › Webhook registri l'indirizzo del tuo sistema: a ogni evento (account creato, modificato, sospeso, riattivato, eliminato, spazio superato, sito creato o eliminato, nuovo rivenditore) il pannello invia una richiesta POST firmata con il segreto del webhook, che si vede una sola volta. Prova invia subito un evento di prova; Consegne mostra gli ultimi invii con l'esito. Se l'indirizzo non risponde il pannello riprova fino a 5 volte nelle due ore successive.

Gli amministratori ricevono tutti gli eventi, i rivenditori solo quelli dei propri clienti e solo verso indirizzi https:// pubblici.
Verifica sempre la firma (X-Koapanel-Signature) prima di fidarti di una richiesta: la pagina Documentazione API mostra come.

Monitoraggio (Prometheus e Grafana)

L'indirizzo /api/v1/metrics del pannello restituisce lo stato del server nel formato di Prometheus, letto anche da Grafana, Zabbix, Netdata, Datadog e Uptime Kuma: CPU, memoria, dischi, servizi attivi, siti online e sospesi, spazio di ogni sito, scadenza dei certificati, ultimo backup riuscito di ogni sito, utenti, piano della licenza e aggiornamenti disponibili.

Crea una chiave in Chiavi API con un utente amministratore (per esempio "prometheus") e salvala in un file sul server di Prometheus.
Aggiungi il pannello alla configurazione di Prometheus:

scrape_configs:
  - job_name: koapanel
    scheme: https
    metrics_path: /api/v1/metrics
    scrape_interval: 60s
    authorization:
      credentials_file: /etc/prometheus/koapanel.key
    tls_config:
      insecure_skip_verify: true   # solo se il pannello usa il certificato autofirmato
    static_configs:
      - targets: ["pannello.example.com:8443"]

Allarmi utili: koapanel_service_up == 0 (un servizio è fermo), koapanel_site_ssl_expiry_timestamp_seconds - time() < 7*86400 (certificato in scadenza), time() - koapanel_site_last_backup_timestamp_seconds > 2*86400 (backup mancante da due giorni), koapanel_disk_free_bytes / koapanel_disk_total_bytes < 0.1 (disco quasi pieno).