บันทึกการเปลี่ยนแปลง

ทุกการเปลี่ยนแปลงของ API ที่ผู้เรียกสังเกตเห็นได้ถูกบันทึกไว้ที่นี่ ใหม่สุดอยู่บน ตามรูปแบบ Keep a Changelog ถ้าของที่คุณพึ่งพามีการเปลี่ยน หน้านี้คือหน้าที่จะประกาศ

เวอร์ชันอยู่ในเส้นทาง · วันนี้ทุกเส้นอยู่ใต้ /v1/ และเอกสาร OpenAPI บอกเวอร์ชันของตัวเองที่ info.version — ถ้าอยากตรวจด้วยโปรแกรมว่ากำลังทำงานกับสัญญาฉบับไหน ให้ดึง https://api.scanfood.co/ext/v1/openapi.json

สิ่งที่โผล่มาใน /v1/ เมื่อไหร่ก็ได้:

• เส้นใหม่
• พารามิเตอร์ query ตัวใหม่ที่ไม่บังคับ
• ช่องข้อมูลใหม่ในคำตอบ
• รหัส error ตัวใหม่สำหรับสถานการณ์ที่เดิมตอบด้วยรหัสกว้างกว่า

ทั้งหมดนี้เป็นการ “เพิ่ม” ⇒ ระบบที่ข้ามของที่ไม่รู้จักจะทำงานต่อได้ตามปกติ และนั่นคือสิ่งที่มันเรียกร้องจากฝั่งคุณด้วย — อ่านแบบผ่อนปรน client ที่ตีตกช่องที่ไม่รู้จักจะพังในรุ่นที่ไม่ทำให้ใครพังเลย

สิ่งที่จะไม่มาแบบทับของเดิมใน /v1/: การลบช่อง เปลี่ยนชื่อช่อง ทำให้เส้นรับค่าได้แคบลง หรือเปลี่ยนความหมายของค่าที่ใช้กันอยู่แล้ว เวอร์ชันถูกวางไว้ในเส้นทางก็เพื่อให้สัญญาที่ต่างขนาดนั้นมาในรูปเส้นทางใหม่ ไม่ใช่มาโผล่ใต้ระบบที่วิ่งอยู่

การเปลี่ยนที่ทำให้ของเดิมพังจะถูกแจ้ง ล่วงหน้าอย่างน้อย 30 วัน ผ่านหน้านี้และผ่านผู้ติดต่อ ScanFood ของคุณ ก่อนที่เส้นทางใหม่จะเปิดใช้ · ระหว่างนั้นเส้นทาง /v1/ เดิมจะไม่ถูกแก้ใต้ระบบของคุณ

สิ่งที่พึ่งพาได้:

• การเปลี่ยนที่ทำให้ของเดิมพัง จะไม่ถูกทำทับลงใน /v1/
• อะไรก็ตามที่สังเกตได้และมีการเปลี่ยน จะถูกบันทึกที่นี่พร้อมวันที่
• กุญแจของคุณใช้ได้ข้ามรุ่น — ไม่มีการตรึงเวอร์ชันไว้กับกุญแจ และไม่มีอะไรหมดอายุเอง

เพิ่ม

• categories บนทุกร้านที่ GET /v1/shops คืนมา — หมวดสินค้าของสาขาในรูปรายการแบน { id, name, level, parentId, hidden } · id คือค่าเดียวกับที่อยู่ใน items[].category บนบิล ⇒ แปลงรหัสหมวดบนบิลเป็นชื่อและเส้นทางเต็มได้แล้ว · ส่งทุกหมวด รวมหมวดที่ร้านซ่อน (hidden: true) เพราะบิลเก่ายังอ้างรหัสนั้นได้ · รหัสบนบิลที่ไม่มีในรายการ = หมวดที่ร้านลบไปแล้ว กู้ชื่อคืนไม่ได้ · ดู ร้านค้า

รุ่นนี้ไม่มีการลบ เปลี่ยนชื่อ หรือบีบขอบเขตของอะไรเดิมเลย · รายชื่อหมวดคือข้อมูลแคตตาล็อกอย่างเดียวที่เปิด ส่วนสินค้า เมนู สต็อก ต้นทุน และสูตร ยังไม่ถูกเปิดผ่านเส้นใดเลย

แก้

