Get Location List

ดึงรายการสถานที่บันทึกเวลา (Location) ที่ลงทะเบียนในระบบ รองรับการกรองตามสถานะเผยแพร่ หน่วยงาน สิทธิ์การลงเวลาของพนักงาน การค้นหา และการแบ่งหน้า

ใช้ API นี้เพื่อค้นหา location_id ที่ต้องใช้ประกอบกับ Submit Time Attendance สำหรับการบันทึกเวลาประเภท Checkin, QR และ Facial

Endpoint นี้ไม่ต้องการสิทธิ์ (scope) พิเศษ — เรียกใช้ได้ด้วย API Key ที่ถูกต้องของระบบ

Endpoint


GET /api/v1/open-apis/locations/get-list

รองรับทั้ง GET (ส่งพารามิเตอร์เป็น Query String) และ POST (ส่งเป็น JSON Body) — โครงสร้างพารามิเตอร์เหมือนกัน

Request Parameters

พารามิเตอร์ทั้งหมดเป็น optional — เรียกโดยไม่ส่งพารามิเตอร์จะได้รายการสถานที่ทั้งหมด

Parameter	Type	Required	Description
`publish_flag`	string	No	กรองตามสถานะเผยแพร่ — `Y` หรือ `N`
`sort_by`	string	No	เรียงลำดับผลลัพธ์ — `order_no` (default), `location_name`, `location_id`, `location_group_code`, `created`
`sort_order`	string	No	ทิศทางการเรียง — `ASC` (default) หรือ `DESC`
`search`	string	No	ค้นหาแบบ substring (ไม่แยกตัวพิมพ์เล็ก/ใหญ่) จาก `location_name` หรือ `location_group_code` — ยาวไม่เกิน 100 ตัวอักษร
`location_group_code`	string	No	กรองตามรหัสกลุ่มสถานที่
`location_id`	string	No	กรองตาม ID สถานที่ (raw ID เช่น `"20260212D9F611580550"`)
`employee_code`	string	No	รหัสพนักงาน (เช่น `"EMP001"`) — คืนเฉพาะสถานที่ที่พนักงานคนนั้นมีสิทธิ์ลงเวลา (ดู Callout ด้านล่าง)
`company_code`	string	No	รหัสบริษัท (เช่น `"COMP-01"`)
`branch_code`	string	No	รหัสสาขา (เช่น `"BR-01"`)
`department_code`	string	No	รหัสแผนก (เช่น `"DEPT-IT"`)
`division_code`	string	No	รหัสฝ่าย (เช่น `"DIV-DEV"`)
`section_code`	string	No	รหัสกอง (เช่น `"SEC-WEB"`)
`position_code`	string	No	รหัสตำแหน่งงาน (เช่น `"POS-DEV"`)
`_PAGE`	number	No	เลขหน้าที่ต้องการ (เริ่มที่ 1)
`_NUMBER_PER_PAGE`	number	No	จำนวนรายการต่อหน้า (1–100, default `20` เมื่อเปิดการแบ่งหน้า)

ทุกพารามิเตอร์ *_code สามารถส่งเป็น internal ID แทนได้ (employee_id, company_id, branch_id, department_id, division_id, section_id, position_id) โดยใช้ค่า raw (ไม่ใช่ Base64) หากส่งทั้ง *_code และ *_id มาพร้อมกัน ระบบจะใช้ค่าจาก *_code เป็นหลัก

พฤติกรรมของ employee_code / employee_id

คืนเฉพาะสถานที่ที่พนักงานมีสิทธิ์ลงเวลา โดยไล่สิทธิ์แบบ cascade ตามลำดับ บริษัท → สาขา → แผนก → ฝ่าย → กอง → ตำแหน่ง → รายบุคคล
คืนเฉพาะสถานที่ที่ใช้งานได้ ณ วันที่เรียก API (สถานที่ที่ปิดในวันนั้น เช่นเปิดเฉพาะ จ.–ศ. เมื่อเรียกวันเสาร์ จะไม่แสดง)
คืนเฉพาะสถานที่ที่ publish_flag = Y — การส่ง publish_flag=N ร่วมกับ employee_code จะได้ payload ว่าง
ค้นเฉพาะพนักงานที่ยังทำงานอยู่ (active) — หากเป็นรหัสของพนักงานที่ลาออกแล้วหรือไม่มีอยู่จริง จะได้ HTTP 400 (not found)

การกรองด้วยหน่วยงาน (company_*, branch_*, department_*, division_*, section_*, position_*) เป็นการเทียบแบบตรงตัว (exact match) กับสิทธิ์ใน child[] ของแต่ละสถานที่ ไม่ไล่ลำดับชั้นให้ — สถานที่ที่ผูกสิทธิ์กว้างกว่า (เช่นสิทธิ์ระดับบริษัททั้งหมด) จะไม่ถูกคืนเมื่อกรองด้วย department_code หากต้องการสิทธิ์ที่แท้จริงของพนักงานรายบุคคลให้ใช้ employee_code

