Core API — รายงานการใช้งานและยอดเครดิต

สร้าง Dashboard ของคุณเอง จากข้อมูลบัญชี iApp ของคุณ — Core API เปิดข้อมูลการใช้งาน API และเครดิตของคุณเป็น JSON แบบอ่านอย่างเดียว (ตัวเลขชุดเดียวกับที่แสดงบน iApp dashboard) เพื่อให้คุณดึงไปใช้ใน Grafana, Google Sheets, ระบบหลังบ้านของคุณ, Slack bot หรืออะไรก็ตามที่คุยกับ HTTP ได้

• ใช้ API key เดิม ที่ใช้เรียก AI API อยู่แล้ว — ไม่ต้องตั้งค่าเพิ่ม
• อ่านอย่างเดียวโดยการออกแบบ — ทุก endpoint เป็น GET; ต่อให้ key หลุด ก็ไม่สามารถแก้ไขบัญชีผ่าน API นี้ได้
• ไม่มีข้อมูลส่วนบุคคล (PII) — ผลลัพธ์มีเฉพาะข้อมูลเชิงเทคนิค (เวลา, path, สถานะ, เครดิต, latency) ไม่มีชื่อ อีเมล IP หรือเนื้อหาคำขอ
• รายงานแยกตาม key — ออก API key หนึ่งอันต่อหนึ่งแอปพลิเคชันหรือหนึ่งลูกค้าปลายทาง แล้ววัดการใช้งานของแต่ละ key แยกกันได้
• ฟรี — การเรียก Core API ไม่หักเครดิต

Base URL: https://iapp.co.th/api/core/v1

ขอ API Key ได้ที่ไหน?

ไปที่ API Key Management เพื่อดู key ของคุณหรือสร้าง key ใหม่

Endpoints

Method	Path	คำอธิบาย
GET	/ping	ทดสอบว่า API key ใช้งานได้
GET	/credits	ยอดเครดิตคงเหลือ
GET	/usage/summary	สถิติการใช้งานแบบสรุปตามช่วงเวลา
GET	/usage/timeseries	การใช้งานตามช่วงเวลา (ราย ชั่วโมง/วัน/สัปดาห์/เดือน) — พร้อมทำกราฟ
GET	/usage/services	แยกตามบริการ (จำนวนคำขอ เครดิต latency อัตรา error)
GET	/usage/keys	แยกตาม API key — หนึ่งแถวต่อหนึ่ง key พร้อมชื่อ key
GET	/usage/records	รายการเรียก API รายรายการ พร้อม ตัวกรอง เรียงลำดับ และแบ่งหน้า

ทุก endpoint ต้องส่ง header apikey พารามิเตอร์วันที่รับทั้งรูปแบบ YYYY-MM-DD และ ISO 8601 เต็มรูปแบบ หากไม่ระบุช่วงเวลา ค่าเริ่มต้นคือ 30 วันล่าสุด

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

ส่ง API key ใน header ชื่อ apikey (ใช้ x-api-key ก็ได้):

curl "https://iapp.co.th/api/core/v1/ping" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "ok": true,
    "apiKeyPrefix": "iapp_liv...",
    "timestamp": "2026-08-05T09:30:00.000Z"
  }
}

เก็บ key ไว้ฝั่งเซิร์ฟเวอร์เท่านั้น

เรียก Core API จาก backend, cron job หรือเครื่องมือ BI ของคุณ — อย่าเรียกจาก JavaScript ในเบราว์เซอร์เด็ดขาด เพราะใครก็ตามที่เปิดดู source ของหน้าเว็บจะเห็น API key ของคุณ (เราตั้งใจบล็อกการเรียกจากเบราว์เซอร์ด้วย CORS อยู่แล้ว)

ยอดเครดิตคงเหลือ

GET /credits — เครดิต iApp (IC) ที่เหลืออยู่ของคุณ

curl "https://iapp.co.th/api/core/v1/credits" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "balance": 1234.56,
    "currency": "IC",
    "validUntil": "2027-01-31T16:59:59.000Z"
  }
}

เหมาะกับการทำระบบแจ้งเตือนเครดิตใกล้หมด: ตั้ง cron ตรวจทุกชั่วโมงแล้วแจ้งเตือนเมื่อ balance ต่ำกว่าเกณฑ์ที่กำหนด

สรุปการใช้งาน

GET /usage/summary — ตัวเลขภาพรวมของช่วงเวลา

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
startDate	date	30 วันก่อน	เริ่มต้นช่วงเวลา
endDate	date	ปัจจุบัน	สิ้นสุดช่วงเวลา
apiKeyId	uuid	—	เฉพาะคำขอที่เรียกด้วย API key นี้ — ใช้ keyId จาก /usage/keys

