LESS SDK — คู่มือสำหรับนักพัฒนา EDC

Base URL

ค่านี้ส่งเข้าทุก SDK call (provision(), postSlip(), syncBatch(), getSyncStatus()):

val baseUrl = "https://less-api.loxbit.co.th"

ค่าที่ผูกไว้กับเครื่องทดสอบ UAT

ค่าชุดนี้อ่านจากตารางบน UAT จริง (less_devices / less_terminal_bindings / less_device_merchants) ไม่ใช่จากเอกสาร

ชื่อร้านที่จะขึ้นบนสลิป (ร้านทดสอบ UAT (ไม่ใช่ร้านจริง)) ฝั่ง server ใส่ให้เอง จาก registration — ห้ามส่งมา field merchant_name เป็น json:"-" คือเครื่องตั้งชื่อร้านตัวเองไม่ได้โดยการออกแบบ

Network

เช็คก่อนเริ่มเขียนโค้ด

รันจากเครื่อง EDC หรือเครื่องที่อยู่วงเดียวกัน ถ้าไม่ได้ 200 คือติดที่ network ไม่ใช่ที่โค้ด:

curl -sS -o /dev/null -w '%{http_code}\n' https://less-api.loxbit.co.th/healthz

เครื่องที่ LESS ยังไม่รู้จัก เรียก provision() จะได้ 404 DEVICE_NOT_FOUND ทันที เพราะ endpoint นั้นทำหน้าที่แลก bootstrap code เท่านั้น ไม่ได้สร้าง device ให้ DEVICE_NOT_FOUND ไม่ใช่ bug ฝั่งคุณ — มันแปลว่าเรายังไม่ได้ seed serial นั้น

ขั้นตอน

ยังไม่มีเลข MID/TID จริงก็เริ่มได้

ถ้าเลข merchant จริงยังไม่นิ่ง ทีม LESS ผูกเครื่องกับ MID/TID ทดสอบให้ก่อนได้ ทดสอบครบทั้ง flow (provision → postSlip → ลูกค้าเปิดสลิป) แล้วเปลี่ยนเป็นเลขจริงทีหลัง การเปลี่ยน binding ไม่ทำให้ secret ของเครื่องหาย (D78)

ถ้า secret หายบนเครื่อง

เช่น reinstall แอปแล้วไม่ได้ backup KeyStore — เรียก provision() ด้วย code เดิม จะได้ 409 DEVICE_ALREADY_PROVISIONED ไม่ใช่ secret ต้องแจ้งทีม LESS ให้ reset ฝั่ง server แล้วออก code ใหม่ (ฝั่งเรามี POST /api/v1/admin/devices/reissue-bootstrap ให้แล้ว ไม่ต้องแก้ DB มืออีก)

1. Device Provisioning — ทำครั้งเดียวตลอดอายุเครื่อง

• TMS → LESS core-api
  ลงทะเบียนเครื่องผ่าน POST /api/v1/tms/terminals ด้วย serial + ข้อมูล merchant
  ระยะ UAT: ทีม LESS ทำขั้นนี้ให้มือ — ดู § ขอ Onboard
• LESS core-api → TMS
  LESS ออก bootstrap code ใช้ครั้งเดียว (TTL 48 ชม. ผูกกับ serial)
• EDC App → LESS core-api
  แอปเรียก LESSClient.provision(baseUrl, serial, bootstrapCode) เพื่อแลกเป็น secret ถาวร — endpoint นี้ไม่ต้องเซ็น HMAC ตัว code คือหลักฐานในตัวเอง
• EDC App
  เก็บ secret ลง Android KeyStore — server คืนให้ครั้งเดียว

2. Transaction — Online และ Offline Queue

• ลูกค้า → EDC App
  payment host อนุมัติรายการเรียบร้อยแล้ว
  ลำดับนี้สำคัญ: รายการถูกอนุมัติก่อนสลิปจะเกิด นี่คือเหตุผลที่ D88 เลิกให้ LESS ปฏิเสธสลิป
• EDC App → LESS core-api
  ประกอบ payload ด้วย SlipRequestBuilder แล้วส่ง POST /api/v1/slips พร้อม HMAC
• LESS core-api → EDC App
  ตรวจ signature → resolve เจ้าของสลิป → เลือก template → ตอบ trusted_url, claim_code, token
