# ยืนยันตัวตนด้วย API key

Source: https://checkslip.com/docs/authentication

ทุกคำขอไปยัง Checkslip API ต้องแนบ API key ของคุณ ออก key ได้ที่หน้า API key ในเว็บแอป

## ส่ง API key

แนบ key ใน header Authorization แบบ Bearer ทุกคำขอ key ของ Checkslip ขึ้นต้นด้วย csk_ และส่งผ่าน HTTPS เท่านั้น

```
Authorization: Bearer csk_…
```

**cURL**

```bash
curl https://api.checkslip.com/api/slips/lookup \
  -H "Authorization: Bearer $CHECKSLIP_API_KEY" \
  -H "Idempotency-Key: order-1042-slip-1" \
  -H "Content-Type: application/json" \
  -d '{"qr":"00330006000001010306902126302105340875102TH9104F86F"}'
```

**Node.js**

```javascript
const res = await fetch("https://api.checkslip.com/api/slips/lookup", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CHECKSLIP_API_KEY}`,
    "Idempotency-Key": "order-1042-slip-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    qr: "00330006000001010306902126302105340875102TH9104F86F",
  }),
});
const data = await res.json();
```

**Python**

```python
import os

import requests

res = requests.post(
    "https://api.checkslip.com/api/slips/lookup",
    headers={
        "Authorization": f"Bearer {os.environ['CHECKSLIP_API_KEY']}",
        "Idempotency-Key": "order-1042-slip-1",
    },
    json={
        "qr": "00330006000001010306902126302105340875102TH9104F86F",
    },
)
data = res.json()
```

## สิทธิ์ของ key

ตอนออก key คุณเลือกได้ว่า key นั้นทำอะไรได้บ้าง ให้แต่ละ key มีเฉพาะสิทธิ์ที่ระบบของคุณใช้จริง

| สิทธิ์ | ทำอะไรได้ |
| --- | --- |
| `slip:lookup` | ส่ง QR หรือ trans_ref ไปดึงข้อมูลรายการโอนที่ธนาคารมี (ใช้เครดิตเมื่อพบรายการ) |
| `slip:read` | อ่านประวัติผลตรวจของบัญชี |
| `credit:read` | อ่านยอดเครดิต วันหมดอายุ และประวัติเครดิต |
| `webhook:read` | อ่านปลายทางและประวัติการส่ง webhook |
| `webhook:manage` | สร้าง แก้ไข และลบปลายทาง webhook (ไม่รวมการอ่าน) |
| `audit:read` | อ่านบันทึกคำขอ API และบันทึกการเปลี่ยนแปลงของบัญชี |
| `audit:export` | สร้างและดาวน์โหลดไฟล์หลักฐาน (ต้องมี audit:read ด้วย) |
| `billing:read` | อ่านคำสั่งซื้อ ใบเสร็จ เครดิต และข้อมูลออกใบเสร็จ (รวมเลขประจำตัวผู้เสียภาษี) |
| `billing:write` | แก้ข้อมูลที่จะพิมพ์บนใบเสร็จต่อจากนี้ (เติมเครดิตด้วย key ไม่ได้) |
| `usage:read` | อ่านยอดการใช้เครดิตของบัญชี |

- สิทธิ์แต่ละตัวแยกกัน ไม่มีตัวไหนรวมอีกตัว เช่น slip:lookup ไม่ได้ให้ slip:read มาด้วย
- เปลี่ยนสิทธิ์ของ key ที่ออกแล้วไม่ได้ ถ้าต้องการสิทธิ์อื่น ให้ออก key ใหม่

## เก็บ key ให้ปลอดภัย

- เว็บแอปแสดงค่า key ทั้งหมดครั้งเดียวตอนออก คัดลอกไปเก็บทันที ถ้าทำหายให้ออก key ใหม่
- เก็บ key ไว้ฝั่งเซิร์ฟเวอร์ เช่น ตัวแปรสภาพแวดล้อมหรือที่เก็บความลับ อย่าใส่ในแอปมือถือ โค้ดหน้าเว็บ หรือ repository
- แยก key ตามระบบหรือสภาพแวดล้อม เพื่อเพิกถอนตัวเดียวได้โดยไม่กระทบที่อื่น
- key ที่ใช้งานได้สูงสุด 10 ตัวต่อบัญชี (ที่เพิกถอนหรือหมดอายุไม่นับ)

## เปลี่ยน key

1. ออก key ใหม่ในเว็บแอป
2. เปลี่ยนระบบของคุณให้ใช้ key ใหม่
3. เพิกถอน key เก่า

key ที่ถูกเพิกถอนหรือหมดอายุแล้วจะใช้ไม่ได้ภายใน 30 วินาที (ปกติทันที) และเปิดใช้กลับไม่ได้

## เมื่อ key มีปัญหา

คำขอที่ตอบด้วย error เหล่านี้ไม่หักเครดิต ดูทุกรหัสได้ที่ [รหัสข้อผิดพลาด](https://checkslip.com/docs/errors)

| รหัส | HTTP | ความหมาย |
| --- | --- | --- |
| [`UNAUTHENTICATED`](https://checkslip.com/problems/unauthenticated) | 401 | ไม่ได้ส่ง key หรือ key ใช้ไม่ได้ (ผิดรูปแบบ ถูกเพิกถอน หมดอายุ หรือไม่มีอยู่) ระบบไม่บอกว่าเป็นกรณีไหนเพื่อความปลอดภัย |
| [`FORBIDDEN`](https://checkslip.com/problems/forbidden) | 403 | key ไม่มีสิทธิ์ (scope) ของรายการนี้ |
| [`NOT_VIA_API_KEY`](https://checkslip.com/problems/not-via-api-key) | 403 | รายการนี้ทำได้เฉพาะในเว็บแอป เช่น จัดการ API key หรือเติมเครดิต |
| [`ACCOUNT_SUSPENDED`](https://checkslip.com/problems/account-suspended) | 403 | บัญชีถูกระงับการใช้งานชั่วคราว |
| [`RATE_LIMITED`](https://checkslip.com/problems/rate-limited) | 429 | เรียกถี่เกินเพดาน (มีทั้งเพดานของบัญชี และเพดานของ key ตัวนั้นถ้าตั้งไว้) รอตามวินาทีใน header Retry-After แล้วส่งใหม่ |