BOT barcode

เหตุผลที่ต้องใช้

1D barcode สำหรับชำระบิลของ Bank of Thailand คือสตริง ASCII แบบหนึ่งมิติที่พิมพ์อยู่บนใบแจ้งหนี้ค่าสาธารณูปโภคในประเทศไทย ใช้สแกนที่เคาน์เตอร์ธนาคาร เคาน์เตอร์ 7-Eleven และตู้คีออสก์สำหรับการชำระบิลข้ามเคาน์เตอร์ ไม่ใช่ EMVCo, ไม่ใช่ QR และ ไม่ใช่ TLV — wire format เป็นสตริงที่ขึ้นต้นด้วย | คั่นด้วย \r และไม่มี checksum

barcode นี้อยู่ในแพ็กเกจ @thai-qr-payment/payload เดียวกันเพราะ vocabulary ของ billerId / ref1 / ref2 ตรงกับ Thai bill-payment merchant template (EMVCo tag 30) แต่ byte ที่ออกบน wire ไม่เกี่ยวข้องกัน module นี้แยกออกมาภายใต้ export ของตัวเอง เพื่อให้ผู้เรียกที่ใช้เฉพาะส่วน QR สามารถ tree-shake ทิ้งได้

import { buildBOTBarcode, parseBOTBarcode } from 'thai-qr-payment';

สร้าง

buildBOTBarcode({ billerId, ref1, ref2?, amount? }) billerId คือ biller id แบบข้ามธนาคารยาว 15 ตัวอักษร (Tax ID + suffix) input ที่สั้นกว่าจะถูก zero-pad ทางซ้ายให้เต็ม ส่วน input ที่ยาวเกินจะ throw ref1 เป็นค่าที่จำเป็น ส่วน ref2 จะเป็น empty string บน wire เมื่อไม่ระบุค่า

buildBOTBarcode({
  billerId: '099400016550100',
  ref1: '123456789012',
  ref2: '670429',
  amount: 3649.22,
});
// '|099400016550100\r123456789012\r670429\r364922'

ยอดเงินท้ายสุดจะถูกเก็บเป็น จำนวนเต็มหน่วยสตางค์ (บาท × 100 ปัดเป็นจำนวนเต็ม) หากละไว้ (หรือใส่ 0) จะเป็นยอดที่ให้แคชเชียร์กรอกเอง — sentinel '0' ตัวเดียวจะถูกเขียนลงไป และแคชเชียร์เป็นผู้พิมพ์ยอดเงินด้วยตนเอง:

buildBOTBarcode({ billerId: '099999999999990', ref1: '111222333444' });
// '|099999999999990\r111222333444\r\r0'

Throws เมื่อ input ผิดรูปแบบ — ยอดเงินติดลบ / ไม่ใช่จำนวนจำกัด, biller id ยาวเกิน, มีตัวอักษร CR อยู่ในฟิลด์ใด หรือ ref1 ว่างเปล่า เพื่อป้องกันไม่ให้ผู้เรียกสร้าง barcode ที่สแกนไม่ได้โดยไม่รู้ตัว

อ่าน

parseBOTBarcode(barcode) คืนค่าฟิลด์ที่ถอดแล้ว หรือคืน null หากมีปัญหาเชิงโครงสร้าง (เช่น ไม่มี prefix, จำนวนฟิลด์ผิด หรือ biller id สั้นเกินไป) ยอดเงินจะคืนเป็นจำนวนบาทแบบทศนิยม ส่วน sentinel '0' จะแสดงเป็น undefined

parseBOTBarcode('|099400016550100\r123456789012\r670429\r364922');
// {
//   billerId: '099400016550100',
//   ref1: '123456789012',
//   ref2: '670429',
//   amount: 3649.22,
// }

parseBOTBarcode('|099999999999990\r111222333444\r\r0');
// { billerId: '099999999999990', ref1: '111222333444' }

การคืน null แทนการ throw exception ทำให้ผู้เรียกสามารถ branch ผลลัพธ์ได้โดยไม่ต้องใช้ try / catch — เหมาะสำหรับการรับ input จาก scanner ที่อาจจะใช่หรือไม่ใช่ BOT barcode

ตัวอย่าง wire

Wire (escaped)	Decoded
|099999999999990\r111222333444\r\r0	{ billerId: '099999999999990', ref1: '111222333444' }
|099400016550100\r123456789012\r670429\r364922	{ billerId: '099400016550100', ref1: '123456789012', ref2: '670429', amount: 3649.22 }

Wire bytes: \| คือ pipe ตามตัว (0x7C ใช้เป็น sentinel); \r แต่ละตัวคือ carriage return ตัวเดียว (0x0D); ไม่มี terminator ที่ท้ายสตริง สตริงจะมี pipe หนึ่งตัวและ \r คั่นสามตัวเสมอ ไม่ว่าจะระบุฟิลด์ทางเลือกครบหรือไม่ — ช่องที่ว่างจะมีขนาด zero-width บน wire