• Offline Failover
  ถ้าเน็ตล่ม เขียน payload ลง local queue ของเครื่อง พอเน็ตกลับมาส่งรวมทีเดียวด้วย client.syncBatch() (POST /api/v1/sync/batch, ไม่เกิน 50 รายการ/call)

1. Git Submodule

git submodule add http://172.29.220.3:3000/panuwat/terminal-sdk-android.git terminal-sdk-android

cd terminal-sdk-android && git fetch && git checkout main && git pull

2. Gradle

ใน settings.gradle.kts:

include(":terminal-sdk-android")
project(":terminal-sdk-android").projectDir = File("./terminal-sdk-android")

ใน app/build.gradle.kts:

dependencies {
    implementation(project(":terminal-sdk-android"))
}

ใน AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

เวอร์ชันที่ต้องใช้

LESSSecurityInterceptor ทำให้อัตโนมัติทุก signed request ไม่ต้องเขียนเอง หัวข้อนี้มีไว้เพื่อไล่หาสาเหตุตอนเจอ 401 เท่านั้น

string-to-sign =
  {METHOD}\n{PATH}\n{X-API-Key}\n{X-Timestamp}\n{X-Nonce}\n{HEX(SHA256(BODY))}

• PATH ที่เซ็น ไม่รวม query string
• HEX(SHA256(BODY)) ของ body เปล่า = sha256 ของ empty string
• Replay window = 600 วินาที นาฬิกาคลาดเกิน 10 นาที = ถูกปฏิเสธ (SDK แก้ skew แล้ว retry ให้ 1 ครั้งอยู่แล้ว)
• ขาด header ตัวใดตัวหนึ่งใน 4 ตัว = 401 MISSING_AUTH_HEADER
• signature ไม่ตรง = 401 INVALID_SIGNATURE

16 code ที่ลงทะเบียนไว้ในระบบ LESS (migration 013_service_types.sql):

ป้ายภาษาไทยของ service (คำถามที่ปิดไปแล้ว)

10 จาก 16 code ยังไม่มี label_th — เลิกถามไปแล้ว ไม่ต้องหาคำตอบมาให้ (D90) เพราะไม่มีอะไรใน LESS ที่ render ค่านี้เลย สลิปแสดงชนิดรายการจาก template ไม่ใช่จากป้าย และตาราง EDC-Menu ของ TMS ก็จ่ายหนี้นี้ไม่ได้ (WELFARE1, HCARE, ONUS, NHSO, BMTA, BMTASRT, WAY4, PROUD, ALIPAY_PLUS ไม่มีแถวเมนูเลย) registry จะเติมตัวเองจาก traffic จริงในโหมด learn

แลก bootstrap code (ใช้ครั้งเดียว) เป็น HMAC secret ถาวร · ไม่ต้องเซ็น HMAC

// request
{ "serial": "P302246N10589", "bootstrap_code": "<ส่งให้ทาง chat>" }

// data
{ "serial": "P302246N10589", "secret": "LESS-SEC-..." }

server คืน secret ให้ครั้งเดียว เรียกซ้ำได้ 409 DEVICE_ALREADY_PROVISIONED · serial ที่ยังไม่ได้ seed ได้ 404 DEVICE_NOT_FOUND (endpoint นี้ไม่สร้าง device)

ส่งสลิปแบบ online · payload เป็น nested envelope (header / transaction / merchant / delivery) ไม่ใช่ flat fields

// request (ตัวเต็มที่ใช้ได้จริงกับเครื่อง UAT)
{
  "header": {
    "schema_version": "1.0",
    "request_id": "<unique ต่อ request>",
    "timestamp": "2026-08-25T14:46:00Z",
    "terminal_serial_no": "P302246N10589"
  },
  "transaction": {
    "rrn": "<unique — idempotency key>",
    "ref_code": "EDC-1001",
    "approval_code": "123456",
    "trace_no": "000123",
    "batch_no": "000003",
    "amount": 100.50,
    "currency": "THB",
    "txn_date_time": "2026-08-25T14:46:00Z",
    "txn_status": "approved",
    "txn_type": "SALE",
    "payment_type": "sale",
    "entry_mode": "CONTACTLESS_CHIP"
  },
  "card_data": { "masked_pan": "524172XXXXXX5566", "card_scheme": "MASTERCARD" },
  "merchant": {
    "bank_code": "KTB",
    "mid": "UAT-DUMMY-MID-01",
    "tid": "UATDUM01",
    "service_type": "PURCHASE",
    "main_mid": "UAT-DUMMY-MID-01",
    "main_tid": "UATDUM01"
  },
  "delivery": { "delivery_method": "qr" }
}

