คู่มือการอัปเกรด 2019-05-29

โอมิเซะมีความยินดีแจ้งให้ทราบถึง API เวอร์ชันใหม่ เวอร์ชัน 2019-05-29 ซึ่งเปิดให้อัปเกรดได้ตั้งแต่วันนี้เป็นต้นไป

ร้านค้าสามารถศึกษาคู่มือการอัปเกรดนี้เพื่อใช้ API เวอร์ชันล่าสุดได้อย่างเต็มประสิทธิภาพ การอัปเกรดเวอร์ชันของ API จะไม่ใช่การอัปเกรดแบบอัตโนมัติ เมื่อร้านค้าได้ศึกษาคู่มือนี้แล้วสามารถอัปเกรดบัญชีของตัวเองและปรับเปลี่ยนแอปพลิเคชันได้เมื่อพร้อม หากต้องการอ่านข้อมูลเพิ่มเติมเกี่ยวกับเวอร์ชัน API ของเรา สามารถดูได้ที่คู่มือ API

ก่อนอัปเกรดกรุณาศึกษาข้อมูลทั้งหมดในคู่มือฉบับนี้และทดสอบการทำงานอย่างละเอียดในโหมดทดสอบก่อน เนื่องจากมีการอัปเกรดบางส่วนที่ไปกระทบการทำงานของระบบเดิม

ตัวอย่างเช่น Webhook events จะแสดงรายละเอียดตามเวอร์ชัน API ที่ใช้ในขณะทำรายการจริง ไม่ใช่การอิงตามเวอร์ชัน API ที่ระบุใน request

เมื่ออัปเกรดเวอร์ชัน API แล้วจะไม่สามารถปรับกลับมาใช้งานเวอร์ชันเดิมได้อีก

โอมิเซะได้ทำการอัปเกรด API ครั้งใหญ่ล่าสุดเมื่อปลายปี 2017 เป็นเวอร์ชัน 2017-11-02 ซึ่งในครั้งนั้นได้เพิ่ม Source API เข้ามาเพื่อรองรับช่องทางการรับชำระเงินรูปแบบใหม่ๆ ที่เราได้เปิดให้บริการในช่วงปีที่ผ่านมานี้ การอัปเกรดเวอร์ชันเป็น 2019-05-29 ครั้งนี้ ทีมนักพัฒนาของเราตั้งใจที่จะปรับปรุงส่วนต่างๆ เพื่อเพิ่มความราบรื่นและเสถียรภาพการทำงานของระบบให้ดียิ่งขึ้น

คู่มือการอัปเกรดนี้ อธิบายการปรับปรุงส่วนต่างๆ โดยแบ่งตามหัวข้อดังนี้:

  1. Capability endpoint ใหม่ที่เราเพิ่มเข้ามา
  2. ภาพรวมการปรับปรุงเปลี่ยนแปลงและความตั้งใจของเรา
  3. การเปลี่ยนแปลงที่มีผลกระทบต่อโครงสร้างข้อมูลของ API เดิม
  4. การปรับปรุงที่ไม่มีผลกระทบต่อครงสร้างข้อมูลของ API เดิม

ร้านค้าสามารถเลือกอ่านคู่มือการใช้งานให้ตรงตามเวอร์ชัน API ที่ใช้ในปัจจุบัน โดยไปที่คู่มือการใช้งานและเลือกเวอร์ชันจากเมนูด้านซ้ายบน

Capability Endpoint ใหม่ของบัญชีผู้ใช้

โอมิเซะได้เพิ่ม "capability" endpoint ใหม่ เพื่อให้ร้านค้าสามารถดึงข้อมูลที่เกี่ยวข้องกับบัญชีผู้ใช้ได้สะดวกยิ่งขึ้น ข้อมูลต่างๆ ที่สามารถเรียกได้ คือ

  • ตรวจสอบว่าบัญชีผู้ใช้มีการเปิดระบบผ่อนชำระแบบ 0% เอาไว้หรือไม่
  • การตรวจช่องทางรับชำระเงินทั้งหมดที่เปิดใช้เอาไว้
  • การตรวจสอบรายชื่อธนาคารที่สามารถโอนเงินออกได้

ข้อมูลเพิ่มเติมที่กล่าวมาข้างต้นนี้ สามารถค้นหาได้โดยใช้ public key ซึ่งจะทำให้ใช้งานง่ายสำหรับร้านค้าที่เชื่อมต่อกับระบบของโอมิเซะผ่าน Source API

