Giới Thiệu

SmartSac cung cấp hai nhóm API chính:

• Device API — dành riêng cho vi điều khiển (ESP32, Arduino). Dùng Station Token để xác thực.
• Web API — dành cho ứng dụng web/mobile đã đăng nhập. Dùng Session Cookie.

Xác Thực

Mỗi trạm sạc có một Station Token riêng (tạo từ trang Quản Lý Trạm). Gửi token theo một trong ba cách:

Cấu Trúc Response

Mọi response đều là JSON với trường status:

{
  "status": "success" | "error",
  "message": "...",   // mô tả lỗi (khi status=error)
  "data": { ... }     // dữ liệu trả về (khi status=success)
}

Gửi Telemetry

HTTP 200
{ "status": "success", "message": "Đã nhận telemetry", "station": 42 }

Nhận Config & Lệnh Điều Khiển

{
  "status": "success",
  "data": {
    "station_name": "Trạm Sạc 01",
    "config": {
      "wait_time": 60,          // phút chờ trước khi sạc
      "measure_interval": 300,  // giây xác nhận đầy
      "threshold_w": 10.0,      // ngưỡng đầy (W)
      "limit_input_w": 1000,    // công suất tối đa (W)
      "max_temp_charger": 55,   // nhiệt ngắt DS (°C)
      "max_temp_battery": 55,   // nhiệt ngắt MLX (°C)
      "max_temp_env": 45,       // nhiệt ngắt môi trường (°C)
      "max_humidity": 85,       // độ ẩm ngắt (%)
      "max_time_h": 10,         // giới hạn giờ sạc
      "battery_type": "lead",   // loại pin: lead | li-ion
      "capacity_ah": 20,        // dung lượng (Ah)
      "output_a": 3.0           // dòng sạc (A)
    },
    "command": {
      "action": "charge_now"    // charge_now | charge_wait | charge_stop | ""
    },
    "telegram": {
      "enabled": true,
      "token": "123:ABC...",
      "chat_id": "987654321"
    }
  }
}

Ví dụ — ESP32 (Arduino / C++)

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* SERVER    = "https://hetcuu.com/smartsac";
const char* TOKEN     = "SK_YOUR_TOKEN_HERE";   // lấy từ trang Quản Lý Trạm

// ── Gửi telemetry ──────────────────────────────────────────
bool postTelemetry(float p, float v, float i, float ds,
                   float mlx, float dht_t, float dht_h,
                   const char* state, bool charging) {
    HTTPClient http;
    http.begin(String(SERVER) + "/api/station/device/telemetry");
    http.setTimeout(5000);
    http.addHeader("Content-Type",  "application/json");
    http.addHeader("Authorization", String("Bearer ") + TOKEN);

    StaticJsonDocument<512> doc;
    doc["p"] = p; doc["v"] = v; doc["i"] = i;
    doc["ds"] = ds; doc["mlx"] = mlx;
    doc["dht_t"] = dht_t; doc["dht_h"] = dht_h;
    doc["state"] = state;
    doc["charging"] = charging;

    String body; serializeJson(doc, body);
    int code = http.POST(body);
    http.end();
    return code == 200;
}

// ── Lấy config & lệnh điều khiển ──────────────────────────
String fetchCommand() {
    HTTPClient http;
    http.begin(String(SERVER) + "/api/station/device/config");
    http.setTimeout(5000);
    http.addHeader("Authorization", String("Bearer ") + TOKEN);

    int code = http.GET();
    if (code != 200) { http.end(); return ""; }

    String body = http.getString();
    http.end();

    StaticJsonDocument<2048> doc;
    if (deserializeJson(doc, body)) return "";

    return doc["data"]["command"]["action"] | "";
}

// ── Loop ───────────────────────────────────────────────────
unsigned long lastTelemetryMs = 0, lastConfigMs = 0;

void loop() {
    unsigned long now = millis();

    if (now - lastTelemetryMs >= 3000) {
        postTelemetry(readPower(), readVoltage(), readCurrent(),
                      readTempDS(), readTempMLX(), readTempDHT(),
                      readHumDHT(), currentStateCode(), isCharging);
        lastTelemetryMs = now;
    }

    if (now - lastConfigMs >= 7000) {
        String cmd = fetchCommand();
        if      (cmd == "charge_now")  startChargingNow();
        else if (cmd == "charge_wait") setWaitMode();
        else if (cmd == "charge_stop") stopAll();
        lastConfigMs = now;
    }
}

Ví dụ — Python

import requests, time

SERVER = "https://hetcuu.com/smartsac"
TOKEN  = "SK_YOUR_TOKEN_HERE"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

def post_telemetry(data: dict):
    r = requests.post(f"{SERVER}/api/station/device/telemetry",
                      json=data, headers=HEADERS, timeout=5)
    return r.json()

def get_command() -> str:
    r = requests.get(f"{SERVER}/api/station/device/config",
                     headers=HEADERS, timeout=5)
    return r.json().get("data", {}).get("command", {}).get("action", "")

# Ví dụ vòng lặp
while True:
    post_telemetry({"p": 150, "v": 220, "i": 0.68,
                    "ds": 38.5, "mlx": 35.2,
                    "dht_t": 30, "dht_h": 65,
                    "state": "DANG_SAC", "charging": True})
    cmd = get_command()
    if cmd: print("Lệnh từ server:", cmd)
    time.sleep(3)

Ví dụ — cURL

# Gửi telemetry
curl -X POST https://hetcuu.com/smartsac/api/station/device/telemetry \
  -H "Authorization: Bearer SK_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"p":120,"v":220,"i":0.55,"ds":36,"mlx":33,"dht_t":28,"dht_h":70,"state":"DANG_SAC","charging":true}'

# Lấy config và lệnh
curl https://hetcuu.com/smartsac/api/station/device/config \
  -H "Authorization: Bearer SK_YOUR_TOKEN"

Mã Trạng Thái Sạc

HTTP Status Codes