Đặc tả S2Sell API
S2Sell API là MCard API cung cấp khả năng mua thẻ server to MCard.
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](post/mcapi-first) để 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)
1. 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.
2. 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).
3. 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.
4. 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.
5. 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).
6. 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.
1. Mã nhóm CATECODE là chuỗi ký tự hoa A-Z/chữ số và không dài quá 4 ký tự.
2. 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:
1. CARDTYPEID: mã sản phẩm (loại thẻ).
2. 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ữ.
3. CARDVALUE: mệnh giá sản phẩm, hay giá trị thẻ (mệnh giá in trên mặt thẻ giấy).
4. 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ỳ).
5. 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](mailto:support@esi.vn)
hoặc [services@mcard.vn](mailto:services@mcard.vn)
Các kịch bản thử nghiệm (lệnh curl gõ trên máy chủ linux):
1. 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"},...
2. 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"}
3. 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](https://mcard.vietfi.net/mcardstatic/swagger-ui.html?f=https://mcard.vietfi.net/mcapi/swagger/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](https://swagger.io/tools/swagger-codegen/). Mã nguồn được generate hoặc code như sau:
* PHP: [Tải PHP demo](https://esi.vn/release/mcapi/s2sell-php-demo20160225.tar.gz)
* Java: [Tải Java demo](https://esi.vn/release/mcapi/s2sell-java-demo20160225.zip)