API สำหรับพาร์ทเนอร์

API ระหว่างเซิร์ฟเวอร์สำหรับพาร์ทเนอร์: ออกคีย์ อ่านการตั้งค่าหน้าร้านและตำแหน่งที่ตั้ง สร้างลูกค้า มอบแพ็กเกจ และจัดการลิงก์การสมัครสมาชิกจากเว็บไซต์หรือบอต Telegram ของคุณเอง

API สำหรับพาร์ทเนอร์ช่วยให้คุณสร้าง เว็บไซต์ของคุณเอง, แดชบอร์ดของคุณเอง หรือ บอต Telegram บน CreateYourVPN ได้

API ครอบคลุม ลูกค้า การสมัครสมาชิก แพ็กเกจ และการตั้งค่าหน้าร้าน ส่วนโครงสร้างพื้นฐาน เช่น เซิร์ฟเวอร์ โหนด แผงควบคุม และข้อมูลรับรอง SSH อยู่นอกสัญญาสาธารณะ

สำหรับการเชื่อมต่อระหว่างเซิร์ฟเวอร์เท่านั้น เก็บคีย์ API ไว้บนเซิร์ฟเวอร์ของคุณ และอย่าใส่ไว้ในโค้ด frontend คำขอที่มีเฮดเดอร์ของเบราว์เซอร์จะถูกปฏิเสธด้วย 403 browser_forbidden

การรับคีย์

เปิดแดชบอร์ด → เมนูบัญชี → "API" แล้วไปที่แท็บ "คีย์"

ตั้งชื่อคีย์ (บอต Telegram, แลนดิ้งเพจ) และเลือกเฉพาะสิทธิ์ที่จำเป็น

กด "ออกคีย์" แล้วคัดลอกค่าทั้งหมด secret จะแสดงเพียง ครั้งเดียว เพราะระบบเก็บไว้เฉพาะค่า hash

พาร์ทเนอร์แต่ละรายมีคีย์ที่ใช้งานอยู่ได้สูงสุด 5 คีย์ หากต้องการหมุนเวียนคีย์ ให้ออกคีย์ใหม่ อัปเดตการเชื่อมต่อ แล้วจึงเพิกถอนคีย์เดิม

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

ส่งคีย์เป็นโทเค็นแบบ bearer:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… ก็ใช้ได้เช่นกัน สำหรับกรณีที่ Authorization ถูก proxy ใช้งานอยู่

คีย์มีรูปแบบ cyv_live_<key_id>_<secret> ครึ่งแรก (key_id) เป็นข้อมูลสาธารณะ: คือสิ่งที่คุณเห็นในแดชบอร์ด และแจ้งฝ่ายสนับสนุนได้อย่างปลอดภัย ครึ่งหลังคือ secret

สิทธิ์ (scopes)

สิทธิ์	อนุญาตให้ทำอะไร
`config:read`	อ่านการตั้งค่าหน้าร้าน แพ็กเกจ ตำแหน่งที่ตั้ง และ `/me`
`users:read`	อ่านข้อมูลลูกค้า การสมัครสมาชิก และทราฟฟิก
`users:write`	สร้างลูกค้า มอบแพ็กเกจ รีเซ็ตลิงก์การสมัครสมาชิก และลบลูกค้า

config:read เพียงพอสำหรับการเชื่อมต่อที่อ่านข้อมูลหน้าร้านอย่างเดียว เพิ่ม users:read หรือ users:write เฉพาะเมื่อการเชื่อมต่อต้องใช้การดำเนินการกับลูกค้าที่เกี่ยวข้อง

สัญญาฉบับเต็มที่เรียกใช้งานได้อยู่ในคอลเลกชัน Postman สาธารณะ ในนั้นมีทุก endpoint สิทธิ์ พารามิเตอร์ body ของคำขอ ตัวอย่างคำตอบ และรหัสข้อผิดพลาดที่คงที่ คอลเลกชันสร้างจากสัญญาของ backend และเป็นแหล่งข้อมูลปัจจุบันของสคีมาคำขอและคำตอบ

เปิดคอลเลกชัน Postman สาธารณะ

สำรวจทุก endpoint และคัดลอกคอลเลกชันไปยัง workspace ของคุณ

ขีดจำกัดอัตรา

ขีดจำกัดนับ แยกกันสำหรับแต่ละคีย์ โดยไม่ขึ้นกับที่อยู่ IP ของคำขอ

120 คำขอต่อนาที ต่อคีย์โดยรวม
10 คำขอต่อนาที สำหรับ GET /users โดยเฉพาะ

GET /users มีขีดจำกัดแยก เพราะแต่ละคำขอโหลดรายชื่อลูกค้าทั้งหมด สำหรับการตรวจสอบเป็นประจำ ให้ใช้ GET /users/{id} หรือค้นหาด้วย externalId

รูปแบบการเข้าถึงที่แนะนำ เก็บ ID ลูกค้าของ CreateYourVPN ที่ได้กลับมาตอนสร้างไว้ และใช้ GET /users/{id} สำหรับการค้นหาครั้งต่อไป คุณผูก ID นี้กับตัวระบุของคุณเองได้ผ่าน externalId

การเรียกซ้ำอย่างปลอดภัย (Idempotency)

มีสามการดำเนินการที่ต้องมีเฮดเดอร์ Idempotency-Key: การมอบแพ็กเกจ, การรีเซ็ตลิงก์การสมัครสมาชิก และ การลบลูกค้า

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

การส่งคำขอซ้ำด้วยคีย์เดิมภายใน 24 ชั่วโมง จะได้คำตอบที่บันทึกไว้แทนการดำเนินการซ้ำ วิธีนี้ป้องกันการเปลี่ยนแปลงซ้ำซ้อนเมื่อการเชื่อมต่อลองใหม่หลังหมดเวลา

สร้างคีย์หนึ่งคีย์ต่อ เหตุการณ์ทางธุรกิจ หนึ่งรายการ (เช่น การชำระเงินหนึ่งครั้งหรือการกระทำหนึ่งครั้ง) และใช้คีย์นั้นซ้ำในทุกการลองใหม่ของเหตุการณ์นั้น

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

ใช้คอลเลกชัน Postman สาธารณะด้านบนเป็นแหล่งอ้างอิงหลักของสคีมาคำขอและคำตอบ