โครงสร้างข้อมูลและรหัสอ้างอิง

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

franchiseId ─┬─ shopId ─┬─ รหัสบิล ──── items[]
             │          │
             │          ├─ deviceId · stationId       (มีบนทุกบิล)
             │          │
             │          └─ providerId ─── memberId (m1_…) ─── coupons[]
             │                                  ▲
             └─ … สาขาอื่น                      │
                        บิลที่ผูกสมาชิก ────────┘  (transaction.memberId คือค่าเดียวกัน)

• GET /v1/shops คือจุดเริ่มต้นเสมอ เพราะมันคืน shopId franchiseId และ providerId ของทุกสาขาที่กุญแจอ่านได้ ไม่มีเส้นอื่นที่ต้องอธิบายความสัมพันธ์นี้อีก
• franchiseId กับ providerId เป็นคนละแกน ทั้งคู่บันทึกอยู่บนตัวร้าน ตัวหนึ่งคือโครงสร้างธุรกิจ อีกตัวคือฐานข้อมูลสมาชิก หลายสาขาใช้แบรนด์สมาชิกร่วมกันได้โดยไม่ต้องอยู่แฟรนไชส์เดียวกัน จึงห้ามอนุมานตัวหนึ่งจากอีกตัวหนึ่ง
• บิลหนึ่งใบเป็นของร้านเดียวเท่านั้น และพก franchiseId deviceId stationId มาด้วย คุณจึงรวมยอดข้ามสาขาหรือแยกตามเครื่องได้โดยไม่ต้องยิงคำขอที่สอง
• สมาชิกเป็นของแบรนด์ ไม่ใช่ของสาขา ข้อมูลสมาชิกกำหนดขอบเขตด้วย providerId และไม่มีช่องร้านอยู่บนตัวสมาชิก

ทุกตัวข้างบนเป็นค่าทึบ ให้ปฏิบัติกับมันเป็นสตริง เก็บความยาวและตัวพิมพ์ไว้ให้ตรงเป๊ะ อย่าสร้างขึ้นเอง และอย่าตีความหมายจากตัวอักษรข้างใน

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

• เสถียร สมาชิกคนเดิมได้ token เดิมเสมอ จึงเก็บเป็นคีย์อ้างอิง ใช้เป็นคีย์ของรายการ หรือใช้จับคู่กับบิลได้อย่างปลอดภัย
• เหมือนกันทั้งระบบ token ไม่เปลี่ยนตามกุญแจหรือตามสาขา สองร้านในแฟรนไชส์เดียวกันจึงเห็นค่าเดียวกันสำหรับคนคนเดียวกัน
• ย้อนกลับไม่ได้ แปลงกลับเป็นตัวตนจริงจากนอก ScanFood ไม่ได้
• บอกรุ่นด้วยคำนำหน้า วันนี้ทุก token ขึ้นต้นด้วย m1_ ถ้าวันหลังมีการหมุนกุญแจเข้ารหัส จะกลายเป็น m2_ ให้ตรวจที่คำนำหน้า อย่ายึดความยาวตายตัว

คุณหยิบ memberId จากบิลไปเรียก GET /v1/members/{memberToken} ได้เลย ไม่ต้องมีตารางแปลง ถ้าสมาชิกคนนั้นอยู่ในแบรนด์ที่กุญแจของคุณอ่านไม่ได้ คำตอบคือ 404

ยังมีอีกทางหนึ่งที่จะได้ token มา ถ้าคุณมี LINE user id ของลูกค้าอยู่แล้ว จากบอทหรือ LIFF ของคุณเอง GET /v1/members/lookup จะแลกมันเป็น memberId ของคนนั้นให้ เฉพาะกุญแจที่เปิดสิทธิ์การค้นนี้ไว้ การแลกเดินทางเดียวคือส่ง id เข้าไปแล้วได้ token กลับมา และไม่มี response ไหนส่ง LINE user id กลับออกไป ดูรายละเอียดที่ สมาชิก

จำนวนเงินทุกช่องเป็น เงินบาท ในรูปตัวเลขธรรมดา ไม่มีช่องบอกสกุลเงิน ไม่ใช่หน่วยย่อย และไม่ใช่สตริง

ยอดระดับบิลอยู่ใน amounts และมีสี่กติกา

