API REST de Eziwan

La API REST de Eziwan te permite integrar la plataforma en tus herramientas actuales —SCADA, ERP, ITSM, BI— o crear tus propias aplicaciones de supervisión.

URL base y autenticación​

Punto final​

https://api.eziwan.com/v1

Autenticación Bearer​

Todas las solicitudes requieren un token API Bearer:

Authorization: Bearer np_api_xxxxxxxxxxxxxxxxxxxxxxxx

Genera un token en Configuración → API → Crear un token.

Niveles de permisos disponibles por token:

  • Solo lectura: únicamente GET — panel de control, datos, estado
  • Lectura/Escritura: GET + POST/PUT — alertas, reinicio, configuración
  • Admin: acceso completo, incluida la gestión de usuarios y la facturación

Puntos finales principales​

Dispositivos​

# Mostrar todos los dispositivos
GET /v1/devices

# Detalle de un dispositivo
GET /v1/devices/{device_id}

# Estado en tiempo real (señal, VPN, tarjeta SIM activa)
GET /v1/devices/{device_id}/status

# Historial de conectividad
GET /v1/devices/{device_id}/connectivity?from=2026-01-01&to=2026-06-01

Datos de los sensores​

# Últimos valores de todas las variables de un dispositivo
GET /v1/devices/{device_id}/data/latest

# Serie temporal de una variable
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

Alertas​

# Alertas activas sobre la organización
GET /v1/organization/alarms/active

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

# Cerrar una alerta
POST /v1/alarms/{alarm_id}/acknowledge
Body: { "comment": "Technicien en route" }

# Resolver una alerta
POST /v1/alarms/{alarm_id}/resolve
Body: { "comment": "Pompe réparée, retour à la normale" }

Medidas específicas​

# Reinicio de un dispositivo (se requiere permiso de lectura/escritura)
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

Ejemplos prácticos​

Python — Obtener los dispositivos sin conexión​

import requests

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

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

# Mostrar una lista de los dispositivos sin conexión
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 — Obtener datos de un sensor​

import requests
from datetime import datetime, timedelta

API_TOKEN = "np_api_xxxxxxxxxxxxxxxxxxxxxxxx"
DEVICE_ID = "d_a1b2c3d4"

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

# Últimas 24 horas — potencia activa
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 — Exportación a CSV para el informe mensual​

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

Webhooks​

Los webhooks envían eventos mediante notificaciones push a tu punto final HTTP.

Configuración​

Panel de control → Alertas → Webhooks → Añadir un webhook

Parámetros:

  • URL: tu punto final HTTPS (p. ej.: https://your-app.com/eziwan-events)
  • Secreto: clave HMAC-SHA256 para verificar la firma (opcional, pero recomendado)
  • Eventos: selecciona los tipos (device.offline, alarm.triggered, failover, etc.)

Formato de la carga útil​

{
  "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"
}

Verificación de la 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)

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

Eventos disponibles​

EventoDesencadenante
device.offlineDispositivo fuera de línea
device.onlineVuelta a línea
alarm.triggeredUmbral de alarma superado
alarm.resolvedAlarma resuelta
failover.activatedCambio de SIM1 a SIM2
failover.recoveredVuelta a SIM1
firmware.updatedActualización de firmware completada
provisioning.completedZTP finalizado — pasarela en línea

Integraciones de ITSM mediante webhooks​

ServiceNow​

// Script de transformación para 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​

# Creación automática de un ticket a través de la API de 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://tu-instancia.atlassian.net/rest/api/3/issue"

Límites y cuotas​

PlanSolicitudes API/díaWebhooksExportación CSV
Starter1 0002 puntos de conexión90 días
Growth10 00010 puntos de conexión1 año
Scale100 00050 puntos de conexión3 años
EnterpriseIlimitadoIlimitadoIlimitado
Documentación completa

La documentación completa de OpenAPI (Swagger) está disponible en api.eziwan.com/docs.

Contactar con el equipo técnico → | Guía de inicio rápido →

Preguntas frecuentes​

¿Cómo autenticarse en la API?​

Mediante un token «Bearer» generado desde la consola (con alcance y caducidad configurables). Los tokens se revocan al instante y cada llamada se registra junto con su emisor.

¿A qué datos se puede acceder a través de la API?​

El inventario de los equipos y su estado (señal, SIM, VPN, firmware), los datos recopilados (Modbus, sensores), el historial de alertas y las acciones de gestión (reinicio, envío de configuraciones).

¿Es posible recibir notificaciones mediante notificaciones push en lugar de mediante polling?​

Sí, mediante webhooks: la plataforma llama a tu punto final HTTP cada vez que se produce uno de los eventos seleccionados (alerta, desconexión, umbral superado), lo cual es ideal para crear tickets de ITSM o alimentar tu sistema de supervisión actual.

¿Hay límites de velocidad de descarga?​

Sí, un límite de tasa protege la plataforma; las cuotas estándar cubren con holgura las integraciones habituales y se ajustan bajo petición para usos intensivos.

Recursos relacionados​