Bank-Slip-Verifier (npm)

ไลบรารีตรวจสอบสลิปโอนเงิน (Zero-dependency) สำหรับ OIIO Service Slip Verify API — ใช้ได้กับ npm, pnpm, bun, yarn หรือเบราว์เซอร์

ภาษาไทย - English

โหมดตรวจสอบ 3 แบบใน client เดียว — ยืนยันว่าสลิปที่ลูกค้าส่งมาว่า "โอนจริง" ในระบบธนาคารหรือไม่:

| โหมด | Endpoint | ความเร็ว | | --- | --- | --- | | detectAmount({ img }) | POST /api/slip | ช้าที่สุด — อ่านจำนวนเงินจากรูปด้วย OCR แล้วตรวจสอบ | | verifyAmount({ img, amount }) | POST /api/slip/:amount | เร็วกว่า — ระบุยอดที่คาดหวัง ข้ามขั้นตอน OCR | | verifyQrCode({ qrCodeData, amount }) | POST /api/slip/:amount/no_slip | เร็วที่สุด — ใช้ข้อมูล QR โดยไม่ต้องใช้รูป |

คุณสมบัติ

| ความสามารถ | รายละเอียด | | ------- | ------- | | ครบ 3 endpoints | ตรวจจับยอดด้วย OCR, รูป + ยอดที่ระบุ, และตรวจสอบด้วย QR ล้วนๆ — ผลลัพธ์ type เดียวกันทั้งหมด | | Static API | import { Client } — ไม่ต้องสร้าง instance, await Client.verifyAmount(...) ใช้ได้ทันทีกับเซิร์ฟเวอร์ hosted | | Zero dependencies | ไม่มี install scripts, ไม่มี native binaries, ไม่มี runtime deps — ESM + CJS + TypeScript types | | ใช้ได้ทุกที่ | Node.js >= 18, Bun, Deno, เบราว์เซอร์ — อะไรก็ได้ที่มี global fetch | | Errors ที่ typed | SlipApiError พร้อม HTTP status และ error slug ตามเอกสาร (amount-not-verified, slip-not-found, ...) รวมถึง SlipTimeoutError และ SlipError | | กัน timeout | ค่าเริ่มต้น 35 วินาที — เพราะการตรวจสอบอาจใช้เวลาสูงสุด 25 วินาที (OCR) |

เริ่มต้นใช้งาน

ติดตั้งด้วย package manager ตัวใดก็ได้:

npm install @byteindev/bank-slip-verifier
# หรือ
pnpm add @byteindev/bank-slip-verifier
# หรือ
yarn add @byteindev/bank-slip-verifier
# หรือ
bun add @byteindev/bank-slip-verifier

Client เป็น static wrapper พร้อมใช้ เชื่อมกับเซิร์ฟเวอร์ hosted ให้อัตโนมัติ:

import { Client } from '@byteindev/bank-slip-verifier';

// 1. รู้ยอดที่ลูกค้าควรโอน (แนะนำ — เร็วกว่า):
const { data, fromCache } = await Client.verifyAmount({
  img: 'data:image/jpeg;base64,...',
  amount: 100,
});
console.log(data.amount === 100); // true — ธนาคารยืนยันว่ามีการโอนจริง

// 2. ไม่รู้ยอด — ให้ OCR อ่านจากรูป (ช้าที่สุด):
const detected = await Client.detectAmount({ img: 'data:image/jpeg;base64,...' });
console.log(detected.data.amount); // ยอดที่ OCR อ่านได้ แล้วตรวจสอบกับธนาคาร

// 3. ใช้ข้อมูล QR อย่างเดียว ไม่ใช้รูป (เร็วที่สุด):
const qr = await Client.verifyQrCode({ qrCodeData: '004...', amount: 100 });
console.log(qr.data.ref); // เลขอ้างอิงรายการโอน

ผลลัพธ์ทุกโหมดมีโครงสร้างเดียวกัน:

{
  message: 'Slip processed successfully.',
  fromCache: false, // true เมื่อตอบจากแคชของเซิร์ฟเวอร์
  data: {
    ref: '202602032204376094',
    date: '2026-03-17T10:00:00.000Z',
    amount: 100,
    sender_bank: '004',
    sender_name: 'John Doe',
    sender_id: 'xxx-x-xxxxx-x',
    receiver_bank: '014',
    receiver_name: 'Jane Doe',
    receiver_id: 'xxx-x-xxxxx-x',
  },
}

ใช้เซิร์ฟเวอร์ของตัวเอง (หรือปรับแต่ง)

import { createClient } from '@byteindev/bank-slip-verifier';

const client = createClient(); // hosted: https://slip-c.oiio.download
// หรือ
const custom = createClient({ baseUrl: 'https://your-deployment.example.com' });
// หรือตั้งค่า static client:
Client.configure({ baseUrl: 'https://your-deployment.example.com' });

const result = await client.verifyAmount({ img: 'data:image/jpeg;base64,...', amount: 100 });

ลำดับการหา Base URL: option baseUrl > environment variable BANK_SLIP_VERIFIER_BASE_URL > เซิร์ฟเวอร์ hosted:

BANK_SLIP_VERIFIER_BASE_URL=https://staging.example.com node app.js

เรื่อง Timeout

การตรวจสอบอาจใช้เวลาสูงสุด 25 วินาที (endpoint OCR) เอกสาร API แนะนำให้ตั้ง HTTP timeout 30 วินาทีขึ้นไป — ไลบรารีนี้ตั้งค่าเริ่มต้นไว้ที่ 35 วินาที และจะ throw SlipTimeoutError เมื่อไม่ได้รับคำตอบภายในเวลา:

