คู่มือ API (Sender Token)

ภาพรวม

ใช้ Sender Token เพื่อส่งการแจ้งเตือนผ่าน API ของระบบหลังบ้าน (ควรใช้ฝั่งเซิร์ฟเวอร์เท่านั้น และเก็บโทเค็นนี้เป็นความลับ)

Endpoint

POST https://notipush.app/api/send-push

รายละเอียด Payload

Key	ความหมาย
sender_token String (Required)	Sender Token ที่ได้จากแอป (เก็บเป็นความลับ)
title String (Required)	หัวข้อของการแจ้งเตือน
body String (Required)	เนื้อหาของการแจ้งเตือน
target_ids Array (Optional)	ระบุ ID ผู้รับในรูปแบบ array (ใส่ค่าเดียวสำหรับเป้าหมายเดียว หรือหลายค่าสำหรับหลายเป้าหมาย)

ตัวอย่าง

การตอบกลับ

ตัวอย่าง Response

{
  "success": true,
  "results": {
    "successCount": 1,
    "failureCount": 0
  }
}

หากเปิดใช้ Firebase จะได้ค่า successCount/failureCount; หากไม่เปิดใช้งาน อาจได้ simulated=true

การตอบกลับกรณีเกิดข้อผิดพลาด

รหัสสถานะ	ความหมาย	รายละเอียดเพิ่มเติม
`400`	คำขอไม่ถูกต้อง	พารามิเตอร์ไม่ครบถ้วน, id_token ไม่ถูกต้อง, อีเมลหรือจำนวนวันไม่ถูกต้อง
`401`	ไม่มีสิทธิ์	ไม่มี Authorization header, token ไม่ถูกต้อง, session หมดอายุ
`403`	ถูกปฏิเสธ	sender_token ไม่ถูกต้อง, บัญชีหมดอายุ, demo disabled, ไม่มีสิทธิ์ admin
`404`	ไม่พบข้อมูล	ไม่พบผู้ใช้, ไม่พบข้อมูลที่ร้องขอ
`409`	ขัดแย้ง	เคยลงทะเบียน Target ID นี้แล้ว (already_subscribed)
`422`	ข้อมูลไม่สมบูรณ์	พบข้อความซ้ำภายใน 5 วินาที (duplicate_message)
`429`	ส่งคำขอบ่อยเกินไป	เกิน limit ต่อวินาทีของแผน (too_many_requests)
`500`	ข้อผิดพลาดเซิร์ฟเวอร์	ข้อผิดพลาดทั่วไปในระบบ, ฐานข้อมูล, หรือการเชื่อมต่อ

ลิงก์ลงทะเบียน (Registration Link)

คุณสามารถสร้างลิงก์สำหรับให้ผู้รับ (Receiver) สแกนหรือกดเปิดเพื่อเพิ่มช่องรับแจ้งเตือนได้อัตโนมัติ โดยใส่ Notify Token และ Target ID (ถ้าต้องการ) ลงในลิงก์

รูปแบบลิงก์ (Web URL)

ใช้ลิงก์นี้ได้ทั้งบนเว็บ, แอป และ QR Code — จะ redirect ไปเปิดแอป Receiver อัตโนมัติ หรือพาไป App Store/Play Store หากยังไม่ได้ติดตั้ง

https://notipush.app/r/?t=YOUR_NOTIFY_TOKEN

หากต้องการระบุ Target ID ด้วย:

https://notipush.app/r/?t=YOUR_NOTIFY_TOKEN&tg=TARGET_ID

Parameter	ความหมาย
t String (Required)	Notify Token ของคุณ (ค่าสาธารณะ ไม่ใช่ Sender Token)
tg String (Optional)	Target ID สำหรับติดป้ายกำกับอุปกรณ์/กลุ่มของผู้รับ (ระบบของคุณเป็นคนกำหนด)

Notify Token ≠ Sender Token — Notify Token เป็นค่าสาธารณะ ใช้สำหรับลงทะเบียนผู้รับ ส่วน Sender Token ใช้สำหรับส่ง Push เท่านั้น ห้ามเปิดเผย

สร้าง QR Code จากลิงก์

นำลิงก์ที่สร้างด้านบนไปสร้าง QR Code ด้วยเว็บไซต์ หรือ Library ในภาษาโปรแกรมของคุณ ไม่มี endpoint สำหรับสร้าง QR Code บนเซิร์ฟเวอร์ ผู้รับสแกน QR Code แล้วจะเปิดแอป Receiver พร้อมลงทะเบียนอัตโนมัติ

ตัวอย่าง: สร้าง QR Code ด้วย Python

import qrcode

notify_token = "YOUR_NOTIFY_TOKEN"
target_id = "room-101"  # Optional

url = f"https://notipush.app/r/?t={notify_token}&tg={target_id}"
img = qrcode.make(url)
img.save("notipush_qr.png")
print(f"QR Code saved: {url}")

