Biz API

​Cách tích hợp Got It Biz API

Đây là tài liệu kỹ thuật kết nối hệ thống Got It, được sử dụng để phát hành voucher trên nhiều nền tảng khác nhau: Desktop Website, Mobile Website, Mobile Application, ... Yêu cầu bắt buộc là API Got It phải được gọi từ server của khách hàng. Không được gọi từ Javascript phía end-user.

​Lịch sử tài liệu

Ngày cập nhật	Nội dung cập nhật
02/10/2023	Thêm mới

​Quy trình tích hợp

Các bước cơ bản để tích hợp với Got It:

• Bước 1: Đăng ký tài khoản doanh nghiệp. Bạn cần hoàn thành quá trình đăng ký với đầy đủ thông tin, trạng thái mặc định của doanh nghiệp sẽ là chưa xác thực. Thông tin tích hợp mặc định sẽ môi trường Stg
• Bước 2: Tiến hành tích hợp theo tài liệu được cung cấp.
• Bước 3: Đơn vị tiến hành kiểm thử phần mềm, tham khảo các testcase của Got It cung cấp để kiểm tra các lỗi phổ biến trong quá trình phát hành voucher.
• Bước 4: Sau khi đơn vị kinh doanh hoàn thành tích hợp và kiểm thử, Got It sẽ xác thực dịch vụ của bạn trên môi trường test trước khi lên production.
• Bước 5: Sau khi được xác nhận, tài khoản doanh nghiệp của bạn sẽ được chuyển sang trạng thái đã xác thực.
• Bước 6: Thay đổi các thông tin tích hợp theo môi trường production.

​Thông tin tích hợp

Got It cung cấp cho đơn vị kinh doanh hai môi trường để tích hợp với Biz API:

• Stagging: Sử dụng trong quá trình tích hợp: xây dựng tính năng, kiểm thử, debug, v.v…
• Production: Sử dụng để triển khai cho end user tạo voucher thật.

​Yêu cầu bảo mật

• Sử dụng giao thức TLS v1.2

​Key Credential

Tất cả yêu cầu gửi đến phải chứa trường “X-GI-Authorization” trên header, API Key do Got It cung cấp. Đây là mã bí mật, duy nhất chỉ cung cấp cho khách hàng, khách hàng có trách nhiệm bảo mật. Khách hàng để lộ API Key X-GI-Authorization sẽ phải chịu trách nhiệm cho mọi voucher phát sinh từ phía API Key này.

Thông tin này sẽ thay đổi theo từng môi trường, khách hàng nên để chúng trong cấu hình của application.

​Cấu hình HTTP Request

Key	Dữ liệu
Content-Type (required) Applied to all operations	Luôn luôn là 'application/json' Default: application.json
Domain (required)	Môi trường Staging: https://api-biz-stg.gotit.vn/ Môi trường Production: https://api-biz.gotit.vn/
Accept-Language	Ngôn ngữ sử dụng cho các trường dạng text. (Ví dụ: tên sản phẩm, điều khoản sử dụng…) en: Tiếng Anh vi: Tiếng Việt

​Luồng xử lý

Mô tả chi tiết

(1)(2) Request/Response master data:

• Yêu cầu thông tin để phục vụ cho việc tạo voucher và hiển thị thông tin cho người dùng cuối (end-user).
• Sử dụng các API ở mục Get master data
• Các thông tin được mô tả chi tiết ở mục Dữ liệu & Định nghĩa cho từng API

(3)(4) Request issue voucher/Response voucher information:

• Yêu cầu tạo voucher.
• Sử dụng các API ở mục Transaction.

(5)(6) Request/Response send voucher to end user

• Yêu cầu gửi voucher đến người dùng cuối. Có 2 hình thức: sms và email.
• Sử dụng API ở mục Send SMS

(7) Request use voucher

• Người dùng đến yêu cầu sử dụng và cung cấp thông tin voucher cho đối tác Merchant của Got It.

