Schedule a call with us HERE
Logo
10 Jul 2023

Loga API Integration Guidelines

สำหรับผู้พัฒนาระบบ POS, E-commerce หรือระบบสารสนเทศใดๆ ที่สนใจเชื่อมต่อระบบกับ Loga เราขอแนะแนวทางเพื่ออำนวยความสะดวกให้สักเล็กน้อย

สิ่งที่ต้องเตรียมก่อนเริ่มใช้งาน Loga API

  1. สร้างบัญชี Loga account บน Loga Merchant website
  2. สมัครเป็นร้านค้าบน Loga ตามขั้นตอนบนเว็บไซต์
  3. สร้างบัตรสมาชิกบน Loga ตามขั้นตอนบนเว็บไซต์
  4. เปิดใช้ฟีเจอร์ที่ต้องการใช้บน Loga

เมื่อสร้างบัตรสมาชิกผ่านเว็บไซต์เรียบร้อยแล้ว ก็จะมีข้อมูลเพียงพอให้เชื่อมต่อระบบผ่าน API ได้แล้ว โดยใช้

  • username – ชื่อผู้ใช้ โดยมากจะตรงกับอีเมลที่ใช้สมัครบัญชี
  • password – รหัสผ่าน ซึ่งผู้สมัครตั้งเองในขั้นตอนการสร้างบัญชี
  • card_id – เลขที่บัตร สามารถทราบผ่านหน้าเว็บ แถบ Manage/จัดการ ในส่วน Card Info

หมายเหตุ สำหรับการเริ่มใช้จริงกับร้านค้า (ผู้ใช้บริการ POS หรือ E-commerce ของท่าน) รบกวนให้ร้านค้านั้นๆ สมัครบริการ Loga และสร้างบัตรสมาชิก แล้วจึงนำ username password และ Card ID ของร้านค้านั้นๆ มาใช้เชื่อมต่อแทนนะคะ


Use case scenario (ตัวอย่างสถานการณ์การใช้งาน)

  1. ร้านเปิด พนักงานเปิดเครื่อง POS เพื่อเริ่มใช้งาน >> เรียก Loga API > Service Login
  2. ลูกค้าเข้าร้าน หยิบของมาชำระเงินที่ POS
  3. พนักงานขอเบอร์โทรสมาชิก สำหรับสะสมแต้ม
  4. พนักงานคีย์เบอร์โทรลูกค้าเข้า POS >> เรียก Loga API > Service Get customer info
  5. เมื่อชำระเงินเรียบร้อย POS ออกใบเสร็จ >> เรียก Loga API > Service Add customer points

หมายเหตุ ตัวอย่างข้างต้นเป็นเพียงขั้นตอนอย่างง่ายเพื่อให้เห็นภาพเท่านั้น แท้จริงแล้วนักพัฒนา POS สามารถออกแบบวิธีการใช้งาน และเลือกใช้ Service ที่เหมาะสมกับการใช้งานของผู้ใช้ของท่านได้อีกหลายลักษณะ เช่น

  • พิมพ์ QR Code ลงบนใบเสร็จรับเงินให้ลูกค้าสแกนรับแต้มเอง ลดขั้นตอนการขอเบอร์โทรศัพท์ลูกค้า สำหรับร้านค้าที่ Traffic สูง
  • เชื่อมรายการโปรโมชันของ POS กับ คูปอง หรือของรางวัลของ Loga ให้ผู้ใช้กดเลือกใช้ได้เลย ไม่จำเป็นต้องคีย์ รหัสคูปอง/รหัสรางวัล
  • คำนวนคะแนนสะสมเองตามประเภทสินค้า และส่งให้ Loga เลย
  • ไม่คำนวณคะแนนสะสม เลือกใช้สูตรการคำนวณแต้มที่ร้าน setup ไว้บนระบบ Loga
  • ปรับระดับสมาชิกเป็น VIP ให้ เมื่อลูกค้าจ่ายบิลเกินหนึ่งหมื่นบาท (โดยทั่วไปร้านค้ามัก setup ให้ปรับระดับสมาชิกตามคะแนนสะสมได้อัตโนมัติ แต่เราก็รองรับให้ปรับได้อิสระได้เช่นกัน)

เป็นต้น


Log in

เข้าสู่ระบบ เพื่อให้ได้ Token มาใช้ใน service ใดๆ ที่ต้องการตรวจสอบสิทธิ์

URL https://loga.app/api/main/login

