การแมปข้อมูลสินค้า Square กับข้อมูลสินค้าของ Receipt Roller

สินค้าที่ลงทะเบียนใน Square Catalog จะถูกแปลงเป็น ข้อมูลสินค้าของ Receipt Roller (ProductDto) โดยอัตโนมัติหลังจากเชื่อมต่อกับเครื่อง POS แล้ว บทความนี้สรุปความสัมพันธ์ของแต่ละฟิลด์ และข้อควรระวังเฉพาะของ Square

โครงสร้างของ Square Catalog

ใน Square Catalog สินค้าจะถูกแสดงเป็น 3 ระดับดังนี้ Receipt Roller จะแมป ITEM เป็นสินค้า 1 รายการ และดึง SKU กับราคาจาก ITEM_VARIATION รายการแรก

• ITEM — ตัวสินค้าเอง（ชื่อสินค้า คำอธิบาย หมวดหมู่）
• ITEM_VARIATION — สินค้าแยกตามขนาด/สี（SKU ราคา）
• CATEGORY — หมวดหมู่（ชื่อหมวดหมู่）

ตารางเทียบฟิลด์

ค่าคงที่ / ค่ากำหนดตายตัว

• TaxRate = 0.10（10% ตามมาตรฐานญี่ปุ่น）ถูกตั้งค่าเป็นค่าเดียวกันทั้งหมด อัตราภาษีแยกตามสินค้ายังไม่ถูกนำเข้าในเวอร์ชันปัจจุบัน
• Status = "Active" สินค้าที่ถูกลบในฝั่ง Square（is_deleted = true）จะไม่อยู่ในขอบเขตการซิงค์

รายการที่ไม่ถูกนำเข้า

ฟิลด์ต่อไปนี้ของ Square Catalog ในเวอร์ชันปัจจุบันยังไม่ถูกนำเข้าในฝั่ง RR

• ITEM_VARIATION รายการที่ 2 เป็นต้นไป — ขนาดหรือสีที่แตกต่างกันของ Square ยังไม่ถูกแมปเข้ากับฟังก์ชันตัวเลือกสินค้าในฝั่ง RR（HasVariants / Variants）มีเพียงรายการแรกเท่านั้นที่ถูกใช้เป็น SKU และราคา
• รูปภาพสินค้า（image_ids）— การดึงข้อมูลผ่าน Square Image API เป็นขั้นตอนแยกต่างหาก จึงยังไม่อยู่ในขอบเขตการซิงค์ในปัจจุบัน
• รายการปรับแต่ง（modifier_list_info）— รายการเพิ่มเติม เช่น ท็อปปิ้งหรือตัวเลือกต่างๆ ยังไม่รองรับ
• ข้อมูลต้นทุน — เนื่องจาก Square ไม่มีฟิลด์มาตรฐานเช่นกัน BaseCostPrice จะยังคงเป็น 0 กรุณาลงทะเบียนแยกต่างหากในฝั่ง RR
• ฟิลด์เฉพาะของ RR（JanCode / Brand / Supplier / ModelNumber ฯลฯ）— เนื่องจากไม่มีแนวคิดที่ตรงกันใน Square จะไม่ถูกเขียนทับเมื่อซิงค์ซ้ำ เนื้อหาที่ลงทะเบียนด้วยตนเองในฝั่ง RR จะยังคงอยู่

จังหวะเวลาในการซิงค์

• Square → RR（การนำเข้าข้อมูลหลักสินค้า）: ทำงานแบบแมนนวลผ่านปุ่ม "ซิงค์จาก Square" ในหน้าจัดการสินค้า ระบบจะดึงข้อมูล ITEM และ CATEGORY ทั้งหมดจาก Square Catalog API（ListCatalog）และจับคู่ด้วย SquareCatalogObjectId เพื่อเพิ่มหรืออัปเดตข้อมูล
• พฤติกรรมเมื่อซิงค์ซ้ำ: สินค้าที่มีอยู่แล้ว（ที่มี SquareCatalogObjectId ตรงกัน）จะถูกเขียนทับในฟิลด์ ProductName / Description / SKU / Category / BasePrice / SquareVariationId ส่วนฟิลด์ที่เพิ่มในฝั่ง RR เช่น JanCode / Brand / BaseCostPrice จะยังคงอยู่ไม่ถูกเขียนทับ
• RR → Square: ยังไม่รองรับในเวอร์ชันปัจจุบัน สินค้าที่ลงทะเบียนในฝั่ง RR จะไม่ถูกส่งกลับไปยัง Square Catalog โดยอัตโนมัติ

การจับคู่ข้อมูลและการลงทะเบียนใหม่

เมื่อนำเข้าสินค้าจาก Square Catalog ระบบจะจับคู่กับสินค้าที่มีอยู่แล้วโดยใช้ SquareCatalogObjectId ที่ตรงกันทั้งหมดเท่านั้น หากไม่ตรงกัน จะถูกเพิ่มเข้า PIM เป็นสินค้าใหม่

ระบบจะไม่จับคู่อัตโนมัติด้วยชื่อสินค้าหรือหมวดหมู่（เนื่องจากอาจมีสินค้าต่างกันที่ใช้ชื่อเดียวกันได้） หากต้องการรวมรายการที่ซ้ำกัน กรุณาดำเนินการด้วยตนเองจากหน้าจัดการสินค้า

ข้อควรระวัง

• หากมีการลบสินค้าออกจริงในฝั่ง Square การจับคู่ด้วย SquareCatalogObjectId ของสินค้านั้นจะใช้งานไม่ได้อีกต่อไป และหากเพิ่มใหม่จะถูกลงทะเบียนเป็นสินค้าคนละรายการ แนะนำให้ใช้ "การปิดใช้งาน" แทนการลบในฝั่ง Square
• หากใช้ขนาดหรือสีที่แตกต่างกันของ Square（หลาย Variation） จะมีการนำเข้าเฉพาะ Variation แรกเท่านั้น หากต้องการลงทะเบียนเป็นสินค้าแยกตามขนาด กรุณาลงทะเบียนเป็น ITEM แยกต่างหากในฝั่ง Square ด้วย
• หากสกุลเงินไม่ใช่ JPY จะถูกแปลงค่าโดยอัตโนมัติ（หน่วยสกุลเงินที่เล็กที่สุด ÷ 100） ไม่แนะนำให้ใช้งานแบบผสมหลายสกุลเงิน
• เมื่อลงทะเบียน BaseCostPrice（ต้นทุน）ในฝั่ง RR จะสะท้อนไปยังการคำนวณกำไรในการวิเคราะห์ยอดขาย เนื่องจาก Square ไม่มีฟิลด์ต้นทุน กรุณากรอกแยกต่างหากในฝั่ง RR

คู่มือที่เกี่ยวข้อง

• ProductDto Reference（สำหรับนักพัฒนา）— ข้อกำหนดฟิลด์ทั้งหมดของโมเดลมาตรฐาน
• การแมปข้อมูลการขายของ Square
• การแมปข้อมูลลูกค้าของ Square
• การตั้งค่าเชื่อมต่อ POS ของ Square