ตัวอย่าง: สร้าง QR Code ด้วย JavaScript (Node.js)

const QRCode = require('qrcode');

const notifyToken = "YOUR_NOTIFY_TOKEN";
const targetId = "room-101"; // Optional

const url = `https://notipush.app/r/?t=${notifyToken}&tg=${targetId}`;
QRCode.toFile('notipush_qr.png', url, (err) => {
  if (err) throw err;
  console.log(`QR Code saved: ${url}`);
});

คุณสามารถสร้าง QR Code แบบ Dynamic ได้ — เช่น พิมพ์ QR คนละใบสำหรับลูกค้าแต่ละราย หรือวางไว้ตามห้องต่างๆ ในอาคาร โดยเปลี่ยน Target ID ให้แตกต่างกัน

การใช้ Target ID (ส่งเจาะจงอุปกรณ์/กลุ่ม)

Target ID คือค่าที่ระบบของคุณ (Sender) เป็นคนกำหนดขึ้นมา ฝังไว้ในลิงก์หรือ QR Code ตอนที่ผู้รับลงทะเบียน เมื่อจำเป็นต้องส่งแจ้งเตือนเจาะจง คุณระบุ target_id ใน API call แล้วเฉพาะอุปกรณ์ที่ลงทะเบียนด้วย ID นั้นเท่านั้นที่จะได้รับ

ขั้นตอนการใช้งาน

Sender กำหนด Target ID

ออกแบบ Target ID ตามโครงสร้างของระบบคุณ เช่น รหัสลูกค้า, ชื่อห้อง, แผนก, สาขา เป็นต้น

สร้าง Link / QR Code พร้อม Target ID

ใส่ Target ID ลงในลิงก์ แล้วสร้าง QR Code หรือส่งลิงก์ให้ผู้รับ

ผู้รับสแกน QR / กดลิงก์

แอป Receiver จะลงทะเบียนพร้อมผูก Target ID ไว้กับอุปกรณ์โดยอัตโนมัติ

ส่ง Push เจาะจงด้วย target_id

เรียก API พร้อมใส่ target_id จะส่งเฉพาะอุปกรณ์ที่ลงทะเบียนด้วย ID นั้น ถ้าไม่ใส่จะส่งหาทุกคน (Broadcast)

ตัวอย่างการใช้งานจริง

สถานการณ์	Target ID	ลิงก์ตัวอย่าง
🏨 แจ้งเตือนเฉพาะห้อง	`room-101`	`.../r/?t=TOKEN&tg=room-101`
👤 แจ้งเตือนลูกค้ารายบุคคล	`cust-5678`	`.../r/?t=TOKEN&tg=cust-5678`
🏢 แจ้งเตือนเฉพาะแผนก	`dept-sales`	`.../r/?t=TOKEN&tg=dept-sales`
🏪 แจ้งเตือนเฉพาะสาขา	`branch-bkk01`	`.../r/?t=TOKEN&tg=branch-bkk01`
📢 ส่งทุกคน (Broadcast)	ไม่ต้องใส่	`.../r/?t=TOKEN`

ตัวอย่าง API: ส่งหาเป้าหมายเดียว

curl -X POST "https://notipush.app/api/send-push" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "title": "ห้อง 101 — อาหารพร้อมเสิร์ฟ",
           "body": "กรุณามารับที่เคาน์เตอร์ชั้น 1",
           "target_ids": ["room-101"]
         }'

ตัวอย่าง API: ส่งหาหลายเป้าหมาย

curl -X POST "https://notipush.app/api/send-push" \
     -H "Content-Type: application/json" \
     -d '{
           "sender_token": "YOUR_SENDER_TOKEN",
           "title": "แจ้งเตือนฉุกเฉิน",
           "body": "กรุณาอพยพออกจากอาคารทันที",
           "target_ids": ["floor-1", "floor-2", "emergency"]
         }'

💡 ไม่ใส่ target_ids = ส่งหาทุกคนที่ติดตามช่องนี้ (Broadcast) | ใส่ target_ids = ส่งหาอุปกรณ์ที่ลงทะเบียนด้วย ID ใดๆ ในรายการ (array มีค่าเดียวก็ได้สำหรับเป้าหมายเดียว)

สิ่งที่ระบบของ Sender ต้องเตรียม:
1. กำหนดรูปแบบ Target ID ให้ชัดเจน (เช่น room-{หมายเลข}, cust-{รหัส})
2. สร้าง Link/QR Code โดยใส่ tg=TARGET_ID ที่แตกต่างกันสำหรับแต่ละอุปกรณ์หรือกลุ่ม
3. บันทึก Mapping ของ Target ID ↔ ลูกค้า/ห้อง/กลุ่ม ไว้ในระบบของคุณ
4. เมื่อต้องการส่ง Push ให้ระบุ target_ids ใน API call ตาม Mapping ที่เก็บไว้