Getting Started

เริ่มต้นใช้งาน Humansoft Open API อย่างรวดเร็วด้วยคู่มือนี้

Prerequisites

ก่อนเริ่มใช้งาน Humansoft API โปรดตรวจสอบว่าคุณมี:

บัญชี Humansoft ที่ใช้งานอยู่
API Key สำหรับ API
ความเข้าใจพื้นฐานเกี่ยวกับ RESTful APIs
Development environment (Node.js, Python, PHP หรือภาษาที่คุณต้องการ)

สำคัญ: เก็บรักษา API Key ของคุณให้ปลอดภัย อย่า commit ลงใน version control หรือเปิดเผยในโค้ดฝั่ง client

API Environments

Humansoft API มี 2 environments:

Environment	Base URL	Description
Production	`https://openapi.humansoft.co.th`	สำหรับใช้งานจริง (Production)
UAT	`https://openapi.humansoft.co.th/uat`	สำหรับทดสอบ (User Acceptance Testing)

แนะนำให้ทดสอบกับ UAT environment ก่อนใช้งานจริงบน Production

Quick Start

Get Your API Key

เข้าสู่ระบบ Humansoft และขอ API Key จาก:

HMS Settings - Open API Connection

ระบบจะให้ Key 2 ตัว:

Key Type	Description
Primary Key	Key หลักสำหรับใช้งาน
Secondary Key	Key สำรองสำหรับใช้งาน

เลือกใช้ Key ใดก็ได้ - Primary Key และ Secondary Key ทำงานเหมือนกัน สามารถเลือกใช้อย่างใดอย่างหนึ่งเป็น API Key ได้

แนะนำ: ใช้ Secondary Key สำหรับ rotate key โดยไม่ต้องหยุดระบบ เมื่อต้องการเปลี่ยน Primary Key

API Key ของคุณจะมีรูปแบบคล้ายกับ:


abc123def456ghi789jkl012mno345pqr678

Key นี้เป็นข้อมูลสำคัญ โปรดเก็บรักษาไว้เป็นความลับ

Make Your First API Request

ทดสอบการเชื่อมต่อด้วย API call แรกของคุณ:

หมายเหตุ: API Key ที่ใช้ต้องมีสิทธิ์ กลุ่มข้อมูลองค์กร (org:manage) จึงจะเรียกใช้ API นี้ได้

cURL


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

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/organization/get-list-organization',
  {
    method: 'GET',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
)
const data = await response.json()
console.log(data)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/organization/get-list-organization"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
 
response = requests.get(url, headers=headers)
data = response.json()
print(data)

PHP


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

Handle the Response

การตอบกลับที่สำเร็จจะส่งข้อมูลในรูปแบบ JSON:


{
  "code": 200,
  "message": "สำเร็จ",
  "payload": [
    {
      "id": "20251113320BC9F85E44",
      "code": "C001",
      "name": "บริษัท ABC จำกัด",
      "name_th": "บริษัท ABC จำกัด",
      "name_en": "ABC Company Limited",
      "level_name": "บริษัท",
      "level_name_en": "Company",
      "children": [...]
    }
  ]
}

ดูรายละเอียด Response แบบเต็มได้ที่ Get Organization Structure

Explore More Endpoints

ตอนนี้คุณได้ทดสอบ API แล้ว ลองสำรวจ endpoints อื่นๆ:

Organization APIs - ข้อมูล Master Data องค์กร
Time Leave APIs - จัดการการลา
Overtime APIs - จัดการ OT
Time Attendance APIs - บันทึกเวลา

Authentication

Required Header

API ทุกตัวต้องการ authentication ผ่าน header:

Key	Value	Description
`Ocp-Apim-Subscription-Key`	`YOUR_API_KEY`	Key สำหรับยืนยันตัวตน

Example


GET /api/v1/open-apis/organization/get-list-organization HTTP/1.1
Host: openapi.humansoft.co.th
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json

Error 401 Unauthorized: ถ้าคุณได้รับ error นี้ แสดงว่า API Key ไม่ถูกต้อง หรือหมดอายุ โปรดตรวจสอบ key ของคุณที่ HMS Settings

Response Format

Success Response


{
  "code": 200,
  "message": "สำเร็จ",
  "payload": { /* ข้อมูล */ }
}

Error Response


{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "error": "Error description"
}

หรือ


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "Missing required parameter: 'employee_name'",
    "'effective_dt' must be in YYYY-MM-DD format"
  ]
}

Common HTTP Status Codes

Status Code	Description
`200`	Success - Request สำเร็จ
`400`	Bad Request - Request ไม่ถูกต้อง หรือ validation ไม่ผ่าน
`401`	Unauthorized - API Key ไม่ถูกต้อง
`404`	Not Found - Endpoint ไม่พบ
`500`	Internal Server Error - เกิดข้อผิดพลาดในระบบ

Best Practices

1. Security

เก็บ API Key ในที่ปลอดภัย (ใช้ environment variables)
อย่า commit key ลง Git repository
อย่าเปิดเผย key ใน client-side code
ใช้ HTTPS เสมอ (API รองรับเฉพาะ HTTPS)

2. Error Handling


try {
  const response = await fetch(url, {
    headers: {
      'Ocp-Apim-Subscription-Key': process.env.HUMANSOFT_API_KEY
    }
  })
 
  const data = await response.json()
 
  if (data.code !== 200) {
    console.error('API Error:', data.message, data.errors)
    // Handle error
  }
 
  return data.payload
} catch (error) {
  console.error('Network Error:', error)
  // Handle network error
}

3. Caching

ควรใช้ Cache สำหรับ Master Data ที่ไม่ค่อยเปลี่ยนแปลง:

Organization structure
Bank list
Employee types/status
Position list


// Example: Cache master data for 1 hour
const CACHE_DURATION = 3600000 // 1 hour in ms
const cache = new Map()
 
async function getCachedData(key, fetchFn) {
  const cached = cache.get(key)
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.data
  }
 
  const data = await fetchFn()
  cache.set(key, { data, timestamp: Date.now() })
  return data
}

Support & Resources

Get Help

ต้องการความช่วยเหลือ? ติดต่อเราได้ที่:

📧 Email: support@humansoft.co.th
🌐 Website: https://www.humansoft.co.th/
📱 HMS Settings: https://hms.humansoft.me/setting/setting-connection-open-api

Documentation

API Reference - เอกสาร API ทั้งหมด
Organization APIs - Master Data APIs
Time Leave APIs - จัดการการลา
Overtime APIs - จัดการ OT

Next Steps

คุณพร้อมแล้ว! ต่อไปนี้คือสิ่งที่ควรทำ:

✅ สำรวจ Organization APIs - เริ่มต้นด้วย Master Data
📖 อ่านเอกสาร API ที่คุณสนใจ
🧪 ทดสอบบน UAT environment ก่อน
🚀 Deploy ไปยัง Production เมื่อพร้อม
📊 Monitor API usage และ performance