ARTICLE

Enphase Monitoring API v4: เชื่อม Enlighten เข้ากับ Solar Monitor อย่างปลอดภัย.

คู่มือ Enphase Monitoring API v4 จากเอกสารทางการ: OAuth 2.0, API key, System Summary, Live Status SSE, W/Wh/% units, Grid/Battery direction, rate limits และแนวทาง normalize เข้า Solar Monitor

SolarEnergyIoTโดย Thospaakเผยแพร่ 17 ต.ค. 2569อัปเดต 17 ต.ค. 2569
ภาพประกอบบ้าน Solar และ Dashboard Solar Monitor เชื่อมต่อผ่าน API Cloud สำหรับอธิบาย Enphase Monitoring API v4

Enphase Monitoring API v4 เป็น official developer interface สำหรับอ่านข้อมูลระบบ Enphase จาก Enlighten/Enphase Cloud โดย API v4 มี contract สาธารณะละเอียดพอที่จะนำข้อมูลหลายชนิดมา normalize เข้าสู่ Solar Monitor ได้โดยไม่ต้อง reverse engineer Web/App traffic

บทความนี้โฟกัสเฉพาะ read-only monitoring: System, Summary และ Live Status สำหรับ PV / Consumption / Grid / Battery ไม่ครอบคลุม Commissioning, VPP หรือคำสั่งควบคุมอุปกรณ์

แหล่งข้อมูลหลักที่ใช้ตรวจสอบรอบนี้:

ภาพปกและแผนภาพในบทความเป็น Thospaak editorial illustration เพื่ออธิบาย architecture ไม่ใช่ screenshot จาก Enphase App/Enlighten และไม่ควรใช้ยืนยันหน้าตาอุปกรณ์หรือ UI รุ่นใดรุ่นหนึ่ง

Contract ใน repo ถูก pin จาก primary docs ปัจจุบัน ณ 17 ตุลาคม 2026 แต่ plan, quota และ commercial terms สามารถเปลี่ยนได้ ก่อน deploy จริงควรตรวจหน้า Developer Portal อีกครั้ง

ภาพรวมเส้นทางข้อมูล

Enphase Cloud ไปยัง Adapter และ Solar Monitor

แนวคิดสำคัญคือ Browser ไม่ควรถือ Client Secret, access token หรือ refresh token. หน้า Solar Monitor ในเว็บนี้จึงเป็น fixture-only prototype ส่วน deployment จริงควรให้ server-side connector เป็นผู้จัดการ OAuth, rate limit และ vendor requests แล้วส่งเฉพาะ normalized snapshot ให้ Frontend

Enphase System / IQ Gateway
        ↓
Enphase Cloud
        ↓
Monitoring API v4
        ↓
Server-side Enphase adapter
        ↓
thospaak.solar-cloud.plant-snapshot
        ↓
Solar Monitor / History / Alerts

Authentication: OAuth 2.0 + API key

เอกสาร API v4 ระบุว่าคำขอต้องมีทั้ง:

  1. OAuth 2.0 access token ใน Authorization: Bearer ...
  2. API key ของ Application ใน header ชื่อ key

Developer app ต้องได้รับ authorization จากเจ้าของ System ก่อนจึงจะอ่านข้อมูลของ System นั้นได้ ส่วน Client ID, Client Secret, refresh token และ access token เป็น server-side secret ไม่ควรส่งไปกับ JavaScript ฝั่ง Browser

สำหรับ Homeowner สามารถเริ่มจาก Developer Portal และ Watt plan ได้ ส่วน Installer มี Partner plan แยกต่างหากตาม eligibility ของ Enphase

Endpoint ที่ Adapter ใช้

PR79 เพิ่ม deterministic adapter enphase-api-v4-plant-v1 และ PR80 นำ adapter เดิมมาใช้ใน Solar Monitor โดยไม่เปลี่ยน canonical contract

หน้าที่ Official endpoint สิ่งที่ใช้
System identity GET /api/v4/systems/{system_id} ID, name, timezone, address, status
System summary GET /api/v4/systems/{system_id}/summary installed size, current PV, today/lifetime energy, report timestamps
Live Status GET /api/v4/systems/{system_id}/live_data PV, Load/Consumption, Grid, Battery, SOC, live timestamp