• rankLevel ของสมาชิกเป็นจำนวนเต็มหรือ null เสมอแล้ว ตรงตามที่เอกสารอ้างอิงประกาศไว้ตั้งแต่ต้น · เดิมส่งค่าตามที่บันทึกไว้ตรง ๆ ⇒ สมาชิกส่วนใหญ่ได้สตริงกลับไป ส่วนมากเป็น "" บางรายเป็นตัวเลขในเครื่องหมายคำพูด เช่น "11" · ตอนนี้ตัวเลขในเครื่องหมายคำพูดมาเป็นตัวเลขนั้น ("11" → 11) · สตริงว่าง หรือค่าที่ไม่ใช่ตำแหน่งระดับที่ใช้ได้ (เช่น "01") มาเป็น null · ถ้าโค้ดของคุณถือว่า "" คือ “ไม่มีระดับ” อยู่แล้ว ก็ทำงานต่อได้ · ถ้าแปลงสตริงเป็นเลขเอง ตอนนี้อ่านเป็นตัวเลขได้เลย
• rank ของสมาชิกเป็นสตริงหรือ null เสมอแล้ว · ข้อมูลสมาชิกเก่าจำนวนหยิบมือเก็บตัวเลขไว้ในช่องนี้ ตอนนี้มาเป็น null

เอกสาร

• items[].category บนบิลถูกเขียนในเอกสารตามที่มันเป็นมาตลอด คือ array ของรหัสหมวด เรียงจากหมวดบนสุดลงไปหมวดย่อยสุด (ส่วนใหญ่มีรหัสเดียว · สินค้าไม่มีหมวด = []) · เดิมเอกสารอ้างอิงและตัวอย่างเขียนว่าเป็นชื่อหมวด · ตัวข้อมูลไม่ได้เปลี่ยน

เพิ่ม

• GET /v1/members/lookup — โทเคนสมาชิกที่อยู่เบื้องหลัง LINE user id ที่คุณถืออยู่แล้ว · ส่ง providerId กับ lineUserId เข้าไป แล้วได้ memberId ของคนนั้นกลับมา ซึ่งเป็นโทเคนตัวเดียวกับที่โผล่บนบิลและในลิสต์สมาชิก ⇒ บอทแชตจึงเดินจาก “มีคนเพิ่งทักเข้ามา” ไปถึงระดับสมาชิก แต้ม และประวัติการซื้อของคนนั้นได้ · การแลกเดินทางเดียว คือส่ง id เข้าไปแล้วได้โทเคนกลับมา และไม่มี response ไหน ส่ง LINE user id กลับออกไป · ดู สมาชิก
• สิทธิ์รายกุญแจสำหรับการค้นนี้ allowLineLookup — ปิดไว้เป็นค่าตั้งต้น และให้สิทธิ์แบบเดียวกับ tel และ email · มันคุมเฉพาะเส้นใหม่เส้นนี้ ไม่ว่าจะเปิดหรือปิด response เดิมทุกเส้นไม่เปลี่ยนอะไรเลย
• 403 lookup_not_enabled — คำตอบเมื่อกุญแจที่ไม่มีสิทธิ์นี้เรียกเส้นค้นสมาชิก

รุ่นนี้ไม่มีการลบ เปลี่ยนชื่อ หรือบีบขอบเขตของอะไรเดิมเลย ⇒ ระบบที่ไม่ได้ใช้เส้นใหม่ ไม่ต้องแก้อะไร

แก้

• บิลซื้อกลับบ้านตอบ channel.code เป็น "take_away" แล้ว · เดิมตอบเป็น "dine_in" และ channel.name ขึ้นเป็นชื่อเรตราคาของร้านแทนชื่อช่องทาง ⇒ ยอดซื้อกลับบ้านถูกนับรวมเป็นยอดทานที่ร้าน · ทานที่ร้าน มารับเอง และช่องทางที่ร้านตั้งเอง ไม่เปลี่ยน · ถ้าคุณเก็บบิลจาก API นี้ไว้แล้ว ยอดซื้อกลับบ้านในนั้นจะอยู่บนแถว dine_in และย้ายได้ด้วยการดึงช่วงวันนั้นใหม่

เพิ่ม

• GET /v1/usage — สถานะโควตาของกุญแจของคุณ อ่านตรงจากตัวนับชุดที่ใช้บังคับจริง ทั้งเพดานต่อนาทีและต่อวันที่กุญแจใบนั้นใช้จริง จำนวนคำขอที่ใช้ไปแล้ววันนี้และที่เหลือ และเจ็ดวันไทยล่าสุด · ไม่รับพารามิเตอร์ และรายงานเฉพาะกุญแจที่เรียกเข้ามาเท่านั้น · ดู ขีดจำกัดการเรียก

