คู่มือเริ่มต้นใช้งานสำหรับนักพัฒนา

นี่คือขั้นตอนการเชื่อมต่อ API ซาจูของ HRUM เป็นครั้งแรก ตั้งแต่สมัคร เรียกครั้งแรก การคิดค่าบริการ ไปจนถึงการจัดการข้อผิดพลาด ทำตามหน้านี้หน้าเดียวก็พอ พารามิเตอร์ทั้งหมดของแต่ละเอนด์พอยต์อยู่ในเอกสาร API

หากอยากเห็นผลลัพธ์ก่อนสมัคร ทดลองได้ฟรีที่ Playground โดยไม่ต้องใช้คีย์ สูงสุดเดือนละ 5 ครั้ง

ให้ AI สร้างแอปให้ — อีบุ๊กฟรี (ภาษาเกาหลี)

เลือกอีบุ๊ก (ภาษาเกาหลี)แอปดูดวงแบบรวม (ภาษาเกาหลี)แอปแชตตัวละคร (ภาษาเกาหลี)เว็บแอประบบสมาชิก (ภาษาเกาหลี)

1. สมัครคอนโซล

  1. ที่หน้าเข้าสู่ระบบคอนโซล เลือกแท็บ สมัครสมาชิก แล้วกรอกอีเมลและรหัสผ่าน
  2. กดปุ่มยืนยันในอีเมล "ยืนยันอีเมล" ในกล่องจดหมาย แล้วเข้าสู่ระบบอีกครั้ง
  3. เมื่อสมัครจะได้รับเครดิตฟรี ₩1,000 (หากเข้าเงื่อนไขป้องกันการสมัครโดยมิชอบ การให้เครดิตอาจถูกระงับไว้)

2. ออกคีย์ API

  1. ที่หน้าคีย์ APIในคอนโซล ใส่ชื่อคีย์ (เช่น เซิร์ฟเวอร์โปรดักชัน) แล้วกด ออกคีย์
  2. คีย์ใหม่จะแสดงเพียงครั้งเดียวทันทีหลังออก คัดลอกทันทีและเก็บไว้ในที่ปลอดภัย เช่น ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ หากทำหายให้ออกคีย์ใหม่
  3. ใช้คีย์บนเซิร์ฟเวอร์เท่านั้น หากใส่ในโค้ดเบราว์เซอร์หรือแอป ใครก็ดึงไปใช้ได้

หากตั้งจำนวนคำขอต่อวินาที·ต่อวันไว้ใน การจำกัดคำขอ ในหน้าเดียวกัน ก็จะปกป้องยอดคงเหลือได้แม้คีย์รั่วไหลหรือโค้ดวนซ้ำไม่สิ้นสุด

3. เรียกครั้งแรก — ปฏิทินหมื่นปี

ทุกคำขอส่งไปยังพาธภายใต้ https://api.hrum.ai/api/v1/partners/v1/ โดยใส่คีย์ไว้ในเฮดเดอร์ X-Partner-Api-Key ด้านล่างคือการเรียกปฏิทินหมื่นปีที่คำนวณผังดวงซาจูจากวันเดือนปีและเวลาเกิด

curl

export HRUM_API_KEY="your-api-key"

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":1990,"month":5,"day":15,"hour":12,"minute":0,"timezone":"Asia/Seoul","gender":"male"}'

Python (requests)

import os
import requests

res = requests.post(
    "https://api.hrum.ai/api/v1/partners/v1/manseryeok",
    headers={"X-Partner-Api-Key": os.environ["HRUM_API_KEY"]},
    json={"year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
          "timezone": "Asia/Seoul", "gender": "male"},
    timeout=30,
)
body = res.json()
if not body.get("success"):
    raise RuntimeError(f'{body.get("statusCode")} {body.get("code")}')
print(body["data"]["wonkuk"]["day"])

User-Agent เริ่มต้นของ urllib ในไลบรารีมาตรฐานของ Python จะติดกฎความปลอดภัยและได้ 403 กลับมา ให้ใช้ requests หรือหากใช้ urllib ให้ใส่เฮดเดอร์ User-Agent: <ชื่อแอป>/<เวอร์ชัน> เอง

JavaScript (Node 18 ขึ้นไป บนเซิร์ฟเวอร์)

