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

API đối tác Zlavomat.sk

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

API được sử dụng để chuyển thông tin về phiếu quà tặng giữa Zlavomat và hệ thống của đối tác kinh doanh. API cho phép đối tác xác minh tính hợp lệ của phiếu quà tặng trong hệ thống của họ và đổi phiếu quà tặng. Đối tác không cần phải sử dụng Giao diện Đối tác cho mục đích này.

Ví dụ sử dụng có thể có:

  • Khách hàng mua một phiếu mua hàng, với đ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ã, hiệu lực của phiếu mua hàng sẽ được kiểm tra ngay lập tức. Giá trị của phiếu mua hàng sau đó được trừ vào giỏ hàng của đối tác và phiếu mua hàng sẽ tự động được đổi tại Zlavomot.
  • Tương tự như vậy, tính hợp lệ của chứng từ cũng có thể được xác minh trong hệ thống đặt chỗ của đối tác hoặc khách hàng có thể tải khoản tín dụng đã mua có giá trị nhất định trực tiếp lên trang web của đối tác.

API Đối tác yêu cầu một mã thông báo duy nhất cho mỗi đối tác và được gửi kèm với mỗi yêu cầu. Nếu bạn muốn sử dụng API Đối tác, vui lòng liên hệ với nhà cung cấp của bạn/chúng tôi.

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

Điểm truy cập API nằm ở /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 chứng từ có thể trông như thế này, ví dụ:

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 tiêu đề 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 mục kết quả là đúng (trong trường hợp thành công) hoặc sai (trong trường hợp lỗi). Trong trường hợp có lỗi, mục lỗi sẽ chứa mã lỗi ( code ) và mô tả của nó ( message ). Ngoài thông tin trong trường lỗi, hệ thống sẽ trả về mã trạng thái HTTP tương ứng (400, 401, 403, 404) trong trường hợp có lỗi.

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

Tất cả các ngày đều theo định dạng YYYY-MM-DDTHH:MM:SSZ (ISO8601; ví dụ: 2011–01–01T10:10:10+02:00).

Xác minh tính hợp lệ của chứng từ

  • hành động: voucherCheck
  • tham số: mã thông báo (bắt buộc; mã thông báo đối tác duy nhất), mã (bắt buộc; mã phiếu giảm giá)

Có ba mã phiếu kiểm tra:

  • 1234–5677–77–111 (đã thanh toán, chưa sử dụng),
  • 2234–5688–88–222 (đã trả tiề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 những mã này, máy chủ sẽ trả về phản hồi tương ứng (trong trường hợp phiếu mua hàng đã thanh toán nhưng chưa sử dụng, máy chủ cũng sẽ trả về mẫu phiếu mua hàng và dữ liệu 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 chứng từ 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 mục biến thể hoặc variantName chứa ID hoặc tên của biến thể được sắp xếp của hành động, nếu hành động được chỉ định chứa các biến thể. Nếu không, cả hai thuộc tính đều là NULL .

Trạng thái lỗi

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

Ví dụ về một yêu cầu

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

Câu trả lời ví dụ

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

Đổi phiếu giảm giá

  • hành động: voucherApply
  • tham số: mã thông báo (bắt buộc; mã thông báo đối tác duy nhất), mã (bắt buộc; mã phiếu giảm giá)

Chúng tôi sẽ cố gắng đổi phiếu mua hàng có mã đã cho.

Bạn có thể sử dụng số phiếu kiểm tra cho mục đích kiểm tra. Trong trường hợp đó, phiếu sẽ không được đổi, nhưng hệ thống sẽ trả về phản hồi như thể việc này đã xảy ra.

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

Định dạng của câu trả lời hoàn toàn giống với trường hợp kiểm tra tính hợp lệ của chứng từ.

Trạng thái lỗi

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

Ví dụ về một yêu cầu

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

Câu trả lời ví dụ

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

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

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

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