เอกสารสำหรับนักพัฒนา: API, Webhooks และ SCIM

ภาพรวม

ตั้งค่าทั้งหมดได้ในแอป HomeHQ ที่เมนู ตั้งค่า → API และการเชื่อมต่อ (เฉพาะเจ้าของและผู้ดูแลองค์กร) — รูปแบบข้อมูลเวอร์ชัน 2026-10-01 ส่งกลับในหัว X-HomeHQ-Api-Version และในทุก webhook

เริ่มใช้งานใน 2 นาที

1. เปิดแอป HomeHQ → ตั้งค่า → API และการเชื่อมต่อ → กด สร้าง API key ตั้งชื่อ (เช่น "ระบบเงินเดือน") แล้วเลือกสิทธิ์เท่าที่จำเป็น
2. คัดลอก key ที่ขึ้นต้นด้วย hhq_ เก็บในที่ปลอดภัย (เช่น ตัวแปรแวดล้อมของเซิร์ฟเวอร์) — แสดงครั้งเดียว HomeHQ เก็บเฉพาะค่าแฮช
3. ลองเรียก:

curl https://homehqth.com/api/v1/me \
  -H "Authorization: Bearer $HOMEHQ_API_KEY"

// Node.js 18+ (fetch มีในตัว)
const res = await fetch('https://homehqth.com/api/v1/members?limit=100', {
  headers: { Authorization: `Bearer ${process.env.HOMEHQ_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { data, pagination } = await res.json();
console.log(data.length, pagination.nextCursor);

การยืนยันตัวตน

ส่ง API key ในหัว Authorization: Bearer <key> ทุกคำขอ (ผ่าน HTTPS เท่านั้น) · ห้ามใส่ key ในโค้ดฝั่งเว็บเบราว์เซอร์หรือแอปมือถือ · key ไม่มีวันหมดอายุจนกว่าจะกด เพิกถอน — เพิกถอนแล้วใช้ไม่ได้ทันที · องค์กรมี key ที่ใช้งานอยู่ได้สูงสุด 20 อัน (แยก key ต่อระบบ จะได้เพิกถอนทีละระบบได้)

ถ้าองค์กรลดแพ็กเกจต่ำกว่า Business หรือแพ็กเกจหมดอายุ ทุกคำขอจะได้ 402 จนกว่าจะต่ออายุ (key เดิมยังอยู่ ไม่ต้องสร้างใหม่)

สิทธิ์ของ API key (scopes)

ทุก scope เป็นแบบอ่านอย่างเดียว · เรียก endpoint ที่ key ไม่มีสิทธิ์ จะได้ 403 INSUFFICIENT_SCOPE

รายการ Endpoint

ที่อยู่หลัก https://homehqth.com/api/v1 · ตอบเป็น JSON (UTF-8) · วันที่ใช้รูปแบบ YYYY-MM-DD ตามเวลาประเทศไทย · เวลาเป็น ISO 8601 (UTC) · เงินเป็น สตางค์ (จำนวนเต็ม เช่น 2500000 = 25,000.00 บาท)

พนักงาน — GET /members

{
  "data": [
    {
      "id": "3f2a9c1e-…",
      "employeeCode": "EMP-0012",
      "name": "สมชาย ใจดี",
      "nickname": "ชาย",
      "email": "somchai@acme.co.th",
      "role": "member",
      "employmentStatus": "active",
      "resignEffectiveDate": null,
      "seatType": "full",
      "hasAccount": true,
      "company": {
        "id": "c-…",
        "name": "บริษัท เอซีเอ็มอี จำกัด"
      },
      "branch": {
        "id": "b-…",
        "name": "สำนักงานใหญ่"
      },
      "department": {
        "id": "d-…",
        "name": "บัญชี"
      },
      "position": {
        "id": "p-…",
        "title": "นักบัญชี"
      },
      "managerId": "m-…",
      "joinedAt": "2026-03-01T02:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": true,
    "nextCursor": "WyIyMDI2LTAzLTAxIDA5OjAwOjAwKzAwIiwiM2YyYTljMWUiXQ"
  }
}

การลงเวลา — GET /attendance?from=2026-10-01&to=2026-10-31

{
  "data": [
    {
      "id": "a-…",
      "memberId": "m-…",
      "workDate": "2026-10-01",
      "checkIn": "2026-10-01T01:58:12.000Z",
      "checkOut": "2026-10-01T11:03:40.000Z",
      "mode": "office",
      "branchId": "b-…",
      "edited": false
    }
  ],
  "pagination": {
    "limit": 100,
    "hasMore": false,
    "nextCursor": null
  }
}

mode: office เข้าออฟฟิศ · wfh ทำงานที่บ้าน · onsite นอกสถานที่ · edited = ฝ่ายบุคคลแก้ไขหรือเพิ่มให้ (มีประวัติในแอป)

การลา — GET /leave-requests?from=2026-10-01&to=2026-12-31&status=approved

คืนใบลาที่ช่วงวันลาคาบเกี่ยวกับ from–to · type เป็นรหัสประเภท (เช่น sick personal vacation หรือรหัส c_… ของประเภทที่องค์กรเพิ่มเอง) · portion: full morning afternoon · status: pending, approved, rejected, cancelled

เงินเดือน — GET /payroll/runs และ /payroll/runs/{id}/payslips

{
  "data": [
    {
      "id": "r-…",
      "companyId": "c-…",
      "month": "2026-09",
      "periodStart": "2026-09-01",
      "periodEnd": "2026-09-30",
      "payDate": "2026-09-30",
      "status": "paid",
      "lockedAt": "…",
      "paidAt": "…",
      "publishedAt": "…",
      "totals": {
        "headcount": 42,
        "incomeSatang": 128450000,
        "deductionSatang": 9800000,
        "netSatang": 118650000,
        "taxSatang": 3200000,
        "ssoEmployeeSatang": 3675000,
        "ssoEmployerSatang": 3675000
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

สลิปรายคนให้เฉพาะยอดรวม: รายได้ รายการหัก สุทธิ ภาษี ประกันสังคม กองทุนสำรองเลี้ยงชีพ พร้อมชื่อ/รหัส/แผนก ณ งวดนั้น — ไม่มีเลขบัญชีธนาคารและเลขบัตรประชาชน (ไฟล์โอนธนาคารสร้างในแอปเท่านั้น)

โครงสร้างองค์กร — GET /org

คืน companies branches departments positions ทั้งหมดในครั้งเดียว ใช้จับคู่ id กับระบบของคุณ

การแบ่งหน้า

รายการทุกชนิดใช้ cursor: ส่ง limit (1–200 ค่าเริ่มต้น 50 หรือ 100 สำหรับการลงเวลา/สลิป) แล้วเรียกหน้าถัดไปด้วย cursor=<pagination.nextCursor> จนกว่า hasMore เป็น false · cursor เป็นค่าทึบ อย่าแก้หรือประกอบเอง

async function all(path) {
  const out = [];
  let cursor = '';
  do {
    const url = new URL('https://homehqth.com/api/v1' + path);
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.HOMEHQ_API_KEY}` } });
    const body = await res.json();
    if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
    out.push(...body.data);
    cursor = body.pagination.nextCursor ?? '';
  } while (cursor);
  return out;
}