// data
{
  "transaction_id": "...",
  "token": "ZV726CJ6JB",
  "ref_code": "EDC-1001",
  "claim_code": "62VUNF",
  "trusted_url": "https://less-customer.loxbit.co.th/v/ZV726CJ6JB",
  "expires_at": "...",
  "notification_status": "queued"    // มีเฉพาะเมื่อ delivery = sms
}

trusted_url → ทำ QR ให้ลูกค้าสแกน · claim_code → แสดงบนจอ EDC · รูปแบบ URL คือ {public_base_url}/v/{token}

field ที่บังคับ (ขาดตัวใดตัวหนึ่ง = 400 VALIDATION_FAILED)

header.schema_version · header.request_id · header.timestamp · transaction.rrn · transaction.ref_code · transaction.currency · transaction.txn_status · transaction.amount (> 0) · transaction.txn_date_time · merchant.bank_code · merchant.mid · merchant.tid · delivery.delivery_method

Enum ที่ server รับ (ค่าอื่น = 400)

ส่ง offline queue รวมทีเดียว ไม่เกิน 50 item · รองรับ partial success

// data
{
  "total": 2,
  "accepted": 2,
  "rejected": 0,
  "results": [
    { "rrn": "RRN001", "result": "accepted", "retryable": false,
      "transaction_id": "...", "token": "...", "ref_code": "REF001",
      "claim_code": "...", "trusted_url": "https://less-customer.loxbit.co.th/v/..." },
    { "rrn": "RRN002", "result": "rejected", "retryable": true,
      "error_code": "SERVICE_UNAVAILABLE", "message": "..." }
  ]
}

ลบออกจาก local queue เฉพาะรายการที่ result = "accepted" · retryable = true คือส่งซ้ำได้ · false คือ payload ผิด ส่งซ้ำก็ผิดเหมือนเดิม

ปัญหาเดิม: DisallowUnknownFields ทำให้ field ที่ core-api ยังไม่ model ไว้กลายเป็น 400 INVALID_PAYLOAD — ฝั่ง EDC จึงส่งข้อมูลใหม่ไม่ได้เลยจนกว่าเราจะ deploy extensions เปิดทางให้ส่งมาก่อนได้

"extensions": {
  "welfare": { "entitlement_id": "...", "balance_before": 500.00 },
  "loyalty": { "points_earned": 25 }
}

service ไหนควรส่ง block อะไร

ทุก service_type ประกาศไว้ว่าสลิปของมันควรมี block อะไร ค่านี้ถูกตรวจและรายงาน แต่ไม่เคยบังคับ — block ที่ขาดคือปัญหา payload การปฏิเสธสลิปเพราะเรื่องนี้คือการเอาปัญหาไปวางไว้หน้าลูกค้าที่เคาน์เตอร์ ซึ่งเป็นความผิดที่ D88 แก้

Build release AAR

cd terminal-sdk-android
./gradlew assembleRelease
# ผลลัพธ์: ./build/outputs/aar/terminal-sdk-android-release.aar

โครงสร้าง package

com.loxbit.less.sdk/
├── LESSClient.kt                   — client หลัก (VERSION = "2.3.0")
├── LESSSecurityInterceptor.kt      — HMAC v1.2 + clock-skew retry
├── LESSException.kt                — exception ที่ห่อ ApiError
├── SlipRequestBuilder.kt           — builder ของ POST /api/v1/slips
├── BatchRequestBuilder.kt          — builder ของ POST /api/v1/sync/batch
├── SlipCreateResponse.kt           — response model ของสลิป
├── SyncBatchResponse.kt            — response model ของ batch
├── TerminalSyncStatus.kt           — response model ของ sync status
├── ApiError.kt                     — error code + predicate (isMerchantRevoked() ฯลฯ)
└── ProvisionResult.kt              — ผลลัพธ์ของ provision