ให้แอปอื่นออกใบแจ้งหนี้ & ใบเสร็จเข้า ERP

External API ให้ระบบภายนอก (เช่น WideStay, POS, เว็บจอง) สั่งออก ใบกำกับภาษี/ใบแจ้งหนี้ และ ใบเสร็จรับเงิน เข้าบริษัทใน ERP โดยตรง — ลงบัญชีคู่ (double-entry) และรันเลขที่เอกสารให้อัตโนมัติ เหมือนออกจากหน้าเว็บทุกประการ

คีย์ต่อบริษัท (per-company)

แต่ละบริษัทมีคู่คีย์ของตัวเอง เจ้าของบริษัท (OWNER) สร้าง/เพิกถอนได้ที่ ตั้งค่า → การเชื่อมต่อ (Integrations) หรือผ่าน API จัดการคีย์

companyId ผูกกับคีย์เสมอ — payload ไม่ต้องระบุบริษัท และข้ามบริษัทกันไม่ได้

การยืนยันตัวตน (HMAC-SHA256)

ทุก request เซ็นด้วย secret บน raw body + timestamp กัน tamper และ replay ทุก request ต้องมี 3 header นี้:

สูตรลายเซ็น — string ที่นำมาเซ็นคือ timestamp + "." + rawBody:

// Node.js — เซ็น request
const crypto = require('crypto');
const body = JSON.stringify(payload);           // raw body ที่จะส่ง (ต้องตรงเป๊ะ)
const ts   = Math.floor(Date.now() / 1000);
const sig  = crypto.createHmac('sha256', secret)
                   .update(`${ts}.${body}`).digest('hex');

await fetch('https://erp.oneable.co.th/api/ext/v1/receipts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': keyId,
    'X-Timestamp': String(ts),
    'X-Signature': sig,
    'Idempotency-Key': paymentIntentId,
  },
  body,                                        // ← ส่ง string เดิมที่เซ็น ห้าม re-stringify
});

Idempotency & การยิงซ้ำ

ส่ง Idempotency-Key เดียวกัน (แนะนำใช้ payment intent id) ระบบจะสร้างเอกสารครั้งเดียว การยิงซ้ำคืน ผลเดิม พร้อม "replayed": true (HTTP 200) — ปลอดภัยที่จะ retry เมื่อ network ล้ม

ออกใบกำกับภาษี / ใบแจ้งหนี้

สร้างและ issue ใบกำกับภาษีทันที (ลง GL: เดบิตลูกหนี้ / เครดิตรายได้+ภาษีขาย) ลูกค้าจับคู่จากเลขผู้เสียภาษี ถ้าไม่มีจะสร้างให้ · ต้องมี scope invoice:create

Request body

Response 201

{
  "id": "cly…",
  "taxInvoiceNo": "IV69070001",   // เลขใบกำกับภาษี
  "subTotal": 1000,
  "vatAmount": 70,
  "total": 1070,
  "status": "ISSUED",
  "replayed": false
}

ออกใบเสร็จรับเงิน (ออกใบกำกับ + รับชำระในก้อนเดียว)

เหมาะกับ event "จ่ายเงินสำเร็จ" — สร้างใบกำกับ (ถ้ายังไม่มี) แล้วรับชำระ ออก ใบเสร็จ (RC) พร้อมลง GL รับเงิน ทั้งหมด atomic · ต้องมี scope receipt:create

Request body

รับ field ชุดเดียวกับ /invoices (customer, lines, vatMode…) บวก field รับชำระ:

Response 201

{
  "taxInvoiceNo": "IV69070001",   // ใบกำกับภาษี
  "receiptNo": "RC69070001",      // ใบเสร็จรับเงิน
  "invoiceId": "cly…",
  "total": 1070,
  "paid": 1070,
  "replayed": false
}

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

ตัวอย่างเต็ม (curl)

# 1) เตรียม body + ลายเซ็น
BODY='{"source":"WideStay","customer":{"name":"บจก. ผู้เช่า","taxId":"0105551234567"},"vatMode":"exclude","lines":[{"description":"ค่าบริการทำความสะอาด","qty":1,"unitPrice":1000,"isService":true}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# 2) ยิง
curl -X POST https://erp.oneable.co.th/api/ext/v1/receipts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Idempotency-Key: pi_abc123" \
  -d "$BODY"

การใช้งานให้ถูกภาษี (โปรดอ่าน)