กรุณาดู capability-api สำหรับข้อมูลเพิ่มเติม

การเปลี่ยนแปลงด้านแบบแผนการตั้งชื่อ

ตัวแปรที่ใช้กริยาในรูปอดีต (เช่น created, refunded) ที่แทนค่าของ datetime (เช่น 2020-01-01T00:00:00Z) จะมีการเพิ่ม _at ไว้ด้านหลัง ตัวอย่างเช่น created จะถูกเปลี่ยนเป็น created_at ตั้งแต่ 2019-05-29 เป็นต้นไป

ตัวแปรที่ใช้กริยารูปอดีตจะถูกใช้แค่กับตัวแปรที่มีค่า true กับ false (Boolean values) เท่านั้น ตัวอย่างเช่น charge.reversed ที่แจ้งรายการที่ยกเลิกการกันวงเงิน จะคงใช้คำศัพท์เดิม ส่วน charge.refunded ที่แจ้งจำนวนเงินถูกเปลี่ยนเป็น charge.refunded_amount

ตัวแปรที่ใช้แสดงค่าของวันที่ หรือ date (เช่น 2020-01-01) มีการเพิ่ม _on อยู่ด้านหลัง ตัวอย่างเช่น receipt.date ถูกเปลี่ยนเป็น receipt.issued_on

ต่อไปนี้ทุกสกุลเงินจะแสดงผลเป็นตัวพิมพ์ใหญ่ทั้งหมด ตัวอย่างเช่น thb ถูกเปลี่ยนเป็น THB เพื่อให้สอดคล้องกับมาตรฐานของ ISO 4217.

ระบบที่เพิ่มเสถียรภาพ

การตอบกลับของ JSON ถูกปรับให้มีโครงสร้างแบบเดียวกันในทุกๆ endpoint และการตอบกลับของ API ได้มีการเพิ่ม livemode และ location

ดูการเปรียบเทียบ JSON ในเวอร์ชันก่อนหน้ากับเวอร์ชันปัจจุบัน เมื่อทำการลบข้อมูลบัตรสำเร็จ จาก 2017-11-02 เป็น 2019-05-15

เราได้อัปเดทค่าตัวแปรของ schedule.status. โดยสถานะ active ถูกเปลี่ยนเป็น running และตัวแปร active อันใหม่ที่เพิ่มเข้ามาจะแสดงค่า true ถ้าสถานะเป็น running หรือ expiring การเปลี่ยนแปลงนี้จะช่วยให้สอดคล้องกับ Search API ที่สามารถค้นหาโดยใช้สถานะ active

โครงสร้างของ Bank account API ได้ถูกปรับให้เป็นรูปแบบเดียวกันสำหรับทุกประเทศ

การเปลี่ยนแปลงที่มีผลกระทบต่อโครงสร้างข้อมูลของ API เดิม

object old field replacement field notes
account id team team now reflects pre-2019-05-29 id value; 2019-05-29 id now is identifier specific to your account
balance reserve_amount reserve
balance available transferable
bank account account_type type
charge refunded refunded_amount
dispute transaction transactions A single dispute can have multiple transactions
forex from base See Investopedia: Base Currency
forex to quote See Investopedia: Quote Currency
receipt date issued_on
occurrence schedule_date scheduled_on Note the "d" at the end of "schedule"
occurrence retry_date retry_on
schedule start_date start_on
schedule end_date end_on
schedule next_occurrence_dates next_occurrences_on Note the "s" at the end of "occurrence"
source installment_terms . installment_term Installment term is now singular, and serialized as an integer rather than a string
transaction type direction
transaction source origin Replaced due to conflict with Source API
transfer transaction transactions A single transfer can have multiple transactions

การเปลี่ยนแปลงที่ไม่กระทบต่อโครงสร้างข้อมูลของ API เดิม

ระบบ API ของเรามีการเพิ่มค่าตัวแปรใหม่เข้ามาเป็นประจำอยู่แล้ว API เวอร์ชัน 2019-05-29 ได้มีการเพิ่มตัวแปรตามตารางด้านล่างและจะเพิ่มให้กับเวอร์ชันอื่นๆ เร็วๆ นี้

object added
charge fee, fee_vat, interest, interest_vat, and net
charge schedule default_card
dispute funding_amount and funding_currency
document deleted and download_uri
recipient deleted and metadata
refund funding_amount, funding_currency, and status
schedule active
transfer deleted, fee_vat, net, and total_fee
transaction key