ข้อผิดพลาด

ทุกข้อผิดพลาดใช้รูปแบบเดียวกัน ข้อความเป็นภาษาอังกฤษ ให้ตัดสินจาก error.code (คงที่) ไม่ใช่ข้อความ และแนบ requestId เมื่อติดต่อทีมงาน

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key lacks the \"payroll:read\" scope",
    "requiredScope": "payroll:read"
  },
  "requestId": "6c1b…"
}

จำกัดความถี่

120 คำขอต่อนาทีต่อ API key · ทุกคำตอบมีหัว X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset (unix วินาที) · เกินแล้วได้ 429 พร้อม Retry-After · ซิงก์ข้อมูลทั้งหมดวันละครั้ง + ใช้ webhook รับการเปลี่ยนแปลงระหว่างวัน จะไม่ชนเพดาน

Webhooks Business+

เพิ่มปลายทางที่ ตั้งค่า → API และการเชื่อมต่อ → Webhooks ใส่ URL (https เท่านั้น) เลือกเหตุการณ์ แล้วคัดลอก signing secret (whsec_… แสดงครั้งเดียว — หมุนใหม่ได้ทุกเมื่อ) · กด ส่งเหตุการณ์ทดสอบ เพื่อดูว่าระบบของคุณรับได้ และดูประวัติการส่ง (สถานะ HTTP เวลาที่ใช้ ข้อผิดพลาดล่าสุด) ได้ทันที