const res = await fetch('https://api.hrum.ai/api/v1/partners/v1/manseryeok', {
  method: 'POST',
  headers: {
    'X-Partner-Api-Key': process.env.HRUM_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ year: 1990, month: 5, day: 15, hour: 12, minute: 0, timezone: 'Asia/Seoul', gender: 'male' }),
});
const body = await res.json();
if (!body.success) throw new Error(`${body.statusCode} ${body.code ?? ''}`);
console.log(body.data.wonkuk.day);

4. อ่านการตอบกลับ

เมื่อสำเร็จจะได้รูปแบบ {"success": true, "data": { … }} กลับมา สำหรับปฏิทินหมื่นปี ใน data จะมีผังดวง 4 เสา (wonkuk) การกระจายธาตุทั้งห้า (ohaengBalance) ธาตุช่วย (yongshin) รูปแบบดวง วัยจร 10 ปี·ดวงรายปี ฯลฯ รายการฟิลด์ทั้งหมดดูได้ที่เอกสาร API ปฏิทินหมื่นปี

API แบบคำนวณที่ข้อมูลนำเข้าเหมือนกันได้ผลลัพธ์เหมือนกันอย่างปฏิทินหมื่นปี หากบันทึกผลที่ได้รับครั้งแรกไว้ใน DB แล้วใช้ซ้ำ ก็จะไม่มีค่าใช้จ่าย

5. การคิดค่าบริการและเครดิต

ราคาต่อหน่วยของแต่ละสินค้าอยู่ในตารางราคา ราคาสินค้าแบบคำนวณหลัก (ตามตารางราคาปัจจุบัน):

6. การจัดการข้อผิดพลาด

เนื้อหาการตอบกลับข้อผิดพลาดอยู่ในรูปแบบ {"success": false, "statusCode": 400, "code": "…", "message": "…", "timestamp": "…"} ให้แยกกรณีด้วย statusCode และ code และอย่าพึ่งพาข้อความใน message

รหัสความหมายวิธีจัดการ
400พารามิเตอร์คำขอไม่ถูกต้องแก้คำขอ อย่าลองส่งคำขอเดิมซ้ำ
401ไม่มีคีย์ API หรือคีย์ไม่ถูกต้องตรวจชื่อเฮดเดอร์ (X-Partner-Api-Key) และค่าคีย์
402ยอดเครดิตไม่พอ code เป็น INSUFFICIENT_BALANCE หรือไม่มีเลยใน API ที่ไม่มีการตรวจยอดคงเหลือก่อนเรียก (เช่น ปฏิทินหมื่นปี)เติมเงินแล้วเรียกใหม่
403ถูกกฎความปลอดภัยบล็อก (เนื้อหาเป็น HTML ไม่ใช่ JSON, error 1010) — ไคลเอนต์ HTTP ที่ User-Agent เริ่มต้นถูกบล็อก (เช่น Python urllib) ไม่ใช่ปัญหาของคีย์ APIใส่เฮดเดอร์ User-Agent: <ชื่อแอป>/<เวอร์ชัน> การเปลี่ยนคีย์ไม่ช่วยแก้ปัญหา
404ฟีเจอร์ที่ยังไม่เปิดให้บัญชี (*_not_enabled) หรือทรัพยากรที่ไม่มีอยู่ไม่คิดค่าบริการ ตรวจพาธและสถานะการเปิดใช้ฟีเจอร์
422ข้อมูลนำเข้าที่ประมวลผลไม่ได้ (เช่น PROMPT_TOO_LONG)ลดหรือแก้ข้อมูลนำเข้า
429เกินขีดจำกัดคำขอหากมีเฮดเดอร์ Retry-After ให้รอตามนั้น หากไม่มีให้รอสักครู่ (สูงสุด 1 นาที) แล้วลองใหม่
500 · 503 · 504ข้อผิดพลาดของเซิร์ฟเวอร์ · ใช้งานไม่ได้ชั่วคราว · บริการต้นทางหมดเวลาลองใหม่เพียงไม่กี่ครั้งโดยเพิ่มช่วงห่างขึ้นเรื่อยๆ (เช่น 1 วินาที → 2 วินาที → 4 วินาที)

เพื่อปกป้องบริการ มีเพดาน 300 ครั้งต่อนาทีต่อคีย์ API เสมอ รายละเอียดดูได้ในเอกสาร รหัสข้อผิดพลาด และ Rate Limit สถานะเหตุขัดข้องตรวจสอบได้ที่หน้าสถานะ

ขั้นตอนถัดไป

ติดต่อ: contact@float.do · ดำเนินการโดย: FLOAT Co., Ltd.