Đặc tả S2Sell API
Viết tắt S2Sell = Server - Server Sell. API = Application Programming Interface
Mục đích
S2Sell API được cung cấp dưới dạng chung của mcapi theo thiết kế kiểu REST. Xin tham khảo Quy tắc API Chung để biết thêm chi tiết.
Với S2Sell đại lý không cần giữ kho thẻ riêng. Dịch vụ MCard sẽ lưu trữ kho thẻ, quản lý thanh toán… Đại lý chỉ cần ứng dụng chạy trên máy chủ của đại lý, kết nối tới MCard và thực hiện gửi lệnh mua thẻ sang MCard khi có nhu cầu là đáp ứng bất kỳ yêu cầu mua thẻ cào nào, bất kỳ giờ nào, hoàn toàn tự động.
Với khả năng đáp ứng kho hàng phong phú, luôn sẵn có, dịch vụ ổn định và an toàn. Và khả năng tích hợp rộng rãi công nghệ, hiệu quả cao sẽ giúp quý đại lý đạt doanh thu tốt.
Đặc tả S2Sell API
Cách thức và tổ chức dữ liệu
Sau khi gửi lệnh mua thành công, MCard sẽ trả về kết quả là mã PIN cho đại lý. Tiền mua sẽ trừ vào tài khoản đại lý trên MCard và giá sẽ áp dụng là giá chính sách riêng mà đại lý nhìn thấy sau khi login vào MCard (Web). Để tra cứu lại hoạt động mua và các thông tin khác, đại lý cũng dùng MCard Web để thực hiện.
Thẻ cào (thẻ mã bí mật)
Mỗi sản phẩm thẻ cào MCard đều có mã sản phẩm duy nhất, gọi là CARDTYPEID, mã này là chuỗi ký tự gồm chữ (A-Z viết hoa), số (0-9) và độ dài không quá 20. Các thao tác mua/bán đều cần mã này để thực hiện.
Mỗi thẻ được lưu trữ và bán đi đều có mã series (thường là mã in trên thẻ giấy - và cũng là mã dùng để khiếu nại với nhà mạng - nếu có). Mã series này gọi là CARDSERIESNO, chứa chữ, số, một số ký hiệu như dấu trừ (-), chấm (.), độ dài không quá 20. Mã này không phân biệt chữ hoa và chữ thường (nghĩa là a = A).
Mã CARDSERIESNO này kết hợp CARDTYPEID thành định danh duy nhất của thẻ. Các CARDTYPEID khác nhau có thể có CARDSERIESNO trùng nhau, nhưng không thể có trùng CARDSERIESNO của một CARDTYPEID.
Mỗi thẻ đều có thông tin CARDPINCODE, là thông tin bí mật của thẻ (phần cào dưới lớp tráng bạc của thẻ giấy). Đây là phần MCard bán đi, một khi đã lộ thì không còn giá trị bán lại. Người mua sẽ dùng mã này nạp vào thuê bao điện thoại hoặc game online.
Thông tin thêm để tham khảo của mỗi thẻ còn có: ngày hết hạn sử dụng (CARDEXPIREDATE), thông tin CARDACCNO (cần sử dụng cho một số game online).
Khi thẻ được bán, thì có thêm thông tin SELLVALUE: là giá tiền thực bán thẻ (sau chiết khấu nhưng trước khi trừ khuyến mại). Giá này có thể thay đổi từng thời kì tuỳ theo chính sách giá của MCard và phụ thuộc thời điểm mua thẻ.
Loại thẻ và tổ chức theo category
Có vài chục sản phẩm thẻ khác nhau được kinh doanh, để tiện việc lựa chọn MCard tổ chức sản phẩm thẻ (hay loại thẻ - CARDTYPEID) theo nhóm sản phẩm (category).
Mỗi nhóm category chỉ có 2 thông tin là mã nhóm CATECODE và tên của nhóm CATENAME. Thông qua truy vấn Category quý đại lý có thể liệt kê danh sách các sản phẩm thẻ trong nhóm đó. Thông tin về category tương đối cố định, ít khi thay đổi.
- Mã nhóm CATECODE là chuỗi ký tự hoa A-Z/chữ số và không dài quá 4 ký tự.
- Tên của nhóm CATENAME là chuỗi Unicode tiếng Việt bất kỳ có thể chứa cả ký tự đặc biệt, được sử dụng để mô tả nhóm sản phẩm. Độ dài tối đa 32 chữ.
Mỗi sản phẩm thẻ thì có các thông tin sau:
- CARDTYPEID: mã sản phẩm (loại thẻ).
- CARDNAME: tên sản phẩm (ví dụ loại thẻ nào cho nhà cung cấp nào), tiếng Việt Unicode có dấu độ dài tối đa 64 chữ.
- CARDVALUE: mệnh giá sản phẩm, hay giá trị thẻ (mệnh giá in trên mặt thẻ giấy).
- SELLVALUE: giá bán mà MCard bán cho đại lý ở thời điểm truy vấn (có thể thay đổi tuỳ thời kỳ).
- STOREAVAIL: giá trị cho phép biết thẻ còn hàng hay không. =1 là còn, =0 là hết.
Thông tin sản phẩm được liệt kê theo từng CATECODE tuỳ theo tổ chức sắp xếp lại của MCard mà đổi nhóm. Còn thông tin mỗi sản phẩm thẻ có thể bị thay đổi tên, giá bán hoặc khả năng bán/không bán/thay đổi giá của sản phẩm đó. Mã sản phẩm thẻ một khi đã tạo ra sẽ không bao giờ thay đổi cả.
Do đó khi lập trình quý vị chỉ nên gắn cố định mã CATECODE, còn danh mục sản phẩm thuộc category nào, và giá bán cuối của chúng thì nên truy vấn trực tiếp từ MCard khi cần mua, nếu cache tăng tốc thì chỉ nên lưu cache lại trong vòng tối đa 1 ngày.
Các hàm được hỗ trợ
- categoryList: liệt kê danh mục nhóm (category) hiện cung cấp bởi MCard.
- categoryCardList: liệt kê sản phẩm thẻ trong category (CATECODE chỉ ra). Hệ thống chỉ liệt kê các thẻ đang được chào bán và kèm các thông tin của sản phẩm thẻ.
- cardTypeView: lấy thông tin của sản phẩm thẻ (gồm cả khả năng còn hàng hay không).
- cardBuy: mua thẻ CARDTYPEID với số lượng chỉ trước.
- cardBuyView: lấy thông tin thẻ đã mua có mã CARDTYPEID và CARDSERIESNO.
Hàm categoryList
- Phương thức gọi: HTTP GET, Resouce URI: /s2sell/category
- Input: không có.
- Kết quả trả về: JSON Array chứa các JSON Object là mô tả của category.
- Trường hợp lỗi: HTTP Error!=200, hoặc JSON Error Object
Hàm categoryCardList
- Phương thức gọi: HTTP GET, Resouce URI: /s2sell/category/{CATECODE}
- Input: CATECODE là mã category cần truy vấn (đặt trong URI).
- Kết quả trả về: JSON Array chứa các JSON Object là mô tả của sản phẩm thẻ.
- Trường hợp lỗi: HTTP Error!=200, hoặc JSON Error Object
Hàm cardTypeView
- Phương thức gọi: HTTP GET, Resouce URI: /s2sell/card/{CARDTYPEID}
- Input: CARDTYPEID là mã sản phẩm kiểm tra để mua (đặt trong URI).
- Kết quả trả về: JSON Object là mô tả của sản phẩm thẻ, có thểm trường STOREAVAIL.
- Trường hợp lỗi: HTTP Error!=200, hoặc JSON Error Object
Hàm cardBuy
- Phương thức gọi: HTTP POST, Resouce URI: /s2sell/card/{CARDTYPEID}
- Input: CARDTYPEID là mã sản phẩm cần mua (đặt trong URI), BUYCOUNT là số lượng muốn mua (từ 1..40), SELLDESTNO tuỳ chọn thông tin tham chiếu phía đại lí (dài tối đa 40 chữ, chỉ chứa chữ, số, dấu chấm, dấu trừ và dấu gạch dưới).
- Kết quả trả về: JSON Object, chứa key "result": JSON Array của JSON Object các thẻ đã mua (gồm cả thông tin mã bí mật và SELLTXNID là giao dịch liên quan).
- Trường hợp lỗi: HTTP Error!=200, hoặc JSON Error Object gắn kèm kết quả result (thành công 1 phần).
Hàm cardBuyView
- Phương thức gọi: HTTP GET, Resouce URI: /s2sell/card/{CARDTYPEID}/{CARDSERIESNO}
- Input: CARDTYPEID là mã sản phẩm cần kiểm tra, CARDSERIESNO là số series thẻ đã mua (đặt trong URI).
- Kết quả trả về: JSON Array chứa các JSON Object là mô tả của sản phẩm thẻ.
- Trường hợp lỗi: HTTP Error!=200, hoặc JSON Error Object.
Ví dụ Resource URI
Resource URL để truy vấn danh sách category là:
https://hostname.domain/mcapi/s2sell/category
Resource URL để truy vấn danh sách sản phẩm trong category tên MOBI là:
https://hostname.domain/mcapi/s2sell/category/MOBI
Resource URL để mua/truy vấn sản phẩm tên mã MOBI100 là:
https://hostname.domain/mcapi/s2sell/card/MOBI100
Hỗ trợ phát triển & môi trường kiểm thử
Môi trường kiểm thử
API thử nghiệm được hỗ trợ bởi Công ty ESI qua Base-URL:
https://mcard.vietfi.net/mcapi
Để truy cập môi trường thử nghiệm và đăng ký đại lý và mở chế độ thử API, xin vui lòng liên hệ support@esi.vn hoặc services@mcard.vn
Các kịch bản thử nghiệm (lệnh curl gõ trên máy chủ linux):
- Thử với categoryList:
curl -H "X-API-Key: FE1D..." https://esi.vn/mcapi/s2sell/category
[{"CATENAME":"FPT Online","CATECODE":"FPT"},{"CATENAME":"The Game Online","CATECODE":"GAME"},{"CATENAME":"Garena Games","CATECODE":"GARE"},…
- Thử với cardTypeView:
curl -H "X-API-Key: FE1D..." https://esi.vn/mcapi/s2sell/card/MOBI10
{"CARDVALUE":"10000.00","CARDNAME":"The MobiFone 10.000 ","STOREAVAIL":"1","SELLVALUE":"9450.00","CARDTYPEID":"MOBI10"}
- Thử với cardBuy:
curl -H "X-API-Key: FE1D..." https://esi.vn/mcapi/s2sell/card/MOBI10 -X "POST" -d "BUYCOUNT=1"
{"result":[{"CARDPINCODE":"1234567890","CARDSERIESNO":"029091000008229","CARDEXPIREDATE":"2016-12-30","CARDACCNO":"","SELLTXNID":"8492435"}]}
Thư viện Client tạo sẵn
Theo cách thức triển khai mới, đặc tả kỹ thuật chính xác của API để test (và chạy thật) sử dụng Swagger để mô tả, liên kết sau là để test, đổi hostname thành mcard.vn thì là thử. Xin click để thử mcapi-s2sell.yaml (ở trong có file swagger đuôi .yaml, có thể tải về và dùng công cụ generate client code từ web site Swagger Codegen. Mã nguồn được generate hoặc code như sau:
- PHP: Tải PHP demo
- Java: Tải Java demo