HomeHQ ส่ง POST แบบ JSON พร้อมหัวต่อไปนี้:

{
  "id": "evt_8mQ2vX…",
  "type": "leave.approved",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-11T03:15:20.000Z",
  "orgId": "o-…",
  "data": {
    "leave": {
      "id": "l-…",
      "memberId": "m-…",
      "type": "vacation",
      "startDate": "2026-10-20",
      "endDate": "2026-10-21",
      "portion": "full",
      "days": 2,
      "status": "approved",
      "approverId": "m-…",
      "decidedAt": "2026-10-11T03:15:19.000Z",
      "createdAt": "2026-10-10T09:00:00.000Z"
    },
    "member": {
      "id": "m-…",
      "name": "สมชาย ใจดี",
      "employeeCode": "EMP-0012",
      "email": "somchai@acme.co.th"
    }
  }
}

เหตุการณ์

member ในเหตุการณ์ member.* มีรูปแบบเดียวกับ GET /members/{id} · ในเหตุการณ์อื่นเป็นข้อมูลย่อ { id, name, employeeCode, email } · member.joined เกิดเมื่อมีรายชื่อใหม่ในองค์กร (ผู้ดูแลเพิ่ม, SCIM, หรือพนักงานเข้าร่วมด้วยรหัสเชิญ) · ปุ่มทดสอบส่งเหตุการณ์ webhook.test

ตรวจลายเซ็น (สำคัญ)

ลายเซ็น = HMAC-SHA256 ของข้อความ <t>.<body ดิบ> ด้วย signing secret แล้วเข้ารหัสเป็น hex · ต้องคิดจาก body ดิบก่อนแปลง JSON · ปฏิเสธลายเซ็นที่ t ห่างจากเวลาปัจจุบันเกิน 5 นาที (กันการส่งซ้ำ) · เทียบแบบเวลาคงที่

// Node.js + Express
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.HOMEHQ_WEBHOOK_SECRET; // whsec_...
const seen = new Set(); // ใช้ฐานข้อมูลจริงในระบบของคุณ

app.post('/homehq/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-HomeHQ-Signature') || '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex');
  const given = Buffer.from(parts.v1 || '', 'hex');
  const ok = given.length === 32 && crypto.timingSafeEqual(given, Buffer.from(expected, 'hex'))
    && Math.abs(Date.now() / 1000 - t) < 300;
  if (!ok) return res.status(400).send('bad signature');

  const event = JSON.parse(req.body);
  if (seen.has(event.id)) return res.sendStatus(200); // ส่งซ้ำ — ทำไปแล้ว
  seen.add(event.id);
  queue.push(event); // ประมวลผลทีหลัง
  res.sendStatus(200);
});

