Partner

สำหรับตัวแทนจำหน่ายที่ถือกระเป๋าเครดิตรวมหนึ่งใบ ให้ธุรกิจหลายรายในพูล — ดูยอดคงเหลือ, รายชื่อธุรกิจที่พูลจ่ายให้ และรายการเดินบัญชีที่บอกได้ว่าเงินแต่ละบาทหมดไปกับสายไหน

Account key เท่านั้น — ทุก endpoint ในหน้านี้รับเฉพาะ API key ระดับบัญชี (Settings → API Keys) business key จะได้ 403 account_key_required และ ไม่ต้องส่ง X-Business-Id (header นี้ไม่ถูกอ่านเลย) พูลถูกระบุจากเจ้าของ key เท่านั้น ไม่มีพารามิเตอร์ให้ระบุพูลอื่น

ถ้าบัญชีของคุณไม่ได้เป็นเจ้าของพูลพาร์ทเนอร์ ทุก endpoint ในหน้านี้ตอบ 404 partner_not_found

GET /partner

สถานะพูล: ยอดเครดิตคงเหลือ, แผน, และจำนวนธุรกิจ

curl https://phone.mcloud.co.th/api/v1/partner \
  -H "Authorization: Bearer crk_..."

{
  "partner": {
    "id": "01990412-6b8d-7c04-8e19-2a7f5d3c9b64",
    "name": "บริษัท เอ จำกัด",
    "status": "active",
    "businessQuota": null,
    "plan": { "id": "0192aa70-...", "key": "pro", "name": "Pro" }
  },
  "credit": {
    "balanceThb": 4820.5,
    "lifetimeToppedUpThb": 25000,
    "lifetimeSpentThb": 20179.5,
    "status": "ok"
  },
  "businessCount": 12
}

ฟิลด์	ชนิด	ความหมาย
partner.id	uuid	id ของพูล — ตรงกับ partner.id ใน payload ของ callback ระดับ account
partner.name	string	ชื่อตัวแทนจำหน่าย
partner.status	active | suspended	suspended = กระเป๋าถูกระงับ: รัน AI ไม่ได้ เติมเงินไม่ได้ เปิดธุรกิจใหม่ไม่ได้ (ข้อมูลเดิมอยู่ครบ เป็นสถานะทางบัญชี ไม่ใช่การลบ)
partner.businessQuota	int | null	เพดานจำนวนธุรกิจ — null = ไม่จำกัด (ส่งเป็น null ไม่ใช่ตัดคีย์ทิ้ง เพื่อให้แยก "ไม่มีเพดาน" ออกจาก "ไม่ได้ส่งค่ามา" ได้)
partner.plan	object | null	แผนของพูล — null เมื่อยังไม่ได้ผูกแผนไว้
partner.plan.key	string	ตัวระบุแบบคงที่ของแผน ใช้แตกเงื่อนไขในโค้ดได้
credit.balanceThb	number	ยอดคงเหลือในกระเป๋ารวม (บาท)
credit.lifetimeToppedUpThb	number	ยอดเติมสะสมตลอดอายุพูล
credit.lifetimeSpentThb	number	ยอดใช้สะสมตลอดอายุพูล
credit.status	ok | low | empty	ไฟสถานะของกระเป๋า — ดูด้านล่าง
businessCount	int	จำนวนธุรกิจที่พูลจ่ายให้อยู่ตอนนี้

credit.status มีไว้ให้ตั้ง alert โดยไม่ต้อง hard-code ตัวเลขเอง

• empty — ยอดคงเหลือ 0 หรือติดลบ เส้นนี้คือเส้นที่ระบบใช้ปฏิเสธการรัน AI จริง ๆ สายใหม่จะไม่ถูกวิเคราะห์จนกว่าจะเติมเงิน
• low — ใกล้หมด เป็นการเตือนล่วงหน้าเท่านั้น ยังรันได้ปกติ (เส้นแบ่งของ low อาจถูกปรับได้ ให้เช็คที่ค่า status ไม่ใช่ที่ตัวเลข balanceThb)
• ok — ปกติ

ยอดทั้งหมดในหน้านี้เป็นบาทฝั่งลูกค้า ใช้ตั้งบิลต่อให้ลูกค้าของคุณได้ทันที

GET /partner/businesses

ธุรกิจที่พูลจ่ายให้ พร้อมยอดใช้จ่ายของเดือนนี้รายธุรกิจ

ไม่ใช่ตัวเดียวกับ GET /businesses ซึ่งลิสต์ธุรกิจที่เจ้าของ key เป็นสมาชิก (และเป็น endpoint สำหรับสร้างธุรกิจ) ทั้งสองชุดไม่ครอบกัน: แอดมินผูกธุรกิจเข้าพูลได้โดยไม่ต้องให้สิทธิ์เข้าถึงแก่เจ้าของพูล ธุรกิจหนึ่งจึงโผล่ที่นี่แต่ไม่โผล่ที่นั่นได้

Param	Type	Note
limit	int 1-200	default 20
offset	int	default 0

curl "https://phone.mcloud.co.th/api/v1/partner/businesses?limit=2" \
  -H "Authorization: Bearer crk_..."

{
  "items": [
    {
      "id": "0192b7d1-5c30-7a92-9f41-6c2e83b4a105",
      "name": "Home For Cash",
      "slug": "home-for-cash",
      "createdAt": "2026-03-14T04:12:55.183Z",
      "spendThb": 1284.75
    },
    {
      "id": "0192b7d2-9a11-7c60-b8e4-1d05fa77c398",
      "name": "Hosting Lotus",
      "slug": "hosting-lotus",
      "createdAt": "2026-04-02T08:31:02.660Z",
      "spendThb": 0
    }
  ],
  "total": 12,
  "limit": 2,
  "offset": 0
}