curl "https://iapp.co.th/api/core/v1/usage/summary?startDate=2026-08-01&endDate=2026-08-05" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T00:00:00.000Z" },
    "totalRequests": 18342,
    "totalCredits": 2311.75,
    "avgLatencyMs": 412,
    "successRate": 99.12,
    "topEndpoints": [
      { "endpoint": "/thai-ocr/v3.5/ocr-document", "requests": 9120, "credits": 1824.0 },
      { "endpoint": "/v3/store/data/thai-legal/search", "requests": 4210, "credits": 421.0 }
    ]
  }
}

การใช้งานตามช่วงเวลา (Timeseries)

GET /usage/timeseries — จำนวนคำขอและเครดิตต่อช่วงเวลา พร้อมป้อนเข้ากราฟได้ทันที

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
startDate	date	30 วันก่อน	เริ่มต้นช่วงเวลา
endDate	date	ปัจจุบัน	สิ้นสุดช่วงเวลา
groupBy	enum	day	hour, day, week หรือ month
apiKeyId	uuid	—	เฉพาะคำขอที่เรียกด้วย API key นี้ — ใช้ keyId จาก /usage/keys

curl "https://iapp.co.th/api/core/v1/usage/timeseries?startDate=2026-08-01&endDate=2026-08-05&groupBy=day" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T00:00:00.000Z" },
    "groupBy": "day",
    "points": [
      { "date": "2026-08-01T00:00:00.000Z", "requests": 4102, "credits": 512.25 },
      { "date": "2026-08-02T00:00:00.000Z", "requests": 3876, "credits": 488.5 },
      { "date": "2026-08-03T00:00:00.000Z", "requests": 5211, "credits": 651.0 }
    ]
  }
}

เวลาของแต่ละ bucket เป็น UTC — แปลงเป็นเวลาไทย (UTC+7) ตอนแสดงผล

แยกตามบริการ

GET /usage/services — หนึ่งแถวต่อหนึ่งบริการ iApp ที่คุณเรียก พร้อมตัวชี้วัดคุณภาพ

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
startDate / endDate	date	30 วันล่าสุด	ช่วงเวลารายงาน
sortBy	enum	requests	requests, credits, latency หรือ errorRate
sortOrder	enum	desc	asc หรือ desc
apiKeyId	uuid	—	เฉพาะคำขอที่เรียกด้วย API key นี้ — ใช้ keyId จาก /usage/keys

curl "https://iapp.co.th/api/core/v1/usage/services?sortBy=credits&sortOrder=desc" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-07-06T09:30:00.000Z", "endDate": "2026-08-05T09:30:00.000Z" },
    "services": [
      { "service": "document-ocr", "requests": 9120, "credits": 1824.0, "avgLatencyMs": 890, "errorRate": 0.4 },
      { "service": "thai-legal", "requests": 4210, "credits": 421.0, "avgLatencyMs": 210, "errorRate": 0.1 }
    ]
  }
}

แยกตาม API key

GET /usage/keys — หนึ่งแถวต่อหนึ่ง API key ที่ถูกใช้ในช่วงเวลานั้น — endpoint สำหรับผู้ให้บริการต่อ (reseller) และระบบหลายผู้เช่า (multi-tenant): สร้าง key หนึ่งอันต่อหนึ่งแอปพลิเคชันหรือหนึ่งลูกค้าปลายทางใน API Key Management แล้วแต่ละแถวจะวัดการใช้งานของ key นั้น

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
startDate / endDate	date	30 วันล่าสุด	ช่วงเวลารายงาน
sortBy	enum	requests	requests, credits หรือ lastUsed
sortOrder	enum	desc	asc หรือ desc

curl "https://iapp.co.th/api/core/v1/usage/keys?startDate=2026-08-01" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-24T00:00:00.000Z" },
    "keys": [
      {
        "keyId": "0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c",
        "keyName": "customer-a-production",
        "keyPrefix": "iapp_live_ab",
        "requests": 9120,
        "credits": 1824.0,
        "errorRate": 0.4,
        "avgLatencyMs": 890,
        "lastUsedAt": "2026-08-23T14:22:31.000Z"
      },
      {
        "keyId": "b4f0a2d1-7c3e-4d5a-8e9f-1a2b3c4d5e6f",
        "keyName": "customer-b-production",
        "keyPrefix": "iapp_live_cd",
        "requests": 4210,
        "credits": 421.0,
        "errorRate": 0.1,
        "avgLatencyMs": 210,
        "lastUsedAt": "2026-08-24T08:01:12.000Z"
      }
    ]
  }
}

