HƯỚNG DẪN ĐỐI TÁC
Čeština Němčina Angličtina Chorvatština Maďarština Italština Polština Ruština Slovenština Slovinština Ukrajinština Vietnamština
Giới thiệu Hướng dẫn thực hành Hỗ trợ IT Zlavomat.sk Đối tác API

Zlavomat.sk Đối tác API

Bài đăng này được dịch bởi máy

API dùng để truyền thông tin về voucher giữa Zľavomat và hệ thống của đối tác kinh doanh. Cho phép đối tác kiểm tra tính hợp lệ của voucher và áp dụng voucher trong hệ thống của mình. Vì vậy, đối tác không cần sử dụng Giao diện Đối tác cho mục đích này.

Các ví dụ sử dụng có thể:

  • Khách hàng mua voucher, trong đó điều kiện cung cấp dịch vụ là nhập mã trên trang web của đối tác khi tạo đơn hàng. Nhờ API, sau khi nhập mã sẽ kiểm tra ngay lập tức tính hợp lệ của voucher. Giá trị của voucher sẽ được trừ vào giỏ hàng của đối tác và đồng thời voucher sẽ được tự động áp dụng trên Zľavomat.
  • Theo cách tương tự, cũng có thể kiểm tra tính hợp lệ của voucher trong hệ thống đặt chỗ của đối tác hoặc nạp số dư đã mua cho khách hàng với giá trị nhất định trực tiếp trên trang web của đối tác.

Partner API yêu cầu token, là duy nhất cho mỗi đối tác và được gửi trong mỗi yêu cầu. Nếu bạn muốn sử dụng Partner API, hãy liên hệ với nhân viên kinh doanh của bạn/chúng tôi.

Định dạng yêu cầu

Điểm truy cập API nằm tại địa chỉ /api.

Định dạng yêu cầu là 

<URL přístupového bodu>/<akce>[<pa­rametry>]

Tất cả các yêu cầu đều là yêu cầu HTTP GET tiêu chuẩn, nghĩa là yêu cầu kiểm tra tính hợp lệ của voucher có thể trông như sau: 

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345.

Định dạng phản hồi

Phản hồi của máy chủ luôn ở định dạng JSON với header Content-type tương ứng. Cấu trúc cơ bản của phản hồi như sau. 