API v4 ยังมี production/consumption meter readings, device telemetry, event/alarm และ EV charger endpoints แต่ Solar Monitor prototype ไม่จำเป็นต้องดึงทุก surface ตั้งแต่แรก

System Summary: ใช้ได้แม้ไม่มี Streaming API

/summary เป็น endpoint สำคัญเพราะ response schema ระบุ unit ชัดเจน:

  • size_w — W
  • current_power — W
  • energy_today — Wh
  • energy_lifetime — Wh
  • last_interval_end_at — epoch timestamp
  • last_report_at — epoch timestamp

Adapter จึงแปลง W → kW และ Wh → kWh แบบ deterministic ได้

ตัวอย่าง fixture:

size_w          7,800 W    → 7.8 kW
current_power   5,200 W    → 5.2 kW
energy_today   22,100 Wh   → 22.1 kWh
energy_lifetime 18,500,000 Wh → 18,500 kWh

last_interval_end_at มีความหมายสำคัญกว่าการใช้เวลาที่ Backend เพิ่ง fetch สำเร็จ เพราะ Solar Monitor แยก measurement time ออกจาก ingest time เพื่อไม่ให้ข้อมูลเก่าดูเหมือน realtime เพียงเพราะ API request เพิ่งตอบกลับ

Live Status ไม่ใช่ REST polling ธรรมดา

/live_data ใช้ response แบบ Server-Sent Events (text/event-stream) และรับ header duration ที่เอกสารกำหนดช่วง 30–300 วินาที

ภายใน event มี timestamp_epoch เป็น epoch milliseconds และ field หลัก เช่น:

Field Unit ความหมายหลัง normalize
pv_power W PV production
consumption_power W Site load
battery_soc % Battery SOC
battery_power W + discharge, − charge
grid_power W + import, − export
grid_status enum/text Grid state เช่น On Grid / Off Grid

Enphase เป็น Vendor ที่ mapping directional power ตรงกับ canonical contract ของ Thospaak อยู่แล้ว:

Grid     + = Import      − = Export
Battery  + = Discharge   − = Charge

จึงไม่ต้อง invert เครื่องหมายแบบ Solis/Huawei

Canonical Energy Flow ที่ Solar Monitor ใช้ร่วมกันทุก Vendor

ตัวอย่าง Energy Flow ใน Solar Monitor

Enphase fixture หลักใน PR80 ใช้ค่าที่สร้างขึ้นเพื่อทดสอบ contract ไม่ใช่ข้อมูลบ้านจริง:

PV        5.5 kW
Load      3.8 kW
Grid     -0.7 kW  → EXPORT 0.7 kW
Battery  -0.9 kW  → CHARGE 0.9 kW
SOC       74%

Solar Monitor ไม่ต้องรู้ว่า Enphase ใช้ชื่อ grid_power หรือ battery_power เพราะ Adapter แปลงทุกอย่างเข้า SolarCloudPlantSnapshot ก่อน UI เสมอ

เปิดดูตัวอย่าง: Solar Monitor — Enphase fixture

ถ้าไม่มี Live Status ต้องทำอย่างไร

จุดที่ต้องระวังคือ System Summary กับ Live Status ไม่ใช่ capability เดียวกัน. Developer plan/access control และตัว System เองมีผลต่อ Streaming API

PR80 จึงเพิ่ม Scenario Lab ชื่อ Summary-only plan:

  • PV power จาก Summary ยังอ่านได้
  • Energy today/lifetime ยังอ่านได้
  • installed capacity ยังอ่านได้
  • Grid power = null
  • Load power = null
  • Battery power/SOC = null
  • issue = live-status:unavailable

นี่เป็น fail-closed behavior ที่ตั้งใจไว้ เพราะการคำนวณ Grid/Load/Battery จากสมการพลังงานโดยไม่มี measurement ที่ยืนยัน provenance อาจทำให้ Dashboard ดูแม่นทั้งที่จริงเป็นค่าประมาณ

Live Status มีเงื่อนไขมากกว่าแค่มี Token

OpenAPI ของ Enphase ระบุ error cases ของ Live Status เช่น duration ไม่อยู่ในช่วง, IQ Gateway ไม่ active/ไม่ report, system ไม่รองรับ live stream และ service connectivity errors

