API REST Eziwan

L'API REST di Eziwan consente di integrare la piattaforma nei vostri strumenti esistenti — SCADA, ERP, ITSM, BI — oppure di creare le vostre applicazioni di monitoraggio.

URL di base e autenticazione​

Endpoint​

https://api.eziwan.com/v1

Autenticazione Bearer​

Tutte le richieste richiedono un token API Bearer:

Authorization: Bearer np_api_xxxxxxxxxxxxxxxxxxxxxxxx

Genera un token in Impostazioni → API → Crea un token.

Livelli di autorizzazione disponibili per token:

  • Solo lettura: solo GET — dashboard, dati, stato
  • Lettura/Scrittura: GET + POST/PUT — avvisi, riavvio, configurazione
  • Amministratore: accesso completo, compresa la gestione degli utenti e la fatturazione

Endpoint principali​

Dispositivi​

# Elenca tutti i dispositivi
GET /v1/devices

# Dettaglio di un dispositivo
GET /v1/devices/{device_id}

# Stato in tempo reale (segnale, VPN, SIM attiva)
GET /v1/devices/{device_id}/status

# Cronologia della connettività
GET /v1/devices/{device_id}/connectivity?from=2026-01-01&to=2026-06-01

Dati dei sensori​

# Ultimi valori di tutte le variabili di un dispositivo
GET /v1/devices/{device_id}/data/latest

# Serie temporale per una variabile
GET /v1/devices/{device_id}/data?metric=active_power&from=2026-06-01T00:00:00Z&to=2026-06-01T23:59:59Z&interval=5m

# Export CSV
GET /v1/devices/{device_id}/data/export?format=csv&from=2026-01-01&to=2026-06-30

Avvisi​

# Avvisi attivi relativi all'organizzazione
GET /v1/organization/alarms/active

# Historique des alertes
GET /v1/organization/alarms?from=2026-06-01&severity=critical

# Annullare un avviso
POST /v1/alarms/{alarm_id}/acknowledge
Body: { "comment": "Technicien en route" }

# Risolvere un avviso
POST /v1/alarms/{alarm_id}/resolve
Body: { "comment": "Pompe réparée, retour à la normale" }

Azioni relative alle misure​

# Riavvio di un dispositivo (è richiesta l'autorizzazione di lettura/scrittura)
POST /v1/devices/{device_id}/reboot

# Forcer un failover SIM
POST /v1/devices/{device_id}/failover
Body: { "target_sim": 2 }

# Logs d'audit
GET /v1/audit-logs?from=2026-01-01&to=2026-06-30&format=csv

Esempi pratici​

Python — Recuperare i dispositivi offline​

import requests

API_TOKEN = "np_api_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.eziwan.com/v1"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Elencare i dispositivi offline
response = requests.get(f"{BASE_URL}/devices", headers=headers)
devices = response.json()["data"]

offline = [d for d in devices if d["status"] == "offline"]
print(f"{len(offline)} dispositifs hors ligne :")
for d in offline:
    print(f"  - {d['name']} ({d['id']}) — hors ligne depuis {d['last_seen']}")

Python — Recuperare i dati da un sensore​

import requests
from datetime import datetime, timedelta