keyId คือ id ของ key จากหน้า API Key Management — ไม่ใช่ตัว key เอง นำไปใส่เป็นพารามิเตอร์ apiKeyId ใน /usage/summary, /usage/timeseries, /usage/services หรือ /usage/records เพื่อจำกัดรายงานใด ๆ ให้เหลือเฉพาะ key นั้น key ที่ถูกลบออกจากบัญชีแล้วจะยังปรากฏอยู่ (เพื่อให้ยอดรวมของบัญชีตรงกัน) โดย keyId, keyName และ keyPrefix เป็น null

รายการเรียก API — กรอง เรียงลำดับ แบ่งหน้า

GET /usage/records — log การเรียก API แบบรายรายการ หนึ่งแถวต่อหนึ่งคำขอ — endpoint หลักสำหรับทำรายงานแบบกำหนดเอง

พารามิเตอร์	ชนิด	ค่าเริ่มต้น	คำอธิบาย
startDate / endDate	date	30 วันล่าสุด	ช่วงเวลารายงาน
service	string	—	เฉพาะคำขอไปยังบริการนี้ (ใช้ค่า service จาก /usage/services)
method	enum	—	GET, POST, PUT, DELETE, PATCH
status	int	—	สถานะ HTTP แบบเจาะจง เช่น 402
statusClass	enum	—	2xx, 3xx, 4xx หรือ 5xx (ไม่มีผลเมื่อระบุ status)
minCredits	number	—	เฉพาะคำขอที่มีค่าใช้จ่ายอย่างน้อยเท่านี้ (IC)
apiKeyId	uuid	—	เฉพาะคำขอที่เรียกด้วย API key นี้ — ใช้ keyId จาก /usage/keys
sortBy	enum	timestamp	timestamp, credits, latency หรือ status
sortOrder	enum	desc	asc หรือ desc
limit	int	100	จำนวนแถวต่อหน้า 1–1000
offset	int	0	ตำแหน่งเริ่มต้น (limit + offset ≤ 10,000 — ถ้าต้องการลึกกว่านั้นให้แคบช่วงวันที่ลง)

ตัวอย่าง — 50 คำขอที่แพงที่สุดของเดือนนี้:

curl "https://iapp.co.th/api/core/v1/usage/records?startDate=2026-08-01&sortBy=credits&sortOrder=desc&limit=50" \
  -H "apikey: YOUR_API_KEY"

ตัวอย่าง — คำขอที่ล้มเหลว (4xx) ของบริการหนึ่ง เรียงจากเก่าไปใหม่:

curl "https://iapp.co.th/api/core/v1/usage/records?service=document-ocr&statusClass=4xx&sortBy=timestamp&sortOrder=asc" \
  -H "apikey: YOUR_API_KEY"

ตัวอย่าง — คำขอของ key เดียว (รายงานรายลูกค้า):

curl "https://iapp.co.th/api/core/v1/usage/records?apiKeyId=0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c&startDate=2026-08-01" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T09:30:00.000Z" },
    "records": [
      {
        "timestamp": "2026-08-04T14:22:31.000Z",
        "service": "document-ocr",
        "endpoint": "/thai-ocr/v3.5/ocr-document",
        "method": "POST",
        "status": 402,
        "credits": 0,
        "latencyMs": 18,
        "apiKeyPrefix": "iapp_liv...",
        "keyId": "0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c",
        "keyName": "customer-a-production"
      }
    ],
    "pagination": { "total": 3, "limit": 100, "offset": 0, "hasMore": false }
  }
}

การแบ่งหน้า: เรียกซ้ำโดยเพิ่ม offset ครั้งละ limit จนกว่า hasMore จะเป็น false

Postman Collection

ถนัดคลิกมากกว่าพิมพ์ curl? นำเข้า collection สำเร็จรูป — ครบทั้ง 7 endpoints พร้อมตัวอย่างตัวกรองแบบเปิด/ปิดได้ และชุดทดสอบในตัว 66 ข้อ (รวมการตรวจ PII รั่ว):

• Collection · Environment สำหรับ Production

นำเข้า collection กับ environment แล้วตั้งค่าตัวแปร apikey ก็ใช้งานได้ทันที

สร้าง Dashboard ใน 20 บรรทัด

Python — รายงานค่าใช้จ่ายรายวัน:

import requests

BASE = "https://iapp.co.th/api/core/v1"
HEADERS = {"apikey": "YOUR_API_KEY"}

credits = requests.get(f"{BASE}/credits", headers=HEADERS).json()["data"]
series = requests.get(
    f"{BASE}/usage/timeseries",
    headers=HEADERS,
    params={"startDate": "2026-08-01", "groupBy": "day"},
).json()["data"]

