คู่มือ / อ⁠อ⁠เ⁠ด⁠อ⁠ร์และการเชื่อมต่อ

สำหรับผู้พัฒนาเ⁠ว็⁠บ⁠ไ⁠ซ⁠ต์

API สาธารณะทำอะไรได้ คี⁠ย์ทำงานอย่างไร ทำไมอ⁠อ⁠เ⁠ด⁠อ⁠ร์ซ้ำกันไม่ได้ และขอสเปกฉบับเต็มได้อย่างไร

หน้านี้สำหรับคนที่ทำหน้าร้านออนไลน์ ที่นี่มีแนวทางและกฎ ส่วน สเปกฉบับเต็มพร้อมที่อยู่ของเมธอด ฟิลด์ และตัวอย่าง จะให้พร้อมกับคี⁠ย์ เมื่อร้านหรือผู้พัฒนาของร้านขอมา

ทำไมไม่เผยแพร่สเปกบนเ⁠ว็⁠บ⁠ไ⁠ซ⁠ต์

คำอธิบายเมธอดที่วางไว้บนเ⁠ว็⁠บ⁠ไ⁠ซ⁠ต์ ช่วยคนที่ตามหาการเชื่อมต่อของคนอื่นมากกว่าช่วยผู้พัฒนา ผู้พัฒนาต้องการแค่ครั้งเดียวและได้รับภายในไม่กี่นาที ส่วนบอตค้นหาไม่มีเหตุให้ต้องได้ เขียนมาหาเรา แล้วจะได้คำอธิบายภายในวันเดียวกัน

การยืนยันตัวตน

เข้าใช้ด้วย คี⁠ย์เชื่อมต่อ คี⁠ย์เป็นของร้านเดียว: ข้อมูลของร้านอื่นเข้าถึงผ่านคี⁠ย์นี้ไม่ได้ เพราะโครงสร้างของระบบ ไม่ใช่เพราะ «มีการตรวจในโค้ด»

  • ร้านออกคี⁠ย์ในหลังบ้าน และคี⁠ย์แสดงครั้งเดียว
  • ส่วนลับเราเก็บเป็น แฮช — กู้คืนไม่ได้ ทำได้แค่ออกคี⁠ย์ใหม่
  • เพิกถอนได้ทันที: คี⁠ย์ที่เพิกถอนแล้วใช้ไม่ได้ตั้งแต่คำขอถัดไป
  • คี⁠ย์อยู่ บนเซิร์ฟเวอร์ของหน้าร้าน ไม่ควรอยู่ในเบราว์เซอร์ของลูกค้า ในแ⁠อ⁠ปมือถือ หรือในรีโพซิทอรี
คี⁠ย์รั่ว = อ⁠อ⁠เ⁠ด⁠อ⁠ร์แปลกปลอมในแ⁠ค⁠ช⁠เ⁠ชี⁠ย⁠ร์ของคุณ

ถ้าคี⁠ย์หลุดไปในแชทกลุ่ม ในรีโพซิทอรีสาธารณะ หรือในโค้ดฝั่งลูกค้า — เพิกถอนแล้วออกคี⁠ย์ใหม่ กดปุ่มเดียว และถูกกว่าผลที่ตามมาทุกอย่าง

การเชื่อมต่อทำอะไรได้

ความสามารถหน้าร้านได้อะไร
เ⁠ม⁠นูหมวดหมู่ เ⁠ม⁠นู ราคา ตัวเลือกเพิ่มเติม รูปภาพ — ไม่รวมรายการที่หยุดขาย
รับอ⁠อ⁠เ⁠ด⁠อ⁠ร์ส่งอ⁠อ⁠เ⁠ด⁠อ⁠ร์ในคำขอเดียวและได้เลขอ⁠อ⁠เ⁠ด⁠อ⁠ร์
แก้ไขและยกเลิกได้จนกว่าร้านจะรับอ⁠อ⁠เ⁠ด⁠อ⁠ร์
ตรวจโค้ดส่วนลดส่วนลดบนหน้าร้านและบนแ⁠ค⁠ช⁠เ⁠ชี⁠ย⁠ร์คำนวณเหมือนกัน
แจ้งการชำระเงินการจ่ายฝั่งหน้าร้านเชื่อมกับวิธีชำระเงินของร้าน
สถานะการรับอ⁠อ⁠เ⁠ด⁠อ⁠ร์ร้านรับอ⁠อ⁠เ⁠ด⁠อ⁠ร์อยู่ตอนนี้หรือไม่
ส่งสถานะกลับรับแล้ว กำลังทำ ส่งให้ไรเดอร์แล้ว — การแจ้งเตือนส่งไปที่หน้าร้านและลงนามด้วยรหัสลับร่วม