API_TOKEN = "np_api_xxxxxxxxxxxxxxxxxxxxxxxx"
DEVICE_ID = "d_a1b2c3d4"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Ultime 24 ore — potenza attiva
response = requests.get(
    f"https://api.eziwan.com/v1/devices/{DEVICE_ID}/data",
    headers=headers,
    params={
        "metric": "active_power",
        "from": (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z",
        "to": datetime.utcnow().isoformat() + "Z",
        "interval": "5m"
    }
)

data = response.json()["data"]
print(f"{len(data)} points retournés")
for point in data[:5]:
    print(f"  {point['timestamp']}: {point['value']} {point['unit']}")

curl — Esportazione CSV per il rapporto mensile​

curl -H "Authorization: Bearer np_api_xxxx" \
  "https://api.eziwan.com/v1/devices/d_a1b2c3d4/data/export?format=csv&from=2026-06-01&to=2026-06-30" \
  -o donnees_juin_2026.csv

Webhook​

I webhook inviano eventi tramite notifiche push al tuo endpoint HTTP.

Configurazione​

Dashboard → Avvisi → Webhook → Aggiungi un webhook

Parametri:

  • URL: il proprio endpoint HTTPS (es.: https://your-app.com/eziwan-events)
  • Secret: chiave HMAC-SHA256 per verificare la firma (facoltativo ma consigliato)
  • Eventi: seleziona i tipi (device.offline, alarm.triggered, failover, ecc.)

Formato del payload​

{
  "event": "device.offline",
  "severity": "critical",
  "timestamp": "2026-06-15T02:14:33.412Z",
  "device": {
    "id": "d_a1b2c3d4",
    "name": "GW-Valenciennes-03",
    "group": "Région Nord / Site Valenciennes",
    "tags": ["env:production", "criticite:haute"]
  },
  "detail": {
    "last_seen": "2026-06-15T02:12:01.000Z",
    "sim_active": 2,
    "rsrp_dbm": -108
  },
  "dashboard_url": "https://app.eziwan.com/devices/d_a1b2c3d4"
}

Verifica della firma​

import hmac, hashlib

def verify_eziwan_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "hmac-sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Nel vostro handler Flask/FastAPI:
# signature = request.headers.get("X-Eziwan-Signature")
# valid = verify_eziwan_webhook(request.body, signature, WEBHOOK_SECRET)

Eventi disponibili​

EventoCondizione di attivazione
device.offlineDispositivo offline
device.onlineRitorno online
alarm.triggeredSoglia di allarme superata
alarm.resolvedAllarme risolto
failover.activatedPassaggio da SIM1 a SIM2
failover.recoveredRitorno a SIM1
firmware.updatedAggiornamento firmware completato con successo
provisioning.completedZTP completato — gateway online

Integrazioni ITSM tramite webhook​

ServiceNow​

// Script di trasformazione per ServiceNow Integration Hub
(function process(/*RESTAPIRequest*/ request) {
    var body = JSON.parse(request.body.dataString);
    
    if (body.event === "device.offline" && body.severity === "critical") {
        var incident = new GlideRecord("incident");
        incident.short_description = "Gateway Eziwan hors ligne : " + body.device.name;
        incident.description = "Site : " + body.device.group + "\nDernier vu : " + body.detail.last_seen;
        incident.urgency = "1"; // Haute
        incident.impact = "2"; // Moyen
        incident.insert();
    }
})(request);

Jira Service Management​

# Creazione automatica di un ticket tramite l'API di Jira
curl -X POST \
  -H "Authorization: Bearer JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": { "key": "OPS" },
      "summary": "Gateway hors ligne : GW-Valenciennes-03",
      "description": "Site : Région Nord\nDernier contact : 2026-06-15T02:12:01Z",
      "issuetype": { "name": "Incident" },
      "priority": { "name": "High" }
    }
  }' \
  "https://votre-instance.atlassian.net/rest/api/3/issue"

Limiti e quote​

PianoRichieste API/giornoWebhookEsportazione CSV
Starter1.0002 endpoint90 giorni
Growth10.00010 endpoint1 anno
Scale100.00050 endpoint3 anni
EnterpriseIllimitatoIllimitatoIllimitato
Documentazione completa

La documentazione completa di OpenAPI (Swagger) è disponibile su api.eziwan.com/docs.

Contatta il team tecnico → | Guida rapida →

Domande frequenti​

Come effettuare l'autenticazione sull'API?​

Tramite token Bearer generato dalla console (durata e scadenza configurabili). I token vengono revocati immediatamente e ogni chiamata viene registrata con il relativo mittente.

Quali dati sono accessibili tramite l'API?​

L'inventario delle apparecchiature e il loro stato (segnale, SIM, VPN, firmware), i dati raccolti (Modbus, sensori), la cronologia degli avvisi e le azioni di gestione (riavvio, invio della configurazione).

È possibile ricevere notifiche tramite push anziché tramite polling?​

Sì, tramite webhook: la piattaforma chiama il vostro endpoint HTTP ogni volta che si verifica un evento specificato (avviso, disconnessione, superamento di una soglia), soluzione ideale per creare ticket ITSM o integrare il vostro sistema di monitoraggio esistente.

Ci sono limiti di velocità?​

Sì, un meccanismo di limitazione della frequenza protegge la piattaforma; le quote standard coprono ampiamente le integrazioni più comuni e possono essere adeguate su richiesta in caso di utilizzi intensivi.

Risorse correlate​