print(f"ยอดคงเหลือ: {credits['balance']:.2f} IC")
for point in series["points"]:
    print(f"{point['date'][:10]}  {point['requests']:>6} คำขอ  {point['credits']:>8.2f} IC")

Node.js — แจ้งเตือนเครดิตใกล้หมด (รันจาก cron):

const BASE = "https://iapp.co.th/api/core/v1";
const THRESHOLD = 100; // IC

const res = await fetch(`${BASE}/credits`, {
  headers: { apikey: process.env.IAPP_API_KEY },
});
const { data } = await res.json();

if (data.balance < THRESHOLD) {
  await notifySlack(` เครดิต iApp ใกล้หมด: เหลือ ${data.balance} IC`);
}

การออกแบบด้านความปลอดภัยและความเป็นส่วนตัว

Core API ถูกออกแบบให้แม้ในกรณีเลวร้ายที่สุด — API key ของคุณหลุด — ความเสียหายก็ถูกจำกัด:

• อ่านอย่างเดียว มีเฉพาะ endpoint แบบ GET — ไม่มีทางสร้าง key ใช้เครดิต แก้ไขการตั้งค่า หรือลบข้อมูลผ่าน API นี้ได้
• ไม่มีข้อมูลส่วนบุคคล ผลลัพธ์ไม่มีชื่อ อีเมล user ID ที่อยู่ IP ของผู้เรียก request header หรือเนื้อหาของคำขอ/คำตอบ API — path ของ endpoint จะถูกตัด query string ออก (เพราะอาจมีข้อมูลของผู้ใช้) และ API key แสดงเพียง 8 ตัวอักษรแรกเท่านั้น
• ข้อมูลของคุณเท่านั้น key ระบุบัญชีของคุณ ไม่มีพารามิเตอร์ใดที่เข้าถึงข้อมูลบัญชีอื่นได้ — พารามิเตอร์ apiKeyId รับเฉพาะ id ของ key ในบัญชีคุณเอง ค่าอื่นจะได้ 404
• จำกัดอัตราการเรียก 120 คำขอ/นาที ต่อ API key เกินกว่านั้นจะได้ HTTP 429 — แนะนำให้ dashboard ดึงข้อมูลทุก 30–60 วินาทีก็เพียงพอ

หาก key ของคุณหลุด ให้เพิกถอนได้ที่ API Key Management — ประวัติการใช้งานยังอยู่ครบ

ข้อผิดพลาด (Errors)

HTTP	Code	ความหมาย
401	UNAUTHORIZED	ไม่ได้ส่ง API key หรือ key ไม่ถูกต้อง
403	FORBIDDEN	บัญชียังไม่ active
400	VALIDATION_ERROR	พารามิเตอร์ผิด — ดูรายละเอียดใน error.details.errors
404	NOT_FOUND	apiKeyId ไม่ใช่ key ของบัญชีนี้
429	TOO_MANY_REQUESTS	เรียกเกินอัตราที่กำหนด (120/นาที ต่อ key)
503	SERVICE_UNAVAILABLE	ระบบขัดข้องชั่วคราว — retry แบบ backoff

ทุก error มีรูปแบบเดียวกัน:

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key." }
}

คำถามที่พบบ่อย

เรียก Core API เสียเครดิตไหม? ไม่เสีย — ฟรี และไม่ปรากฏในรายการใช้งานของคุณ

ข้อมูลสดแค่ไหน? รายการใช้งานปรากฏภายในไม่กี่วินาทีหลังคำขอ API เสร็จ ส่วนยอดเครดิตเป็นแบบ real-time

ดูข้อมูลย้อนหลังได้นานแค่ไหน? เท่ากับที่ dashboard บนเว็บแสดง — หากต้องการเก็บถาวรระยะยาว ให้ดึง /usage/records เป็นระยะแล้วเก็บไว้ฝั่งคุณ

ใช้ key แยกเฉพาะสำหรับรายงานได้ไหม? ได้ — สร้าง key ใหม่ใน API Key Management แล้วใช้เรียก Core API เท่านั้น แต่ละแถวของ records จะบอกว่า key ไหน (keyId, keyName) เป็นคนเรียกคำขอนั้น

ทำรายงานแยกตามลูกค้าหรือตามแอปพลิเคชันได้ไหม? ได้ — สร้าง API key หนึ่งอันต่อหนึ่งลูกค้าหรือหนึ่งแอปพลิเคชัน แล้วใช้ /usage/keys ดูภาพรวมแยกตาม key และใช้พารามิเตอร์ apiKeyId จำกัด endpoint การใช้งานอื่น ๆ ให้เหลือ key เดียว