เรื่องเบิกค่าใช้จ่าย

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

ทุก response ในกลุ่มนี้ห่อด้วย data และวันที่เป็น Unix seconds

อ่านหมวดค่าใช้จ่ายก่อน

GET /expense-categories → อาร์เรย์ใน data ไม่แบ่งหน้า

categoryId ของรายการต้องเป็นหมวดที่มีอยู่จริงในองค์กรนี้ จึงควรดึงมาครั้งเดียวแล้วเก็บไว้ใช้

curl -X GET "$ABSERP_API_URL/openapi/v1/expense-categories?isActive=true" \
  -H "Authorization: Bearer $ABSERP_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": 3,
      "nameTh": "ค่าเดินทาง",
      "nameEn": "Travel",
      "icon": "car",
      "isSystem": true,
      "isOther": false,
      "isActive": true,
      "sortOrder": 1,
      "requiredFields": ["tripDestination", "tripPurpose"],
      "accountCode": "5210"
    }
  ]
}

requiredFields เป็นส่วนที่มีประโยชน์ที่สุด เพราะบอกว่าหมวดนี้บังคับให้กรอกฟิลด์ที่ปกติไม่บังคับข้อใด หมวดค่าเดินทางมักต้องการ tripDestination และ tripPurpose ส่วนหมวดค่าที่พักต้องการ checkinDate และ checkoutDate ควรอ่านค่านี้แล้วปรับฟอร์มตาม ไม่ควรเขียนกฎฝังไว้ในโค้ด

isActive เป็นตัวกรองเดียวที่ endpoint นี้รับ

สร้างเรื่องเบิก

POST /expense-claims → 201 คืนเรื่องเบิกใน data

ต้องระบุ title และควรส่งรายการย่อยมาพร้อมกันในคำขอเดียว เพราะ endpoint ระดับรายการย่อยไม่ได้เปิดใน Open API เรื่องที่สร้างโดยให้ items ว่างไว้จึงเพิ่มรายการทีหลังจากระบบที่เชื่อมต่อไม่ได้

curl -X POST "$ABSERP_API_URL/openapi/v1/expense-claims" \
  -H "Authorization: Bearer $ABSERP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "เดินทางพบลูกค้า กรุงเทพฯ เดือนกันยายน",
    "note": "ปฏิบัติงานที่หน้างานสองวัน",
    "reimbursementMethod": "bank_transfer",
    "items": [
      {
        "categoryId": 3,
        "expenseDate": 1757289600,
        "description": "ค่าแท็กซี่จากสนามบิน",
        "amount": 420,
        "currencyCode": "THB",
        "paidWith": "cash",
        "tripDestination": "กรุงเทพฯ",
        "tripPurpose": "พบลูกค้า",
        "hasTaxInvoice": false
      }
    ]
  }'

ฟิลด์ระดับเรื่อง

ฟิลด์รายการย่อย

amount เป็นยอดรวม VAT อยู่ข้างในแล้ว และ vatAmount บอกว่าเป็นเท่าไร ไม่ต้องนำสองค่ามาบวกกัน

ข้อมูลที่คืนกลับ

{
  "success": true,
  "data": {
    "id": 12,
    "claimNo": "EX-2026-0012",
    "title": "เดินทางพบลูกค้า กรุงเทพฯ เดือนกันยายน",
    "status": "draft",
    "totalAmount": 420,
    "claimantName": "สมหญิง ใจดี",
    "reimbursementMethod": "bank_transfer",
    "submittedAt": null,
    "reviewedBy": null,
    "reviewedAt": null,
    "paidAt": null,
    "createdAt": 1757289600,
    "items": [
      {
        "id": 30,
        "categoryId": 3,
        "categoryNameTh": "ค่าเดินทาง",
        "categoryNameEn": "Travel",
        "expenseDate": 1757289600,
        "description": "ค่าแท็กซี่จากสนามบิน",
        "amount": 420,
        "currencyCode": "THB",
        "paidWith": "cash",
        "hasAttachment": false,
        "attachments": []
      }
    ]
  }
}

totalAmount คำนวณจากรายการย่อย ให้ส่งยอดของแต่ละรายการแล้วอ่านยอดรวมกลับมา

ค้นหาเรื่องเบิก

GET /expense-claims → แบ่งหน้า อยู่ใน data เป็นมุมมองของผู้อนุมัติ ครอบคลุมทุกเรื่องในองค์กรที่ผู้ใช้เจ้าของคีย์มีสิทธิ์เห็น

GET /expense-claims/my ไม่เปิดให้ใช้ผ่าน Open API (ใช้ได้ในเว็บแอปเท่านั้น) ให้ใช้ membershipId กรองรายการนี้แทน

แถวในรายการ ไม่มี items เพื่อให้ payload เล็ก หากต้องการรายการย่อยให้เรียกอ่านรายละเอียด

อ่านเรื่องเบิกรายรายการ

GET /expense-claims/{id} → คืนเรื่องเบิกใน data พร้อม items, attachments ของแต่ละรายการ และ claimantBank (bankId, bankCompany, accountName, accountNoMasked — เลขบัญชีปิดบังเหลือสี่ตัวท้าย และไม่มี endpoint ใดที่เปิดเผยเลขเต็ม)

แก้ไขเรื่องเบิก

PATCH /expense-claims/{id} แก้ข้อมูลส่วนหัวของเรื่อง คือ title, note, reimbursementMethod

endpoint ระดับรายการย่อย (POST /expense-claims/{id}/items, PUT .../items/{itemId}, DELETE .../items/{itemId}) ไม่เปิดให้ใช้ผ่าน Open API (ใช้ได้ในเว็บแอปเท่านั้น) ให้ส่งอาร์เรย์ items ทั้งชุดตอนสร้างเรื่อง

สถานะ

สถานะอ่านได้ แต่เปลี่ยนจากที่นี่ไม่ได้

ขั้นตอนอนุมัติทั้งชุด คือ submit, approve, reject, request-revision, record-payment, cancel ไม่เปิดให้ใช้ผ่าน Open API (ใช้ได้ในเว็บแอปเท่านั้น) เพราะการอนุมัติเงินคืนคือจุดที่ต้องมีคนตรวจ ระบบที่เชื่อมต่อจึงทำได้แค่สร้างเรื่อง แล้วให้คนดำเนินการต่อใน ABSERP

ใบเสร็จแนบ

การอ่านจะเห็นไฟล์ที่แนบไว้แล้ว รายการที่มีไฟล์แนบจะขึ้น hasAttachment: true และแต่ละรายการใน attachments มี originalFilename, mimeType, sizeBytes และ fileKey

การอัปโหลดและลบใบเสร็จ (POST /expense-claims/{id}/items/{itemId}/attachments, DELETE .../attachments/{attachmentId}) ไม่เปิดให้ใช้ผ่าน Open API (ใช้ได้ในเว็บแอปเท่านั้น) เพราะเป็นการรับส่งไฟล์แบบ multipart ไม่ใช่ส่วนหนึ่งของสัญญาการเชื่อมต่อข้อมูล

รหัสข้อผิดพลาด

เรื่องเบิกที่อยู่นอกสมาชิกภาพของคุณจะตอบ 404 ExpenseClaimNotFound เมื่อคุณแค่พยายามอ่าน แต่ตอบ 403 Forbidden เมื่อคุณพยายามแก้ไข การอ่านตั้งใจไม่เปิดเผยว่าเรื่องเบิกนั้นมีอยู่ หากคุณไม่มีสิทธิ์เห็นมัน

ขั้นตอนถัดไป

อ่านต่อที่ ผู้ติดต่อ