ป้องกันการซ้ำ (idempotency)

หน้าร้านส่งทุกอ⁠อ⁠เ⁠ด⁠อ⁠ร์พร้อม คี⁠ย์ของการทำรายการ ของตัวเอง ส่งซ้ำด้วยคี⁠ย์เดิมจะไม่สร้างอ⁠อ⁠เ⁠ด⁠อ⁠ร์ที่สอง — ป้องกันการกดสองครั้ง สัญญาณหลุด และการส่งซ้ำของคิว

ผลในทางปฏิบัติ: ถ้าสัญญาณหลุด ส่งคำขอซ้ำได้ไม่ต้องกลัว ที่ต้องระวังคือกลับกัน — สร้างคี⁠ย์การทำรายการใหม่ให้อ⁠อ⁠เ⁠ด⁠อ⁠ร์เดิมของลูกค้า

สิ่งที่ควรรู้ตอนพัฒนา

  • รายการระบุด้วยรหัส ไม่ใช่ชื่อ: ชื่อเปลี่ยนได้ รหัสไม่เปลี่ยน
  • ตัวเลือกเพิ่มเติมส่งแยก จากเ⁠ม⁠นู พร้อมรหัสและราคาของตัวเอง
  • ราคาของแถวคือเงิน: เซิร์ฟเวอร์ตรวจสอบราคาและไม่เดาเอง
  • รายการหมดเปลี่ยนตลอด: ขอเ⁠ม⁠นูก่อนแสดงทุกครั้ง ไม่แคชไว้ทั้งวัน
  • ตัวเลือกบังคับที่ยังไม่ได้เลือก ไม่ทำให้ถูกปฏิเสธ — อ⁠อ⁠เ⁠ด⁠อ⁠ร์จะเข้ามา และผู้ดูแลเลือกเอง
  • มีการจำกัดความถี่ของคำขอ และมีด่านแยกสำหรับการตรวจโค้ดส่วนลดผิดซ้ำ ๆ หน้าร้านปกติไม่ติด ส่วนลูปสุ่มเดาจะติดทันที

ข้อผิดพลาด

คำตอบเมื่อเกิดข้อผิดพลาดอธิบายชัด: เห็นว่ารายการไหนไม่ผ่านและเพราะอะไร ตอนเชื่อมต่อ ให้บันทึกเนื้อหาคำตอบทั้งหมดลงล็อก — ประหยัดเวลาเขียนคุยกันได้หลายชั่วโมง

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

ตรวจสอบก่อนเปิดใช้

  1. ขอเ⁠ม⁠นูและแสดงบนหน้าร้าน รวมถึงรายการหมด
  2. ส่งอ⁠อ⁠เ⁠ด⁠อ⁠ร์ทดลองและเห็นอ⁠อ⁠เ⁠ด⁠อ⁠ร์ในแผงของแ⁠ค⁠ช⁠เ⁠ชี⁠ย⁠ร์
  3. ส่งซ้ำด้วยคี⁠ย์การทำรายการเดิม และตรวจว่าไม่มีอ⁠อ⁠เ⁠ด⁠อ⁠ร์ที่สอง
  4. ตรวจโค้ดส่วนลด — ทั้งที่ใช้ได้และที่หมดอายุ
  5. แจ้งการชำระเงิน และเห็นว่าอ⁠อ⁠เ⁠ด⁠อ⁠ร์ปิดด้วยวิธีชำระเงินที่ถูกต้อง
  6. ตรวจกรณีสัญญาณหลุด: หยุดคำตอบกลางทางแล้วส่งคำขอซ้ำ