19. API key และ webhook
19.1 เลือกให้ถูกทาง
หัวข้อที่มีชื่อว่า “19.1 เลือกให้ถูกทาง”- API key: ให้โปรแกรมของคุณเรียก EZer เพื่ออ่านหรือเขียนข้อมูล
- Webhook: ให้ EZer แจ้งโปรแกรมของคุณว่ามีเรื่องใหม่ แล้วโปรแกรมไปดึงข้อมูลเองผ่าน API
- ผู้ช่วย AI: ถ้าจะเชื่อมผู้ช่วย AI ไม่ต้องใช้ key ให้ดูบทเชื่อมผู้ช่วย AI
ทั้งสองอย่างอยู่ที่ ตั้งค่า แท็บ คีย์ API
19.2 สร้าง API key
หัวข้อที่มีชื่อว่า “19.2 สร้าง API key”สมาชิกทุกคนสร้าง key ของตัวเองได้ key หนึ่งใช้ได้กับผู้ให้บริการเดียว ถ้ามีสามผู้ให้บริการ ต้องมีสาม key และ key ไม่มีสิทธิ์เกินเจ้าของ ถ้าเจ้าของออกจากผู้ให้บริการ key หยุดใช้ได้
- เปิด ตั้งค่า แท็บ คีย์ API แล้วกด สร้าง API key
- กรอก ชื่อ เช่น ชื่อโปรแกรมที่จะใช้ key นี้
- เลือก ระดับสิทธิ์: อ่าน-เขียน หรือ อ่านอย่างเดียว ถ้าโปรแกรมแค่ดึงข้อมูลไปดู เลือกอ่านอย่างเดียว
- เลือก อายุการใช้งาน: ไม่มีวันหมดอายุ หรือ 1, 7, 30, 90, 365 วัน เลือกได้ตอนสร้างเท่านั้น แก้ภายหลังไม่ได้
- กด สร้าง
- EZer แสดง key ครั้งเดียว กด คัดลอก แล้วเก็บไว้ในที่ปลอดภัยก่อนกด เสร็จแล้ว — ปิด
ดูและยกเลิก key
หัวข้อที่มีชื่อว่า “ดูและยกเลิก key”ตารางแสดงชื่อ ระดับสิทธิ์ ส่วนต้นของ key เจ้าของ ใช้ล่าสุด หมดอายุ และสถานะ สมาชิกเห็นเฉพาะ key ของตัวเอง ผู้ดูแลหลักและผู้จัดการเห็นและยกเลิกได้ทุก key ของผู้ให้บริการ ถ้า key รั่ว กด ยกเลิก key ที่แถวนั้นแล้วยืนยัน ยกเลิกแล้วย้อนกลับไม่ได้ และแถวขึ้นว่า ถูกยกเลิก key ที่หมดอายุแล้วก็แสดง ถูกยกเลิก และไม่มีปุ่มยกเลิก key
EZer ไม่มีปุ่มหมุนเวียน key ถ้าจะเปลี่ยน ให้สร้าง key ใหม่ เปลี่ยนในโปรแกรมของคุณ แล้วยกเลิกอันเก่า
19.3 เรียก API ด้วย key
หัวข้อที่มีชื่อว่า “19.3 เรียก API ด้วย key”ส่ง key ในหัว Authorization ตัวอย่างนี้ถามว่า key นี้ทำอะไรได้บ้างในผู้ให้บริการหนึ่ง ใช้ key ที่ขึ้นต้นด้วย ezk_ ของคุณแทนข้อความตัวอย่าง
GET /api/providers/{provider_id}/my-accessAuthorization: Bearer ezk_xxxxxxxx- คำขอที่เขียนหรือเปลี่ยนข้อมูล (POST, PUT, PATCH, DELETE) ต้องมีหัว Idempotency-Key เป็นข้อความไม่ซ้ำ ยาวไม่เกิน 200 ตัวอักษร ถ้าส่งซ้ำเพราะเครือข่ายหลุด ให้ใช้ค่าเดิม ขาดหัวนี้ EZer ตอบ 400
- key อ่านอย่างเดียวเขียนไม่ได้ ทุกคำขอเขียนได้ 403
- ข้อผิดพลาดมีรหัส (
code) ให้โปรแกรมของคุณเลือกทำตามรหัส ส่วนข้อความไทยและอังกฤษไว้ให้คนอ่าน - API ไม่ได้สัญญาว่าจะไม่เปลี่ยนรูปแบบ ฟิลด์ใหม่อาจโผล่เมื่อไรก็ได้ โปรแกรมของคุณต้องไม่พังเมื่อเจอฟิลด์ที่ไม่รู้จัก
เอกสารอ้างอิงเต็มอยู่ที่การ์ด สำหรับนักพัฒนา ในแท็บเดียวกัน มีลิงก์ เอกสาร API และ ข้อกำหนด OpenAPI ที่อยู่ของเซิร์ฟเวอร์ให้ใช้ตามเอกสารนั้น
19.4 ตั้ง webhook
หัวข้อที่มีชื่อว่า “19.4 ตั้ง webhook”webhook ของ EZer เป็นแค่การสะกิด EZer บอกว่ามีเรื่องใหม่ แต่ไม่ส่งข้อมูลหรือจำนวนใด ๆ ไปด้วย โปรแกรมของคุณต้องไปดึงข้อมูลจริงผ่าน API ด้วย key การสะกิดซ้ำหรือมาสลับลำดับจึงไม่เป็นอันตราย
ผู้ดูแลหลักและผู้จัดการจัดการ webhook ได้ ส่วนนี้ซ่อนจากคนที่ไม่มีสิทธิ์ และสร้างได้เฉพาะตอนเข้าสู่ระบบ API key ทำไม่ได้
- ในแท็บ คีย์ API ไปที่ส่วน ปลายทาง Webhook แล้วกด เพิ่มปลายทาง
- กรอก URL ที่โปรแกรมของคุณรับคำขอ ต้องเป็น https และเป็นที่อยู่บนอินเทอร์เน็ตสาธารณะ ที่อยู่ภายในเครือข่ายหรือชี้มาที่เครื่องตัวเอง (localhost) ใช้ไม่ได้ ถ้าจะทดสอบ ให้ใช้บริการที่เปิดทางเข้า https สาธารณะชั่วคราว
- ติ๊กเรื่องที่ต้องการใต้ ส่งการแจ้งเตือนเมื่อ ปลายทางใหม่เริ่มที่เรื่องส่งรายการให้สำนักงานบัญชีอย่างเดียว
- กด เพิ่ม
เรื่องที่ EZer สะกิดได้
หัวข้อที่มีชื่อว่า “เรื่องที่ EZer สะกิดได้”- รายการถูกล็อกแล้ว: รายการของผู้ให้บริการในเดือนหนึ่งถูกล็อก สะกิดหนึ่งครั้งต่อหนึ่งเหตุการณ์ ไม่ใช่ต่อหนึ่งรายการ และไม่ได้แปลว่านำส่งสรรพากรแล้ว
- ลิงก์ชำระเงินออนไลน์เปลี่ยนสถานะ: ลิงก์ชำระเงินกลายเป็นจ่ายแล้ว หมดอายุ ไม่สำเร็จ หรือยกเลิก ไม่สะกิดตอนเพิ่งเปิดรอชำระ
สิ่งที่โปรแกรมของคุณได้รับ
หัวข้อที่มีชื่อว่า “สิ่งที่โปรแกรมของคุณได้รับ”EZer ส่งคำขอ POST เป็น JSON ที่มี type, event_id, provider_id, month (วันแรกของเดือน), occurred_at และ subject_id เฉพาะเรื่องลิงก์ชำระเงิน ใช้ event_id กันการประมวลผลซ้ำ แล้วไปดึงข้อมูลผ่าน API
ไม่มี secret ร่วมและไม่มีลายเซ็นให้ตรวจ EZer พิสูจน์ตัวเองด้วย Google ID token ในหัว Authorization แบบ Bearer ที่ aud คือ URL ของปลายทางคุณ token นี้บอกว่าใครเรียก แต่ไม่ได้รับรองว่าเนื้อความไม่ถูกแก้ เพราะเนื้อความไม่มีข้อมูลอยู่แล้ว ให้ดึงข้อมูลจาก API เสมอ
เมื่อส่งไม่สำเร็จ
หัวข้อที่มีชื่อว่า “เมื่อส่งไม่สำเร็จ”ส่งไม่สำเร็จคือตอบไม่ใช่ 2xx (รวมการย้ายที่อยู่ 3xx ซึ่ง EZer ไม่ตาม) เชื่อมต่อไม่ได้ หรือไม่ตอบใน 10 วินาที EZer ลองรวมหกครั้ง ห่างกัน 10 นาที 30 นาที 2 ชั่วโมง 6 ชั่วโมง และ 14 ชั่วโมง รวมราว 23 ชั่วโมง แล้วหยุด แถวของปลายทางขึ้นป้าย ส่งไม่สำเร็จ และ EZer ส่งอีเมลหาคนที่เพิ่มปลายทางนี้ (ถ้าคนนั้นไม่อยู่แล้ว จะส่งหาผู้ดูแลหลัก) EZer ไม่ปิดปลายทางเอง ถ้าครั้งต่อไปส่งสำเร็จ ป้ายหายไป
กดไอคอน ประวัติการส่ง ที่แถว (ชื่อขึ้นเมื่อชี้เมาส์)เพื่อดูแต่ละครั้ง มีสถานะ เรื่อง เวลา ครั้งที่ และข้อผิดพลาด เก็บไว้ 90 วัน สถานะ ยังไม่ได้ส่ง แปลว่า EZer ยังไม่มีตัวตนสำหรับเซ็นคำขอ จึงยังไม่ได้ส่งอะไรออกไป แถวที่ไม่ได้รอส่งมีปุ่ม ส่งอีกครั้ง ใช้ event_id เดิม ปุ่ม แก้ไข ที่แถวใช้เปลี่ยน URL หรือเรื่องที่รับ และ ลบ หยุดส่ง
19.5 ต่อไป
หัวข้อที่มีชื่อว่า “19.5 ต่อไป”ถ้าต้องการให้ผู้ช่วย AI ทำงานกับ EZer โดยไม่ต้องเขียนโค้ด ให้ดูบทเชื่อมผู้ช่วย AI