<?php // PHP
$secret = getenv("HOMEHQ_WEBHOOK_SECRET");
$body = file_get_contents("php://input");
parse_str(str_replace(",", "&", $_SERVER["HTTP_X_HOMEHQ_SIGNATURE"] ?? ""), $sig);
$expected = hash_hmac("sha256", $sig["t"] . "." . $body, $secret);
if (!hash_equals($expected, $sig["v1"] ?? "") || abs(time() - (int)$sig["t"]) > 300) {
  http_response_code(400); exit;
}
$event = json_decode($body, true);

หมุน secret ใหม่แล้ว secret เดิมใช้ไม่ได้ทันที — อัปเดตค่าในระบบของคุณก่อนกดหมุน หรือรับได้ทั้งสองค่าช่วงสั้น ๆ

การส่งซ้ำและการปิดอัตโนมัติ

ไม่ได้ 2xx (รวมหมดเวลา/ต่อไม่ได้) → ส่งซ้ำหลัง 1 นาที, 5 นาที, 30 นาที และ 2 ชั่วโมง (รวม 5 ครั้ง) ด้วย event id เดิม · ล้มเหลวครบทุกครั้งติดกัน 10 เหตุการณ์ → ปิดปลายทางอัตโนมัติและแจ้งผู้ดูแลในแอป แก้ระบบแล้วเปิดใหม่ได้ และกด ส่งอีกครั้ง ในประวัติการส่งได้ · เก็บประวัติการส่ง 30 วัน · ลำดับการมาถึงไม่รับประกัน ให้ใช้ createdAt เรียงเอง

SCIM 2.0 Enterprise

ให้ IdP ขององค์กรสร้างพนักงานใหม่ อัปเดตข้อมูล และระงับคนที่ออกจากบริษัทใน HomeHQ อัตโนมัติ · สร้าง token ที่ ตั้งค่า → API และการเชื่อมต่อ → SCIM (เฉพาะเจ้าของระบบ · ขึ้นต้นด้วย hhqscim_ แสดงครั้งเดียว องค์กรละ 1 token — สร้างใหม่แล้ว token เดิมใช้ไม่ได้ทันที)

Microsoft Entra ID (Azure AD)

1. Entra admin center → Enterprise applications → New application → Create your own application → ตั้งชื่อ "HomeHQ" เลือก Integrate any other application you don't find in the gallery (Non-gallery)
2. เมนู Provisioning → Get started → Provisioning Mode = Automatic
3. Tenant URL = https://homehqth.com/scim/v2 · Secret Token = SCIM token จาก HomeHQ → กด Test Connection แล้ว Save
4. Mappings: ตรวจว่า userPrincipalName หรือ mail → userName (แนะนำอีเมลจริงที่พนักงานใช้ · ถ้าเป็นรหัสพนักงาน ให้ map mail → emails[type eq "work"].value ด้วย), Switch([IsSoftDeleted]…) → active, department → …:department, jobTitle → title — ลบ mapping ที่ไม่ใช้ได้
5. Users and groups → เพิ่มคน/กลุ่มที่จะใช้ HomeHQ → กลับไปที่ Provisioning ตั้ง Provisioning Status = On (Entra ซิงก์ทุก ~40 นาที หรือกด Provision on demand เพื่อทดสอบทีละคน)

Okta

1. Okta Admin → Applications → Create App Integration → SWA หรือ SAML 2.0 (ใช้เฉพาะเพื่อ provisioning ก็ได้) → แท็บ General → App Settings → Provisioning = SCIM
2. แท็บ Provisioning → Integration: SCIM connector base URL = https://homehqth.com/scim/v2 · Unique identifier field = userName · เลือก Push New Users, Push Profile Updates, Push Groups · Authentication Mode = HTTP Header แล้ววาง token → Test Connector Configuration
3. To App → เปิด Create Users, Update User Attributes, Deactivate Users
4. แท็บ Assignments เพิ่มคน/กลุ่ม · แท็บ Push Groups เพื่อสร้างแผนกจากกลุ่ม Okta

Google Workspace