• amounts.net คือยอดที่ลูกค้าจ่ายจริง รวมทิปแล้ว ถ้าจะเรียกว่ายอดขายของร้าน ต้องหัก amounts.tip ออกก่อน เพราะทิปเป็นของพนักงาน
• null ไม่เท่ากับ 0 null แปลว่า “ไม่เกี่ยวกับบิลนี้” คือร้านปิดฟีเจอร์นั้น หรือไม่เคยมีการเขียนค่าลงไป ส่วน 0 แปลว่าเปิดใช้อยู่และค่าเป็นศูนย์พอดี อย่ารวมสองอย่างนี้เข้าด้วยกันตอนคิดยอด
• amounts.vatType บอกว่า VAT อยู่ในราคาอย่างไร "Include" คือราคารวม VAT แล้ว และถอด VAT ออกจากยอด ส่วน "Exclude" คือบวก VAT ท้ายบิล อ่านค่านี้ก่อนคำนวณตัวเลขภาษีใหม่เสมอ
• ส่วนลดบันทึกที่ระดับบิล ไม่ได้กระจายลงรายบรรทัด amounts.discount คือส่วนลดที่แคชเชียร์กดเอง amounts.campaign และ amounts.coupon คือรายการโปรโมชันและคูปองที่ใช้ ส่วน amounts.discountTotal คือยอดที่ลดจริง รายการสินค้าไม่มีช่องส่วนลดต่อบรรทัด ถ้าต้องการยอดสุทธิรายบรรทัด ต้องเฉลี่ยเอง

รายการสินค้าแต่ละบรรทัดมี qty unitPrice (ราคาที่คิดจริง) lineTotal ตัวเลือกที่ลูกค้าเลือก รหัสหมวดสินค้า ณ เวลาที่ขาย และธง cancelled vat isTip ทิปที่ถูกกดเป็นรายการหนึ่งบรรทัดจะมี isTip: true ให้ตัดบรรทัดเหล่านั้นออกจากการวิเคราะห์สินค้า

payments[] แยกการรับเงินตามช่องทาง เพราะบิลใบเดียวแบ่งจ่ายหลายช่องทางได้ ยอดในนั้นมากกว่า net ได้ เมื่อลูกค้าจ่ายเงินสดแล้วรับเงินทอน

channel บอกว่าออเดอร์นั้นมาถึงครัวได้อย่างไร

บางอย่างไม่ถูกส่งออกโดยเจตนา และบางอย่างส่งออกแต่ไม่เสถียร

ไม่ส่งออกเลย โดยนโยบาย

• ต้นทุนและสูตรอาหาร ต้นทุนต่อหน่วย สูตรวัตถุดิบ และการตัดสต็อก อยู่ใน ScanFood เท่านั้น
• ตัวตนของลูกค้าบนบิล ชื่อ เบอร์โทร ที่อยู่ โน้ตท้ายบิล และสลิปที่อัปโหลด ไม่ได้เป็นส่วนหนึ่งของบิลที่ส่งออก
• ตัวตนของสมาชิก ชื่อ วันเกิด เพศ รูปภาพ ประวัติแต้มดิบ และประวัติการมาใช้บริการ ไม่ถูกส่งออกเลย สิ่งที่ได้คือค่าจริงเท็จ hasTel hasEmail hasLine ส่วนเบอร์โทรและอีเมลตัวจริงจะเปิดให้เฉพาะกุญแจที่ได้รับอนุมัติไว้แล้วเท่านั้น
• ช่องที่ใช้ภายใน การอ้างอิงกะและผู้จัดการ การอ้างอิงเกตเวย์รับเงิน และสถานะระบบบัญชี

ส่งออก แต่อย่าเอาไปเขียนเป็นเงื่อนไข

• ข้อความ message ในข้อผิดพลาด ให้แตกสาขาที่รหัส error แทน
• จำนวนช่องข้อมูลในออบเจกต์ ภายใน /v1/ มีการเพิ่มช่องได้ ให้มองข้ามสิ่งที่ยังไม่รู้จัก
• channel.name tableName และ cashier ทั้งหมดนี้คือสิ่งที่พนักงานพิมพ์เอง และพนักงานเปลี่ยนชื่อกันเป็นเรื่องปกติ ให้จับคู่ด้วยรหัส แล้วใช้ชื่อไว้แสดงผล
• rankLevel มีความหมายเฉพาะเมื่อแบรนด์นั้นเปิดการเลื่อนระดับอัตโนมัติ ถ้าจะแสดงผลให้ใช้ rankName
• businessDate เป็น null ได้ในบิลที่ไม่ได้ปิดผ่านเส้นทาง POS ปัจจุบัน ดู เขตเวลาและวันธุรกิจ