{
 "result": true,
 "data": {
 ...
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Giá trị của trường result là true (nếu thành công) hoặc false (nếu có lỗi). Trong trường hợp lỗi, trường error chứa mã lỗi (code) và mô tả của nó (message). Ngoài việc chỉ ra trong trường error, hệ thống còn trả về mã trạng thái HTTP tương ứng trong trường hợp lỗi (400, 401, 403, 404).

Trường data chứa dữ liệu được trả về bởi hành động gọi và nội dung của nó là riêng biệt.

Tất cả dữ liệu đều ở định dạng YYYY-MM-DDTHH:MM:SSZ (ISO8601; ví dụ: 2011⁠–⁠01⁠–⁠01T10:10:10+0­2:00).

Xác minh tính hợp lệ của voucher

  • hành động: voucherCheck
  • tham số: token (bắt buộc; token duy nhất của đối tác), code (bắt buộc; mã voucher)

Có ba mã voucher thử nghiệm:

  • 1234⁠–⁠5677⁠–⁠77⁠–⁠111 (đã thanh toán, chưa sử dụng),
  • 2234⁠–⁠5688⁠–⁠88⁠–⁠222 (đã thanh toán, đã sử dụng),
  • 3234⁠–⁠5699⁠–⁠99⁠–⁠333 (chưa thanh toán, chưa sử dụng).

Nếu ứng dụng sử dụng một trong các mã này, máy chủ sẽ trả về phản hồi tương ứng (trong trường hợp voucher đã thanh toán và chưa sử dụng sẽ trả về cả dữ liệu mẫu của voucher và hành động).

Định dạng dữ liệu phản hồi 

{
 "token": <autentizační token>,
 "code": <kód voucheru>,
 "voucherData": <data voucheru>
}

Tham số voucherData chứa định nghĩa của voucher theo định dạng sau. 

{
 "id": <ID voucheru>,
 "orderId": <ID objednávky>,
 "title": <název voucheru>,
 "ordered": <datum a čas objednávky; datum a čas>,
 "paidDate": <datum zaplacení objednávky; datum>
 "validFrom": <začátek platnosti voucheru; datum>,
 "validTo": <konec platnosti voucheru; datum>,
 "key": <kód voucheru>,
 "code": <kód voucheru>,
 "product": <ID akce>,
 "productName": <název akce>,
 "variant": <ID varianty akce>,
 "variantName": <název varianty akce>,
 "imageUrl": <URL obrázku>,
 "smallImageUrl": <URL náhledu>,
 "productUrl": <URL akce>
}

Các trường variant và variantName chứa ID và tên của biến thể sản phẩm đã đặt, nếu sản phẩm đó có các biến thể. Nếu không, cả hai thuộc tính sẽ có giá trị NULL.

Các trạng thái lỗi

  • mã 1101 (HTTP status code 400): không nhập token xác thực hoặc mã voucher,
  • mã 1102 (HTTP status code 403): token này không có trong cơ sở dữ liệu,
  • mã 1103 (HTTP status code 404): voucher với mã này không tồn tại,
  • mã 1104 (HTTP status code 401): đơn hàng mà voucher được phát hành chưa được thanh toán,
  • mã 1105 (HTTP status code 401): voucher đã được áp dụng,
  • mã 1106 (HTTP status code 401): voucher đã được hoàn tiền,
  • mã 1107 (HTTP status code 401): đơn hàng hoặc voucher đã bị hủy,
  • mã 1108 (HTTP status code 401): sản phẩm đã được đối tác quyết toán; không thể áp dụng thêm voucher,
  • mã 1109 (HTTP status code 401): hiệu lực của voucher cho sản phẩm này chưa bắt đầu.
  • mã 1111 (HTTP status code 500): lỗi nội bộ của máy chủ

Ví dụ yêu cầu 

https://www.zlavomat.sk/api/vouchercheck?code=1234-5677-77-111&token=123456789012345

Ví dụ phản hồi 

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Áp dụng voucher

  • hành động: voucherApply
  • tham số: token (bắt buộc; token duy nhất của đối tác), code (bắt buộc; mã voucher)

Thử áp dụng voucher với mã đã cho.

Để kiểm tra, có thể sử dụng số voucher thử nghiệm. Trong trường hợp đó, voucher sẽ không được áp dụng, nhưng hệ thống sẽ trả về phản hồi như thể đã áp dụng.

Định dạng dữ liệu phản hồi

Định dạng phản hồi hoàn toàn giống như khi kiểm tra tính hợp lệ của voucher.

Các trạng thái lỗi

  • mã 1201 (HTTP status code 400): không nhập token xác thực hoặc mã voucher,
  • mã 1202 (HTTP status code 403): token này không có trong cơ sở dữ liệu,
  • mã 1203 (HTTP status code 404): voucher với mã này không tồn tại,
  • mã 1204 (HTTP status code 401): đơn hàng mà voucher được phát hành chưa được thanh toán,
  • mã 1205 (HTTP status code 401): voucher đã được áp dụng,
  • mã 1206 (HTTP status code 401): voucher đã được hoàn tiền,
  • mã 1207 (HTTP status code 401): đơn hàng hoặc voucher đã bị hủy,
  • mã 1208 (HTTP status code 401): sản phẩm đã được đối tác quyết toán; không thể áp dụng thêm voucher,
  • mã 1209 (HTTP status code 401): hiệu lực của voucher cho sản phẩm này chưa bắt đầu.
  • mã 1211 (HTTP status code 500): lỗi nội bộ của máy chủ

Ví dụ yêu cầu 

https://www.zlavomat.sk/api/voucherapply?code=1234-5677-77-111&token=123456789012345

Ví dụ phản hồi 

{
 "result": true,
 "data": {
 "token": "123456789012345",
 "code": "1234567890-123",
 "voucherData": {
 "title": <název voucheru>,
 ...
 }
 },
 "error": {
 "code": 0,
 "message": null
 }
}

Lưu ý: Để sử dụng Partner API để trừ giá trị hoặc sản phẩm trong giỏ hàng, hãy cân nhắc bao gồm nhiều thuộc tính hơn của tham số voucherData. Điều này đặc biệt quan trọng khi bạn có nhiều sản phẩm đang chạy với giá trị sản phẩm khác nhau. Chúng tôi khuyến nghị sử dụng chủ yếu các thuộc tính product hoặc variant.

Quay lại danh sách bài viết

Những bài viết liên quan

Bên trên