Parameter

  • user – ชื่อผู้ใช้ หรือโดยมากจะเป็นอีเมลที่ใช้สมัครบัญชีผู้ใช้
  • pass – รหัสผ่าน ที่ผู้ใช้ตั้งเองในขั้นตอนการสมัคร ที่ผ่านการ hash MD5 แล้ว
  • uuid – ชื่อเครื่อง หรือรหัสอุปกรณ์ของท่าน ซึ่งแท้จริงแล้วจะเป็น String อะไรก็ได้ที่ไม่หายไป เมื่อใช้สร้าง Token แล้วจะต้องใช้ควบคู่กับ Token นี้ตลอดไป

Response (JSON Format)

หาก user/password ถูกต้อง จะได้ code 200 และสิ่งที่ต้องนำไปใช้ต่อคือ data.token

หมายเหตุ token ที่ถูกสร้างขึ้นจะไม่มีวันหมดอายุ แต่จะไม่สามารถใช้ได้หลังจากที่ Log out หรือมีการเปลี่ยนรหัสผ่าน ผ่านเว็บไซต์


Get Card detail

เพื่อดูข้อมูลต่างๆ ของบัตรสมาชิก เช่น ชื่อบัตร ระดับสมาชิก สูตรในการคำนวณแต้ม รายการรางวัล รายการเครดิต เป็นต้น

URL https://loga.app/api/main/get_card_detail

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น

Response (JSON Format)

ข้อมูลต่างๆ ของบัตรสมาชิก ซึ่งข้อมูลส่วนใหญ่หากไม่มีการปรับแต่งใดๆ ผ่านเว็บไซต์ค่าก็จะคงเดิม ไม่จำเป็นต้องเรียกบ่อยๆ


Get Customer info

เพื่อดูข้อมูลของสมาชิกหนึ่งๆ

URL https://loga.app/api/main/get_customer_info

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • [สำหรับ Applicatio/LINE member] cuid – รหัสสมาชิก ได้มาจากหน้าจอแอปพลิเคชันของลูกค้า หรือ scan QR code บนหน้าจอ หรือ เบอร์โทรศัพท์ลูกค้า
  • [สำหรับ Offline member] plastic_ident – รหัสบัตรพลาสติก ได้มาจาก scan Barcoode หรือ NFC หรือ แถบแม่เหล็ก บนบัตรพลาสติก

Response (JSON Format)

ข้อมูลต่างๆ ของสมาชิก เช่น ชื่อ นามสกุล วันเกิด ระดับสมาชิก แต้มสะสม เครดิตสะสม เป็นต้น และหากท่านไม่ทราบ รหัสสมาชิก เรียก service นี้ด้วยเบอร์โทรศัพท์ สิ่งสำคัญที่ต้องโฟกัสคือ

  • data.card.uid คือรหัสสมาชิก สำหรับสมาชิกออนไลน์
  • data.card.pcard_id คือรหัสสมาชิก สำหรับสมาชิกออฟไลน์

หมายเหตุ สมาชิกบางคนอาจมีทั้ง uid และ pcard_id เกิดจากการปรับสภาพสมาชิกจากบัตรพลาสติก เป็นสมาชิกออนไลน์ ท่านสามารถใช้เพียง uid โดยไม่สนใจ pcard_id ได้โดยไม่ส่งผลกระทบอันใด


Create and subscription new plastic card

กรณีที่ทางร้านต้องการสมัครสมาชิกให้ลูกค้า แทนการให้ลูกค้าสมัครเองผ่าน Application/LINE โดยหากทางร้านมิได้มีบัตรพลาสติก (ที่มี barcode, NFC, แถบแม่เหล็ก) ทางร้านสามารถใช้เพียงเบอร์โทรศัพท์ลูกค้าแทนรหัสบัตรพลาสติกได้

URL https://loga.app/api/main/subscribe_by_unregistered_card

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • serial – NFC serial หรือรหัสแถบแม่เหล็ก หากไม่มีสามารถใช้เบอร์โทรศัพท์ลูกค้าแทนได้
  • barcode – Barcode หากไม่มีสามารถใช้เบอร์โทรศัพท์ลูกค้าแทนได้
  • mobile – เบอร์โทรศัพท์ลูกค้า
  • fname – ชื่อลูกค้า

Response (JSON Format)

ผลการสร้างบัตรสมาชิก (สำเร็จหรือไม่) และสิ่งที่ท่านต้องสนใจเป็นพิเศษคือ data.pcard_id เพื่อใช้ใน service ต่อๆ ไป เช่นให้แต้ม

หมายเหตุ Loga ไม่อนุญาตให้สร้างบัตรสมาชิกจากเบอร์โทรศัพท์ที่มีอยู่ในระบบอยู่ก่อนแล้ว (ทั้งออนไลน์ และออฟไลน์) และจะมีประสิทธิภาพมากกว่า หากทาง POS จะใช้เบอร์โทรศัพท์ที่ลูกค้าให้มา Get Customer info ก่อน เมื่อพบกว่าไม่มีสมาชิกจึงค่อยสร้างบัตรสมาชิกให้ แม้ลูกค้าจะยืนยันว่าไม่เคยมีสมาชิกก็ตาม