ดังนั้น production connector ไม่ควรตีความว่า HTTP connected = plant online หรือว่า Live Status ใช้ได้กับทุก System ที่ Summary ใช้ได้

ควรแยกอย่างน้อย:

Authentication / authorization
System connection status
Measurement freshness
Live-stream capability
Snapshot data quality

Solar Monitor ใช้ model นี้อยู่แล้ว: status, freshness และ quality เป็นคนละแกน

Plan และ Rate Limit มีผลต่อ Architecture

หน้า Developer Plans ปัจจุบันระบุ rate limit หลักของ Developer plans ดังนี้:

Plan Requests/min Requests/month Streaming API
Watt 10 1,000 ไม่รวม
Kilowatt 50 50,000 มี
Megawatt 100 300,000 มี

Kilowatt/Megawatt ระบุค่าใช้ Live Status แยกจาก API hits บนหน้า plan ปัจจุบัน ดังนั้นการออกแบบ Backend ไม่ควรเปิด /live_data ค้างหรือเรียกใหม่ถี่ ๆ โดยไม่มีเหตุผลทาง product

แนวทางที่เหมาะกว่าคือแยก workload:

  • Summary/energy — scheduled ingestion ตาม freshness ที่ product ต้องการ
  • Live Status — เปิดเฉพาะหน้า/เหตุการณ์ที่ต้องการ realtime จริง
  • Historical meter/device telemetry — ดึงตาม use case ของ chart/report
  • Retry/backoff — เคารพ 429 และ plan limits

Status mapping ใน Adapter เป็น Conservative Mapping

Enphase API มี system status หลายค่า เช่น normal, comm, micro, power, meter, battery และ status ที่เกี่ยวกับ storage/controller

Normalized contract ของ Thospaak มีเพียง:

online | offline | alarm | unknown

ดังนั้น adapter จึงทำ conservative mapping เพื่อ UI กลาง และเก็บ vendor provenance แยกไว้ ไม่ได้อ้างว่า normalized alarm เป็น severity taxonomy อย่างเป็นทางการของ Enphase

API Monitoring กับ IQ8P เป็นคนละเรื่อง

ถ้ากำลังเลือก Hardware ให้เริ่มจาก Enphase IQ8P: Microinverter 480 VA สำหรับตลาดไทย ซึ่งอธิบาย electrical limits, module compatibility และ backup architecture

ส่วนบทความนี้ตอบอีกคำถามหนึ่ง: เมื่อมี Enphase System แล้ว จะนำข้อมูล Cloud Monitoring มาใช้กับ Dashboard/Automation อย่างไรโดยไม่ทำ contract หลวม

เส้นทางจึงเป็น:

IQ8 / Gateway / Meter / Battery
        ↓
Enphase System
        ↓
Monitoring API v4
        ↓
Normalized Snapshot
        ↓
Solar Monitor

Boundary สำหรับ Production

สิ่งที่ PR80 ยังไม่ทำ:

  • เก็บ Client Secret / refresh token จริง
  • OAuth callback production
  • scheduled polling / SSE worker
  • database current/history
  • alert delivery
  • multi-tenant authorization
  • Commissioning API
  • VPP API
  • remote control

ขั้นเหล่านี้ควรเริ่มเมื่อมี Enphase account/System จริงสำหรับ integration test เพื่อให้ auth lifecycle, plan access, Gateway capability, timestamps และ rate limits ถูกพิสูจน์ด้วย deployment จริง ไม่ใช่ fixture อย่างเดียว

สรุป

Enphase เป็น Vendor ตัวที่ห้าของ Solar Cloud foundation ที่มี public primary contract แข็งแรงพอให้ normalize ได้อย่างปลอดภัย

จุดเด่นของ API v4 คือ schema, unit, timestamp และ Grid/Battery sign semantics ชัดเจน ทำให้ Adapter ไม่ต้องเดาความหมาย ส่วน Streaming/Live Status ต้องแยกจาก Summary capability และออกแบบตาม plan/rate limit จริง

สำหรับทดลอง contract ตอนนี้ให้เปิด Solar Monitor แล้วสลับระหว่าง Enphase Plant ปกติกับ Scenario Summary-only plan เพื่อดูความแตกต่างระหว่าง ข้อมูลที่ไม่มี กับ ค่า 0 จริง