Response Format

Success Response (HTTP 200)


{
  "code": "200",
  "message": "Success",
  "payload": [
    {
      "location_id": "20260212D9F611580550",
      "location_group_code": "LOC001",
      "location_name": "อาคาร A",
      "location_latitude": "13.7563",
      "location_longitude": "100.5018",
      "location_radius": 100,
      "location_start": null,
      "location_end": null,
      "location_qrpath": "",
      "Mon": 1,
      "Tue": 1,
      "Wed": 1,
      "Thu": 1,
      "Fri": 1,
      "Sat": 0,
      "Sun": 0,
      "publish_flag": "Y",
      "created": "2026-02-10 09:00:00",
      "order_no": 1,
      "child": [
        {
          "location_id": "20260212D9F611580551",
          "company_id": "1",
          "branch_id": "0",
          "department_id": "10",
          "division_id": "0",
          "section_id": "0",
          "section_lv01_id": "0",
          "section_lv02_id": "0",
          "section_lv03_id": "0",
          "section_lv04_id": "0",
          "section_lv05_id": "0",
          "position_id": "0",
          "employee_id": "0",
          "global_flag": "N",
          "auth_name": "บริษัท เอชเอ็มเอส จำกัด => ฝ่ายเทคโนโลยีสารสนเทศ"
        }
      ]
    }
  ],
  "_PAGINATION": {
    "_TOTAL_RECORDS": 45,
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 20
  }
}

_PAGINATION จะอยู่ใน response เสมอ — หากไม่ระบุ ทั้ง _PAGE และ _NUMBER_PER_PAGE ระบบจะคืนรายการทั้งหมดใน payload โดย _PAGINATION._NUMBER_PER_PAGE เท่ากับจำนวนรายการทั้งหมด หากระบุมาอย่างน้อยหนึ่งตัว ระบบจะแบ่งหน้าและเติมค่า default ให้ตัวที่ขาด (response ไม่มีฟิลด์จำนวนหน้าทั้งหมด — คำนวณเองได้จาก ceil(_TOTAL_RECORDS / _NUMBER_PER_PAGE))

Error Response - Validation Failed (HTTP 400)


{
  "code": "400",
  "message": "Failed",
  "errors": [
    "'publish_flag' must be one of: Y, N"
  ]
}

Error Response - Not Found (HTTP 400)

เมื่อส่ง *_code / *_id (เช่น employee_code, department_code) ที่ไม่มีอยู่จริง ระบบจะตอบกลับทันทีเพื่อไม่ให้สิทธิ์สถานที่หลุดคืนทั้งองค์กร (fail-closed):


{
  "code": "400",
  "message": "Failed",
  "errors": [
    "'employee_code' not found: EMP999"
  ]
}

Response Fields

ระดับสถานที่ (payload[])

Field	Type	Description
`location_id`	string	รหัสสถานที่ (แถวแรกของกลุ่มเมื่อเรียงตาม `order_no`)
`location_group_code`	string	รหัสกลุ่มสถานที่
`location_name`	string	ชื่อสถานที่
`location_latitude`	string	ละติจูด
`location_longitude`	string	ลองจิจูด
`location_radius`	number	รัศมีที่อนุญาตให้บันทึกเวลา (เมตร)
`location_start`	string \| null	เวลาเริ่มต้นที่เปิดให้บันทึก
`location_end`	string \| null	เวลาสิ้นสุดที่เปิดให้บันทึก
`location_qrpath`	string	Path ของ QR Code สำหรับ Time Attendance App
`Mon` … `Sun`	number	วันที่เปิดใช้งาน (`1` = เปิด, `0` = ปิด)
`publish_flag`	string	สถานะการเผยแพร่ (`Y` / `N`)
`created`	string \| null	วันเวลาที่ลงทะเบียนสถานที่ (`YYYY-MM-DD HH:mm:ss`)
`order_no`	number	ลำดับการแสดงผลที่ตั้งไว้ในระบบ (เป็นลำดับ default ของ `payload`)
`child`	array	รายการการกำหนดสิทธิ์ของสถานที่ (Permission Scope Items)

รายการสิทธิ์ (payload[].child[])