• เรียงตามชื่อธุรกิจ (ก-ฮ / A-Z) — ลำดับคงที่ จึงเดินหน้าด้วย offset ได้ปลอดภัย
• spendThb = ยอดหักจากกระเป๋ารวมของธุรกิจนั้น ตั้งแต่ต้นเดือนปัจจุบันตามเวลาไทย (Asia/Bangkok) ไม่ใช่ 30 วันย้อนหลัง — ต้นเดือนใหม่ค่านี้กลับไปเป็น 0
• ธุรกิจที่ถูกลบไปแล้วไม่อยู่ในลิสต์ (แต่รายการเดินบัญชีเก่ายังอยู่ใน /partner/transactions)

GET /partner/transactions

รายการเดินบัญชีของกระเป๋ารวม เรียงใหม่สุดก่อน

Param	Type	Note
limit	int 1-200	default 20
offset	int	default 0
type	topup | debit | refund | adjustment | trial_grant | chargeback | pool_transfer	optional — กรองตามชนิดรายการ
businessId	uuid	optional — ดูเฉพาะที่ธุรกิจนั้นใช้ไปจากกระเป๋ารวม

curl "https://phone.mcloud.co.th/api/v1/partner/transactions?type=debit&limit=2" \
  -H "Authorization: Bearer crk_..."

{
  "items": [
    {
      "id": "019906b1-8c22-7d90-a4f5-0e7b13d6cc48",
      "type": "debit",
      "amountThb": -2.4132,
      "balanceAfter": 4820.5,
      "description": "AI analysis",
      "business": { "id": "0192b7d1-5c30-7a92-9f41-6c2e83b4a105", "name": "Home For Cash" },
      "callRecordingId": "0192b9c4-8e71-7a13-9d02-5f1a6c3b7e90",
      "createdAt": "2026-09-16T07:03:12.902Z"
    },
    {
      "id": "019905ff-2b41-7a08-8cc1-6f2e94b70a3d",
      "type": "topup",
      "amountThb": 5000,
      "balanceAfter": 4822.91,
      "description": "Bank transfer",
      "business": null,
      "callRecordingId": null,
      "createdAt": "2026-09-15T02:40:19.004Z"
    }
  ],
  "total": 3184,
  "limit": 2,
  "offset": 0
}

ฟิลด์	ชนิด	ความหมาย
id	uuid	id ของรายการ
type	enum	ชนิดรายการ (ดูตารางพารามิเตอร์ด้านบน)
amountThb	number	จำนวนเงิน — ติดลบคือหักออก บวกคือเข้ากระเป๋า
balanceAfter	number	ยอดคงเหลือหลังรายการนี้
description	string | null	คำอธิบายสั้น ๆ
business	object | null	ธุรกิจที่ทำให้เกิดรายการนี้ — null สำหรับการเติมเงิน/โอน/ปรับยอด ซึ่งเป็นของพูล ไม่ใช่ของธุรกิจใด
business.name	string | null	อาจเป็น null ถ้าธุรกิจนั้นถูกลบไปแล้ว
callRecordingId	uuid | null	สายที่ทำให้เกิดการหักนี้
createdAt	ISO 8601	เวลาที่เกิดรายการ

callRecordingId คือตัวเชื่อมจากยอดหักกลับไปยังสาย — เอาไปเรียก GET /recordings/{id} ต่อเพื่อดูว่าเงินก้อนนั้นไปกับสายไหน เป็นชิ้นส่วนที่ทำให้ "พูลถูกหัก 2.41 บาท ตอน 14:03" กลายเป็นบรรทัดที่คุณวางบิลต่อให้ลูกค้าของคุณเองได้

callRecordingId เป็น null ได้ 2 กรณี:

1. รายการนั้นไม่ใช่การหักค่าวิเคราะห์ (เติมเงิน, โอนระหว่างกระเป๋า, ปรับยอด, เครดิตทดลอง)
2. เป็นการหักค่าวิเคราะห์ แต่บันทึกการใช้งานเบื้องหลังหมดอายุตามระยะเก็บข้อมูลไปแล้ว — รายการเดินบัญชีอยู่นานกว่าบันทึกการใช้งานโดยตั้งใจ ตัวเงินจึงไม่หายไปไหน แต่รายการเก่ามาก ๆ อาจโยงกลับไปหาสายไม่ได้แล้ว ถ้าต้องกระทบยอดรายเดือน ให้ดึงข้อมูลภายในรอบเดือนนั้น

ใช้ ?businessId= เพื่อกระทบยอดทีละธุรกิจ และ ?type=debit เพื่อตัดรายการเติมเงินออกจากยอดใช้จ่าย

ข้อผิดพลาด

code	HTTP	เมื่อไหร่
account_key_required	403	เรียกด้วย business key
partner_not_found	404	เจ้าของ key ไม่ได้เป็นเจ้าของพูลพาร์ทเนอร์
validation_failed	422	limit / offset / type / businessId ผิดรูป

ดูการตั้ง callback ระดับพาร์ทเนอร์ (endpoint เดียวรับ event ของทุกธุรกิจในพูล) ได้ที่หน้า Callbacks → ตั้งค่า callback โดยใช้ ?level=account