const client = createClient({ timeoutMs: 60_000 }); // หรือลดลงได้ แต่ไม่ควรต่ำกว่า 30_000

ข้อกำหนดการใช้งาน (Terms of Service)

API ปฏิเสธทุกคำขอถ้าไม่ยอมรับ TOS, Privacy และ EULA โดยไลบรารีจะส่ง { tos: true, privacy: true, eula: true } เป็นค่าเริ่มต้น (การใช้บริการถือว่ายอมรับข้อกำหนด) สามารถ override ได้ทั้งระดับ client และระดับการเรียก:

createClient({ consent: { tos: true, privacy: false, eula: true } }); // ระดับ client
client.detectAmount({ img, consent: { tos: false } });                 // ระดับการเรียก (มีผลกว่า)

จัดการ Errors

Error ทั้งหมดสืบทอดจาก SlipError ข้อผิดพลาดจาก API จะมาเป็น SlipApiError พร้อม HTTP status และ error slug ตามเอกสาร:

import { SlipApiError, SlipTimeoutError, SlipError } from '@byteindev/bank-slip-verifier';

try {
  const { data } = await Client.verifyAmount({ img, amount: 100 });
} catch (err) {
  if (err instanceof SlipApiError) {
    console.log(err.status, err.slug, err.message);
    // 422 'amount-not-verified' 'Amount not verified'
    if (err.slug === 'amount-not-verified') {
      // แจ้งลูกค้าให้ตรวจสอบยอดอีกครั้ง — สลิปไม่ตรงกับยอดจริง
    }
  } else if (err instanceof SlipTimeoutError) {
    // ตรวจสอบนานเกิน timeoutMs — ให้ลองใหม่ภายหลัง
  }
}

| HTTP | slug | สาเหตุ | | --- | --- | --- | | 400 | bad-request | body ไม่ถูกต้อง / ขาด field | | 400 | terms-not-accepted | ไม่ได้ยอมรับ TOS/Privacy/EULA | | 400 | invalid-image | base64 image ไม่ถูกต้อง | | 422 | qr-not-found | หา QR ในรูปไม่เจอ | | 422 | invalid-qr | QR format ไม่ถูกต้อง | | 422 | amount-not-found | OCR อ่านจำนวนเงินไม่ได้ | | 422 | amount-not-verified | OCR อ่านยอดได้ แต่ยอดนั้นตรวจสอบกับธนาคารไม่ผ่าน | | 422 | invalid-slip-data | ข้อมูลสลิปไม่สมบูรณ์ | | 404 | slip-not-found | ไม่พบสลิปในระบบธนาคาร |

SlipApiError.slug เป็น type ตรงกับค่าเหล่านี้ (SLIP_ERROR_SLUGS และ isSlipErrorSlug export ไว้สำหรับเช็คตอน runtime)

หมายเหตุจาก API จริง (ตรวจสอบกับบริการจริงด้วยสลิปจริง): เอกสารระบุว่า ยอดไม่ตรง จะได้ 422 amount-not-verified แต่ API จริงตอบ 404 slip-not-found ("ไม่พบข้อมูลสลิป...") เมื่อยอดที่ส่งไม่ตรงกับสลิป — ในโค้ดธุรกิจควรจัดการ ทั้งสอง slug ว่าเป็นกรณี "ยอดไม่ตรงกัน"

การใช้งานในเบราว์เซอร์ / Edge

แพ็กเกจนี้ไม่มี dependency เฉพาะ Node — ใช้ได้ทุกที่ที่มี fetch ระดับ global ใช้ bundler ตัวโปรดรวมไฟล์แล้วเรียกจาก client-side ได้เลย:

import { Client } from '@byteindev/bank-slip-verifier';
// const Client = window.ByteInDevBankSlipVerifier.Client; // CDN build

const file = fileInput.files[0];
const reader = new FileReader();
reader.onload = async () => {
  const { data } = await Client.verifyAmount({ img: reader.result, amount: 100 });
};
reader.readAsDataURL(file);

หมายเหตุ: การตรวจสอบอาจใช้เวลาหลายวินาที — ควรรักษา timeoutMs ไว้ที่ 30 วินาทีขึ้นไป

Live smoke tests

แพ็กเกจมาพร้อม live smoke test ต่อเซิร์ฟเวอร์จริง (ข้ามโดยค่าเริ่มต้น):

BANK_SLIP_VERIFIER_BASE_URL=https://slip-c.oiio.download npm run test:live

การเช็คยอดไม่ตรงกับสลิปจริง เป็นแบบ opt-in (ไม่ commit สลิปจริงขึ้น repo):

BANK_SLIP_VERIFIER_LIVE_IMAGE=C:\path\to\slip.jpg npm run test:live

API Reference

| Export | คำอธิบาย | | --- | --- | | Client | static wrapper รอบ instance ร่วม (ชี้ไปที่เซิร์ฟเวอร์ hosted โดยค่าเริ่มต้น) | | createClient(options?) | สร้าง SlipClient ใหม่ ชี้ไปที่ hosted หรือ baseUrl ที่กำหนด | | SlipClient | คลาส client; detectAmount, verifyAmount, verifyQrCode | | DEFAULT_BASE_URL | https://slip-c.oiio.download | | ENV_BASE_URL | BANK_SLIP_VERIFIER_BASE_URL — env-var fallback สำหรับ base URL | | SlipError / SlipApiError / SlipTimeoutError | คลาส error แบบ typed | | SLIP_ERROR_SLUGS, isSlipErrorSlug | ค่าคงที่ error slug + type guard | | VERSION | เวอร์ชันของแพ็กเกจ |

Credits

Powered by OIIO Service Slip Verify API.

License

MIT © ByteInDev