(8)(9) Request/Response redeem voucher

• Đối tác kiểm tra voucher hợp lệ và đánh dấu sử dụng.

(10) Response result

• Đối tác phản hồi lại kết quả cho người dùng cuối

(11)(12) Request/Response check voucher

• Kiểm tra trạng thái voucher
• Sử dụng API ở mục Phát hành voucher.

(13) Got It gửi thông báo cập nhật trạng thái voucher (khi voucher có sự thay đổi về trạng thái)

​Bảng trạng thái voucher

Mã	Tên trạng thái	Mô tả
1	New	Voucher đã được phát hành và đã gửi trả qua API response
2	Sent	Voucher được gửi bằng Email hoặc SMS (sử dụng API gửi voucher do Got It cung cấp)
3	Opened	Voucher link đã được mở (do user)
4	Used	Voucher đã được sử dụng (được đổi bởi các cửa hàng vật lý của người bán hoặc các dịch vụ trực tuyến đối tác (ví dụ: nạp tiền điện thoại,...)
5	Downloaded	Trong trường hợp voucher được phát hành bằng Got It Biz Portal: thì ý nghĩa là đã download file chứa thông tin voucher
8	Expired	Voucher đã hết hạn sử dụng
9	Cancelled	Voucher đã bị hủy (Got It hủy)
10	Splitted	Splittable voucher đã được tách. Voucher A khi bị tách, sẽ phát sinh các voucher con B, C, D... Khi đó Voucher A sẽ có state = 10
0	Inactive/ New	Voucher đang chờ ngày được kích hoạt/ Voucher đang được reserved, chờ sử dụng

​Bảng mã lỗi

• API Key Related 00XX (Lỗi liên quan đến API Key)
• Parameter Related 10XX (Lỗi liên quan đến cú pháp tham số truyền vào)
• Value Related 20XX (Lỗi liên quan đến giá trị tham số)
• Other 99XX

Chi tiết tham khảo Biz API Error Codes

​Đảm bảo an toàn thông tin

Để đảm bảo an toàn thông tin khi phát hành voucher, Got It áp dụng các biện pháp như sau:

• Whitelist IP của client khi gọi API
• Thêm key vào header khi gọi API
• Mã hóa bất đối xứng RSA (hai chiều)

Chi tiết tham khảo An toàn thông tin với Biz API

​Danh sách API

Bao gồm:

​Các API lấy danh mục

Dùng để lấy danh mục "Ngành" (Category), "Thương hiệu" (Brand) và "Sản phẩm" (Product)

API	Method	Path
Category	GET	api/v4.0/categories
Category by Product	GET
Brand	GET	api/v4.0/brands
Brand by Product	GET
Brand by Category	GET	api/v4.0/categories//brands
Brand detail	GET	api/v4.0/brands/
Product list	GET	api/v4.0/products
Product detail	GET	api/v4.0/products/
Store by Product	GET	api/v4.0/products//stores

​Các API phát hành/kiểm tra thông tin voucher

API	Method	Path
Phát hành voucher link v (single voucher link)	POST	api/v4.0/vouchers/v
Phát hành voucher link g (group voucher link)	POST	api/v4.0/vouchers/g
Phát hành voucher link e (e-wallet voucher link)	POST	api/v4.0/vouchers/e
Kiểm tra (nhiều) voucher bằng transactionRefId	GET	api/v4.0/vouchers/multiple/status/

​Các API gửi voucher voucher

dùng để gửi voucher đến người dùng cuối

API	Method	Path
Send via Email	POST	api/v4.0/vouchers/send/email
Send via SMS	POST	/api/v4.0/vouchers/send/sms

​Cấu trúc response API

Dữ liệu	Kiểu	Mô tả
status	String	HTTP status
statusCode	Number	HTTP Status Code
error	String	Mã lỗi (nếu có)
message	String	Thông báo lỗi (nếu có)
data	Array object	Chứa data trả về. Trong trường hợp fail, trả về []

---