เปลี่ยน

• ข้อมูลการใช้งานไม่ได้ถูกเก็บไว้ตลอดไปอีกต่อไป · บันทึกของคำขอรายใบเก็บไว้ 90 วัน ส่วนยอดรวมรายวันที่ /v1/usage อ่าน เก็บไว้ 400 วัน ซึ่งนานพอให้เทียบเดือนนี้ กับเดือนเดียวกันของปีก่อนได้ · เรื่องอื่นของกุญแจและข้อมูลของคุณไม่กระทบ

รุ่นสาธารณะรุ่นแรก

เพิ่ม

• GET /v1/shops — ร้านที่กุญแจใบนั้นเห็นได้ พร้อม shopId, shopName, franchiseId, providerId และ timezone ของร้าน · ไม่แบ่งหน้า
• GET /v1/transactions — บิลของร้านหนึ่ง มี 2 โหมด คือช่วงวันปฏิทิน (from/to ไม่เกิน 31 วันต่อคำขอ) หรือดึงเฉพาะที่เปลี่ยน (updatedSince) · ไล่หน้าด้วย cursor · limit สูงสุด 200 ค่าตั้งต้น 100
• GET /v1/transactions/{id} — บิล 1 ใบแบบเต็ม ทั้งรายการสินค้า ยอดเงิน การชำระ ช่องทางขาย ผู้คิดเงิน และสถานะการยกเลิก
• businessDate บนทุกบิล ควบคู่กับ billDate ⇒ ร้านที่ขายข้ามเที่ยงคืนกระทบยอดตามวันขายของตัวเองได้
• GET /v1/members — สมาชิกของแบรนด์หนึ่ง (providerId) พร้อมแต้ม เครดิต ระดับ คูปอง ป้ายกำกับ และประวัติการมาใช้บริการ · ไล่หน้าด้วย cursor
• GET /v1/members/{memberToken} — สมาชิก 1 คน อ้างด้วย token ทึบที่ได้จากลิสต์
• GET /v1/openapi.json — เอกสาร OpenAPI 3.1 ฉบับเต็ม เปิดสาธารณะ ไม่ต้องยืนยันตัวตน
• กุญแจรูป sf_live_<keyId>_<secret> ส่งผ่าน Authorization: Bearer … แต่ละใบผูกขอบเขตกับร้านเดียวหรือทั้งแฟรนไชส์ และมีป้ายชื่อ เพดานต่อนาที และโควตาวันของตัวเอง
• การคุมอัตราและการรายงานโควตา: X-RateLimit-Limit กับ X-RateLimit-Remaining สำหรับโควตาวัน · Retry-After เมื่อชนเพดานต่อนาที (429) · ตัวนับรายวันที่รีเซ็ต 00:00 น. เวลาไทย
• การเพิกถอนกุญแจ มีผลภายใน 5 นาที หลังจากนั้นกุญแจใบนั้นตอบ 401 key_revoked
• api.scanfood.co เป็นโฮสต์เดียวทั้งของ API และของเอกสารชุดนี้
• เว็บเอกสารชุดนี้ รวมถึง สำเนาที่เครื่องอ่านได้ ของคู่มือทุกหน้า

ข้อจำกัดที่รู้อยู่ ณ 1.0.0

• updatedSince ยังใช้กับ /v1/members ไม่ได้ · จะตอบ 400 not_supported ⇒ สมาชิกต้องซิงก์แบบเต็มโดยไล่ทีละหน้า
• บิลที่ปิดก่อนมีระบบติดตามการเปลี่ยนแปลงไม่มี updatedAt ⇒ ไม่โผล่ในผลของ updatedSince เลย · ให้ดึงย้อนหลังด้วย from/to ให้ครบก่อน
• ไม่มี webhook และไม่มีการ push · ทุกอย่างเป็นการดึงตามรอบของคุณเอง
• ไม่มี sandbox และไม่มีชุดข้อมูลทดสอบ — ดู ข้อมูลทดสอบ
• คำขอข้ามโดเมนถูกปัด · API นี้เป็นแบบเซิร์ฟเวอร์ถึงเซิร์ฟเวอร์เท่านั้น
• สินค้า เมนู สต็อก ต้นทุน และสูตร ไม่ถูกเปิดผ่านเส้นใดเลย (ตั้งแต่ 1.3.0 รายชื่อหมวดของร้านเปิดที่ /v1/shops แล้ว · ที่เหลือยังเป็นแบบเดิม)