Add customer points

สำหรับให้แต้มสะสมแก่ลูกค้า

URL https://loga.app/api/points/add_customer_point

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • [สำหรับ Applicatio/LINE member] cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • [สำหรับ Offline member] pcard_id – รหัสบัตรพลาสติก (data.card.pcard_id จาก Service Get Customer info)
  • [กรณีทาง POS คำนวณแต้มเอง] point – จำนวนแต้มที่ลูกค้าได้รับ
  • [กรณีใช้ Loga คำนวณแต้มให้] formula_id – รหัสสูตร สามารถเลือกจากรายการที่ตั้งค่าไว้ (data.point_product.add[0].formula_id จาก Service Get Card detail)
  • cost – ยอดใช้จ่าย หากมิได้กำหนด point มา ระบบจะใช้ยอดใช้จ่ายคำนวณแต้มโดยใช้สูตรที่เลือก หากกำหนด point มายอดใช้จ่ายจะเก็บเป็นข้อมูลประกอบเท่านั้น
  • remark – หมายเหตุใดๆ (ลูกค้าจะเห็นข้อความนี้)
  • [Optional] reference – เลขที่ใบเสร็จ หรือหมายเลขใดๆ ที่จะ unique สำหรับคำสั่งซื้อนี้ หากมี request ที่ reference ซ้ำกันระบบจะเห็นเป็นรายการเดิม ไม่บันทึกซ้ำ
  • [Optional] replace_duplicate – ส่งค่า yes หากต้องการบันทึกทับรายการเดิม (อ้างอิงจาก reference) ใช้สำหรับแก้ไขรายการที่เคยส่งไปแล้ว

Response (JSON Format)

ผลการให้แต้มสมาชิก แต้มสะสมในปัจจุบัน และประวัติรายการแต้มที่พึ่งเกิดขึ้นไม่นาน

หมายเหตุ คำอธิบาย parameter ด้านบนเป็นไปตามจุดประสงค์เริ่มต้น แต่ก็มีทางลัดเล็กน้อย เพื่อความสะดวกในการใช้งาน เช่น สำหรับ pcard_id 1234 สามารถส่งค่า “P1234” ในช่อง cuid แทนการส่ง pcard_id ได้, หากส่งค่า point และ formular_id โดยไม่ส่ง cost ระบบจะเข้าใจว่า point คือ cost และคำนวณแต้มให้ เป็นต้น


Use customer points

สำหรับให้แต้มสะสมแก่ลูกค้า

URL https://loga.app/api/points/use_customer_point

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • [สำหรับ Applicatio/LINE member] cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • [สำหรับ Offline member] pcard_id – รหัสบัตรพลาสติก (data.card.pcard_id จาก Service Get Customer info)
  • point – จำนวนแต้มที่ลูกค้าได้รับ (ไม่จำเป็นต้องกรอก หากำหนดรหัสของรางวัล)
  • [Optional] pp_id – รหัสของรางวัล โดยท่านอาจผูกรหัสไว้กับ promotion บน POS หรือให้พนักงานคีย์ผ่านหน้าจอ (data.point_product.use[0].id จาก Service Get Card detail)
  • remark – หมายเหตุใดๆ (ลูกค้าจะเห็นข้อความนี้)
  • [Optional] reference – เลขที่ใบเสร็จ หรือหมายเลขใดๆ ที่จะ unique สำหรับคำสั่งซื้อนี้ หากมี request ที่ reference ซ้ำกันระบบจะเห็นเป็นรายการเดิม ไม่บันทึกซ้ำ
  • [Optional] replace_duplicate – ส่งค่า yes หากต้องการบันทึกทับรายการเดิม (อ้างอิงจาก reference) ใช้สำหรับแก้ไขรายการที่เคยส่งไปแล้ว

Response (JSON Format)

ผลการใช้แต้มสมาชิก แต้มสะสมในปัจจุบัน และประวัติรายการแต้มที่พึ่งเกิดขึ้นไม่นาน

หมายเหตุ สมาชิกจำเป็นต้องมีแต้มสะสมมากกว่า แต้มที่ท่านต้องการจะตัด จะมีประสิทธิภาพมากกว่า หากทาง POS ตรวจสอบคะแนนสะสมในปัจจุบันจาก service Get Customer info และแสดงบนหน้าจอให้พนักงานทราบ ก่อนจะพยายามใช้แต้มสมาชิก


