HƯỚNG DẪN ĐỐI TÁC
Slovenština Čeština Němčina Angličtina Chorvatština Maďarština Polš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 để truyền thông tin về chứng từ giữa Máy chiết khấu và hệ thống của đối tác kinh doanh. Nó cho phép đối tác xác minh tính hợp lệ của các phiếu thưởng trong hệ thống của mình và đổi phiếu thưởng. Do đó, Đối tác không phải sử dụng Giao diện Đối tác cho mục đích này.

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

  • 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ờ có API, tính hợp lệ của chứng từ sẽ được kiểm tra ngay sau lần nhập này. Giá trị của nó sau đó được khấu trừ trong giỏ của đối tác, đồng thời phiếu thưởng được tự động đổi trong Máy chiết khấu.
  • Theo cách tương tự, tính hợp lệ của các chứng từ 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 lên tín dụng đã mua có giá trị nhất định trực tiếp trên trang web của đối tác.

API đối tác yêu cầu mã thông báo duy nhất cho mỗi đối tác và được gửi cùng 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 người bán của bạn/của chúng tôi.

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

Điểm truy cập API được đặt tại /api.

Định dạng của 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, tức 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 câu trả lời

Phản hồi của máy chủ luôn ở định dạng JSON với tiêu đề Loại nội dung tương ứng. Cấu trúc cơ bản của câu trả lờ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 có lỗi). Trong trường hợp có lỗi, mục lỗi chứa mã lỗi ( code ) và mô tả ( message ). Ngoài chỉ báo 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 ở đị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ã chứng từ)

Có ba mã chứng từ kiểm tra:

  • 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 chứng từ đã thanh toán và chưa sử dụng, nó cũng sẽ trả về dữ liệu hành động và chứng từ mẫu).

Đị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ặt hàng biến thể hoặc tên biến thể 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 đã cho có 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ừ chưa đượ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 đặt hàng trên cơ sở chứng từ được phát hành đã không được thanh toán,
  • mã 1105 (mã trạng thái HTTP 401): phiếu thưởng đã được sử dụng,
  • mã 1106 (mã trạng thái HTTP 401): phiếu thưởng đã được hoàn tiền,
  • mã 1107 (mã trạng thái HTTP 401): đơn đặt hàng hoặc chứng từ đã 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 chứng từ khác,
  • mã 1109 (mã trạng thái HTTP 401): hiệu lực của phiếu thưởng 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

Ví dụ về một câu trả lời

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

đổi phiếu mua hàng

  • 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ã chứng từ)

Một nỗ lực sẽ được thực hiện để đổi phiếu thưởng của mã đã cho.

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

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

Dạng 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ừ chưa đượ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 đặt hàng trên cơ sở chứng từ được phát hành đã không được thanh toán,
  • code 1205 (HTTP status code 401): voucher đã được sử dụng,
  • mã 1206 (mã trạng thái HTTP 401): phiếu thưởng đã được hoàn tiền,
  • mã 1207 (mã trạng thái HTTP 401): đơn đặt hàng hoặc chứng từ đã 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 chứng từ khác,
  • mã 1209 (mã trạng thái HTTP 401): hiệu lực của chứng từ 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

Ví dụ về một câu trả lời

{
 "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 xem xét bao gồm nhiều thuộc tính hơn của thông số voucherData. Nó đặc biệt quan trọng. tại thời điểm bạn có một số 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 chủ yếu sử dụng 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
Nahoru