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

Square ลูกค้า Customer Directory การเชื่อมต่อ POS การแมปข้อมูล

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

สำหรับกลไกการซิงค์ข้อมูลสมาชิกแบบสองทิศทาง（จังหวะเวลา ลำดับความสำคัญเมื่อเกิดข้อขัดแย้ง การแก้ปัญหา）ดูได้ที่ การซิงค์ข้อมูลสมาชิกแบบสองทิศทางกับ Smaregi / Square บทความนี้เป็นเอกสารทางเทคนิคที่มุ่งเน้นเฉพาะ "ฟิลด์ใดตรงกับฟิลด์ใด" เท่านั้น

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

Square Customer Directory Receipt Roller (CrmCustomerDto) หมายเหตุ
id—（บันทึกใน PosCustomerLink）ID ภายในของ Square ฝั่ง RR จะไม่บันทึกลงใน Customer โดยตรง แต่จะเก็บไว้ใน vendorIdentifier ของตารางลิงก์ PosCustomerLinkEntity
reference_idMembershipCodeID ที่ผู้ประกอบการร้านค้าสามารถใช้ได้อย่างอิสระ ใช้เป็นหมายเลขสมาชิกของ RR โดยตรง หากยังไม่ได้ตั้งค่า ระบบจะออกหมายเลขอัตโนมัติในฝั่ง RR
family_nameLastNameคัดลอกตามเดิม
given_nameFirstNameคัดลอกตามเดิม
email_addressEmailปรับให้เป็นตัวพิมพ์เล็กและตัดช่องว่างหน้า-หลังออกเพื่อทำให้เป็นมาตรฐาน
phone_numberPhoneปรับให้เป็นรูปแบบ E.164（เนื่องจาก Square บันทึกในรูปแบบ E.164 อยู่แล้ว จึงมักไม่จำเป็นต้องแปลงในกรณีส่วนใหญ่）
birthdayDateOfBirthSquare เป็นรูปแบบ YYYY-MM-DD ฝั่ง RR บันทึกเป็นวันที่เวลา UTC
address.postal_codePostalCodeยัติภังค์ยังคงอยู่ตามเดิม
address.administrative_district_level_1Prefectureจังหวัด（ระดับ 1 ของเขตปกครอง）
address.localityCityเขต/อำเภอ/ตำบล
address.address_line_1Address1ชื่อถนน/บ้านเลขที่
address.address_line_2Address2ชื่ออาคาร/เลขที่ห้อง
noteNotesบันทึกอิสระสำหรับพนักงานร้านค้า

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

  • คำอ่านชื่อ-นามสกุล (คะนะ)（LastNameKana / FirstNameKana）— เป็นค่าว่าง เนื่องจาก Square ไม่มีฟิลด์คะนะ
  • เพศ（Gender）— ไม่มีรายการมาตรฐานใน Square Customer Directory
  • กลุ่มในฝั่ง Square（group_ids）— ฟังก์ชันกลุ่มของ Square มีระดับความละเอียดแตกต่างจาก MembershipLevel หรือ Tags ของ RR จึงยังไม่ถูกนำเข้าในเวอร์ชันปัจจุบัน
  • เซกเมนต์ในฝั่ง Square（segment_ids）— เนื่องจากเป็นเซกเมนต์แบบไดนามิกที่คำนวณอัตโนมัติ ความหมายในการถ่ายโอนไปยังฝั่ง RR จึงค่อนข้างต่ำ และยังไม่รองรับ

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

เมื่อมีข้อมูลลูกค้าใหม่จาก Square เข้ามา ระบบจะทำการตรวจสอบว่าเป็นบุคคลเดียวกันกับลูกค้าที่มีอยู่แล้วในฝั่ง RR หรือไม่ ตามลำดับดังนี้

  1. MembershipCode（ตรงกับ reference_id ของ Square ทุกตัวอักษร）
  2. Email（ตรงกันทุกตัวอักษรหลังปรับเป็นตัวพิมพ์เล็กและตัดช่องว่างหน้า-หลัง）
  3. Phone（ตรงกันทุกตัวอักษรหลังปรับเป็นรูปแบบ E.164）

หากไม่ตรงกับเงื่อนไขใดเลย จะถูกเพิ่มเข้า CRM เป็นลูกค้าใหม่ หากตรงกัน ข้อมูลลูกค้าที่มีอยู่แล้วจะถูกอัปเดต（ใช้หลัก last-write-wins แยกตามฟิลด์）

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

  • การลงทะเบียน/อัปเดตสมาชิก（Square → RR）: สะท้อนเข้า CRM ภายในไม่กี่วินาทีผ่าน Square Webhook（customer.created / customer.updated）
  • การสำรองข้อมูลตามกำหนดเวลา: เพื่อรองรับกรณีที่ Webhook ไม่มาถึง ระบบจะดึงข้อมูลส่วนต่างผ่าน API SearchCustomers ทุกๆ 1 ชั่วโมง
  • RR → Square: ทันทีที่ลูกค้าลงทะเบียนสมาชิกหรืออัปเดตข้อมูลผ่านแอป การเรียกใช้ CreateCustomer / UpdateCustomer ของ Square จะถูกเพิ่มเข้าคิว โดยปกติจะสะท้อนภายในไม่กี่วินาทีถึงไม่กี่นาที

ข้อควรระวัง

  • หากมีการลบลูกค้าออกจริงในฝั่ง Square การจับคู่ในฝั่ง RR จะใช้งานไม่ได้อีกต่อไป กรุณาดำเนินการลบจากแดชบอร์ดของ Square ด้วยความระมัดระวัง
  • หากพนักงานเขียนทับ reference_id ของ Square ด้วยตนเอง การจับคู่ MembershipCode ในฝั่ง RR จะขาดหาย แนะนำให้ใช้งานโดยไม่เปลี่ยนแปลงฟิลด์ที่ใช้เป็นหมายเลขสมาชิกหลังจากลงทะเบียนแล้ว
  • address ของ Square เป็นฟิลด์ที่มีโครงสร้าง แต่มักพบกรณีที่พนักงานร้านค้าใส่ทุกอย่างลงใน address_line_1 โดยไม่แยก "บ้านเลขที่/ถนน" กับ "ชื่ออาคาร" ในกรณีนั้น Address2 จะว่างเปล่า
  • หากต้องการนำกลุ่มหรือเซกเมนต์ของ Square มาใช้เป็นแท็กของ RR กรุณาปรึกษาทีมพัฒนา

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

เผยแพร่เมื่อ: 2569-05-29 อัปเดตเมื่อ: 2569-07-03
กลับไปที่รายการช่วยเหลือ
บทความที่เกี่ยวข้อง