Get customer coupons

สำหรับดูคูปองที่สมาชิกมี

URL https://loga.app/api/coupon/get_customer_coupons

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)

Response (JSON Format)

รายการคูปองของสมาชิกที่ระบุ

หมายเหตุ สำหรับบัตรพลาสติก สามารถส่ง P ตามด้วย pcard_id ในค่าของ cuid ได้


Coupon QR Code

สำหรับกรณี ไม่ผ่านขั้นตอนการขอเบอร์สมาชิก และเลือกใช้เป็น Flow ให้ลูกค้าแสดง Coupon QR Code เพื่อให้ POS สแกนแล้วตัดใช้คูปอง

รูปแบบของ QR Code คือ cp:CUID:UUID:CardID:coupon_id:FeedID

กล่าวคือหลังจาก scan QR Code แล้วทาง POS ต้อง sprit string ด้วยเครื่องหมาย : และนำ cuid จากตำแหน่งที่ 2 และ coupon_id จากตำแหน่งที่ 5 มาใช้เรียก service Use Customer coupon ในลำดับถัดไป


Use customer coupon

สำหรับใช้คูปองของสมาชิกที่ระบุ

URL https://loga.app/api/coupon/force_use_coupon

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • coupon_id – รหัสคูปอง (data[0].coupon_id จาก Service Get Customer coupons)

Response (JSON Format)

ผลการใช้คูปอง

หมายเหตุ สำหรับบัตรพลาสติก สามารถส่ง P ตามด้วย pcard_id ในค่าของ cuid ได้ และจะมีประสิทธิภาพมากกว่า หากทาง POS ตรวจสอบคูปองที่สมาชิกมีอยู่ผ่าน Service Get Customer coupons ก่อน และให้พนักงานเลือกคูปองที่จะใช้ผ่านหน้าจอ


Return used coupon (void)

สำหรับคืนคูปองกลับคืนให้สมาชิก หรือยกเลิกการใช้

URL https://loga.app/api/coupon/return_used_coupon

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • feed_id – รหัสคูปอง (data[0].feed_id จาก Service Use Customer coupon)

Response (JSON Format)

ผลการคืนคูปอง

หมายเหตุ หากต้องการ support การคืน (void) ในขั้นตอนการใช้คูปองควรเก็บ feed_id เอาไว้ด้วย


Add customer credit

สำหรับให้เครดิตกับสมาชิกที่ระบุ เครดิต (Loga Credits) คืออะไร

URL https://loga.app/api/credits/add_customer_credits

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • cdid – รหัสเครดิต (data.credits[].cdid จาก Service Get Card detail) หลังจากสร้างเครดิตผ่านหน้าเว็บแล้ว หากไม่มีการแก้ไขใดๆ สามารถใช้รหัสเดิมได้ตลอด ไม่จำเป้นต้อง Get Card detail บ่อยๆ
  • amount – จำนวนเครดิตที่ต้องการให้
  • remark – หมายเหตุใดๆ (ลูกค้าเห็นข้อความนี้)

Response (JSON Format)

ผลการให้เครดิต และเครดิตคงเหลือ


Use customer credit

สำหรับใช้เครดิตของสมาชิกที่ระบุ เครดิต (Loga Credits) คืออะไร

URL https://loga.app/api/credits/use_customer_credits

Parameter

  • token – token ที่ได้รับจากการ login
  • uuid – ชื่อเครื่องที่ใช้ขอ token ในการ login
  • card_id – เลขที่บัตร ได้จากหน้าเว็บไซต์ Loga Merchant หลังจากสร้างบัตรสมาชิก ตามที่กล่าวไว้ข้างต้น
  • cuid – รหัสลูกค้า (data.card.uid จาก Service Get Customer info)
  • cdid – รหัสเครดิต (data.credits[].cdid จาก Service Get Card detail) หลังจากสร้างเครดิตผ่านหน้าเว็บแล้ว หากไม่มีการแก้ไขใดๆ สามารถใช้รหัสเดิมได้ตลอด ไม่จำเป้นต้อง Get Card detail บ่อยๆ
  • amount – จำนวนเครดิตที่ต้องการใช้
  • remark – หมายเหตุใดๆ (ลูกค้าเห็นข้อความนี้)

Response (JSON Format)

ผลการใช้เครดิต และเครดิตคงเหลือ

หมายเหตุ จะมีประสิทธิภาพมากกว่า หากตรวจสอบเครดิตคงเหลือจาก Get customer info และแสดงให้พนักงานเห็นในหน้าจอ ก่อนทำการตัดเครดิตสมาชิก


Post by Loga Dev

0 Comments