Field	Type	Description
`location_id`	string	ID ของแถวสิทธิ์นั้นๆ (ต่างจาก `location_id` ระดับกลุ่ม ยกเว้นแถวแรก)
`company_id`	string	ID บริษัท (`0` = ทั้งหมด/ไม่ระบุ)
`branch_id`	string	ID สาขา (`0` = ทั้งหมด/ไม่ระบุ)
`department_id`	string	ID แผนก (`0` = ทั้งหมด/ไม่ระบุ)
`division_id`	string	ID ฝ่าย (`0` = ทั้งหมด/ไม่ระบุ)
`section_id`	string	ID กอง (`0` = ทั้งหมด/ไม่ระบุ)
`section_lv01_id` … `section_lv05_id`	string	ID แผนกย่อยระดับ 1–5 (`0` = ทั้งหมด/ไม่ระบุ)
`position_id`	string	ID ตำแหน่งงาน (`0` = ทั้งหมด/ไม่ระบุ)
`employee_id`	string	ID พนักงานรายบุคคล (`0` = ทั้งหมด/ไม่ระบุ)
`global_flag`	string	สิทธิ์แบบทั่วไป (`Y` / `N`)
`auth_name`	string	ชื่อสิทธิ์องค์กรตามลำดับ (เช่น `บริษัท => ฝ่าย => แผนก`)

ค่า ID ทั้งหมดใน response เป็น raw (ไม่ใช่ Base64) — นำ location_id ไปใช้กับ Submit Time Attendance ได้โดยตรง

การแบ่งหน้า (_PAGINATION)

Field	Type	Description
`_PAGINATION._TOTAL_RECORDS`	number	จำนวนรายการทั้งหมดที่เข้าเงื่อนไข
`_PAGINATION._PAGE`	number	เลขหน้าปัจจุบัน
`_PAGINATION._NUMBER_PER_PAGE`	number	จำนวนรายการต่อหน้า (เท่ากับจำนวนรายการทั้งหมดเมื่อไม่ได้เปิดการแบ่งหน้า)

Code Examples

cURL


curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list',
  {
    headers: { 'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY' }
  }
)
const data = await response.json()
const locations = data.payload

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list"
headers = {"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"}
 
response = requests.get(url, headers=headers)
locations = response.json()["payload"]

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list";
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
$data = json_decode($response, true);
$locations = $data['payload'];
curl_close($ch);
?>

สถานการณ์อื่นๆ


# สถานที่ที่พนักงานคนหนึ่งมีสิทธิ์ลงเวลา
curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list?employee_code=EMP001" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
 
# ค้นหาตามชื่อ พร้อมแบ่งหน้า
curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list?search=อาคาร&_PAGE=1&_NUMBER_PER_PAGE=10" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
 
# กรองผ่าน POST body
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/locations/get-list" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department_code": "DEPT-IT", "publish_flag": "Y", "_PAGE": 1, "_NUMBER_PER_PAGE": 20 }'

Validation Rules

Parameter	Validation	Error Message
`publish_flag`	`Y` หรือ `N`	`'publish_flag' must be one of: Y, N`
`sort_by`	หนึ่งในค่าที่รองรับ	`'sort_by' must be one of: location_name, location_id, location_group_code, created, order_no`
`sort_order`	`ASC` หรือ `DESC` (ไม่แยกตัวพิมพ์เล็ก/ใหญ่)	`'sort_order' must be either 'ASC' or 'DESC'`
`_PAGE`	ตัวเลข ≥ 1	`'_PAGE' must be a positive number`
`_NUMBER_PER_PAGE`	ตัวเลข 1–100	`'_NUMBER_PER_PAGE' must be a number between 1 and 100`
`search`	ยาวไม่เกิน 100 ตัวอักษร และห้ามมี `' " \ ;`	`'search' parameter must not exceed 100 characters`
`*_code`	ห้ามมีอักขระ `' " \ ;`	`'company_code' contains unsafe characters`
`*_id`	อักษรอังกฤษ ตัวเลข `.` `_` `-` เท่านั้น (`/^[A-Za-z0-9._-]+$/`)	`'location_id' contains invalid characters`

Notes

ค่าเริ่มต้นเรียงตาม order_no (น้อย → มาก) และตัดสินด้วย location_id เมื่อค่าเท่ากัน ทำให้ลำดับคงที่ทุกครั้ง (จำเป็นต่อความถูกต้องของการแบ่งหน้า)
sort_by=location_name เรียงตามลำดับพจนานุกรมไทย
หาก _PAGE เกินจำนวนหน้าที่มีอยู่จริง จะได้ HTTP 200 พร้อม payload ว่าง โดย _PAGINATION._TOTAL_RECORDS ยังคืนค่าจริง
รายการใน payload ถูกจัดกลุ่มตาม location_group_code โดยสิทธิ์ย่อยขององค์กรถูกรวมไว้ใน child[] — ค่าระดับสถานที่ (ชื่อ, พิกัด, Mon–Sun, publish_flag) มาจากแถวแรกของกลุ่ม
ฟิลด์ location_start, location_end, created อาจเป็น null ถ้ายังไม่ได้กำหนดค่า

Submit Time Attendance - บันทึกเวลาโดยอ้างอิง location_id ที่ได้จาก API นี้
Get Device List - อุปกรณ์บันทึกเวลาที่ผูกกับสถานที่