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 Slevomat.cz API đối tác

Slevomat.cz API đối tác

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

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

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

  • Khách hàng mua một phiếu mua hàng, trong đó điều kiện để cung cấp dịch vụ là nhập mã vào trang web của đối tác khi tạo đơn hàng. Nhờ có API, sau mục nhập này, hiệu lực của chứng từ sẽ được kiểm tra ngay lập tức. Giá trị của phiếu mua hàng sau đó sẽ được khấu trừ khỏi giỏ hàng của đối tác và phiếu mua hàng sẽ tự động được đổi tại Slevomat.
  • Tương tự như vậy, bạn cũng có thể xác minh tính hợp lệ của chứng từ trong hệ thống đặt chỗ của đối tác hoặc cho phép khách hàng 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. Để sử dụng API đối tác, vui lòng liên hệ với nhà cung cấp của bạn/của 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 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:

https://www.slevomat.cz/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 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 xảy ra lỗi, mục lỗi sẽ chứa mã lỗi ( code ) và mô tả của lỗi ( 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 xảy ra 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ả ngày tháng đề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ừ

(không áp dụng cho các phiếu giảm giá trong danh mục du lịch)

  • sự kiện: 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 (đã 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 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 và chưa sử dụng, máy chủ cũng trả về mẫu phiếu mua hàng và dữ liệu sự kiện).

Đị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>,
 "reservationTime": <Termín rezervace, pokud je voucher rezervován; datum a čas>
}

Trạng thái lỗi

  • mã 1101 (mã trạng thái HTTP 400): mã 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ở đó chứng từ được phát hành chưa được thanh toán,
  • mã 1105 (mã trạng thái HTTP 401): phiếu mua hàng đã được đổi,
  • mã 1106 (mã trạng thái HTTP 401): phiếu mua hàng đã được hoàn lại,
  • 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 này đã được tính phí cho đối tác; không thể sử 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 chương trình khuyến mãi 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ộ,
  • mã 1112 (mã trạng thái HTTP 403): phiếu mua hàng chỉ được đổi thông qua đặt chỗ

Yêu cầu ví dụ

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

Câu trả lời mẫu

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

Đổi phiếu giảm giá

(không áp dụng cho voucher du lịch)

  • 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á)

Họ sẽ cố gắng đổi phiếu mua hàng để lấy mã đã cho.

Có thể sử dụng số phiếu dự thi cho mục đích thử nghiệm. Trong trường hợp này, phiếu mua hàng sẽ không được đổi, nhưng hệ thống sẽ trả về phản hồi như thể phiếu đã được đổi.

Đị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 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ở đó chứng từ được phát hành chưa được thanh toán,
  • mã 1205 (mã trạng thái HTTP 401): phiếu mua hàng đã được đổi,
  • mã 1206 (mã trạng thái HTTP 401): phiếu mua hàng đã được hoàn lại,
  • 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 này đã được tính phí cho đối tác; không thể sử 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 chương trình khuyến mãi 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ộ
  • mã 1212 (mã trạng thái HTTP 403): phiếu mua hàng chỉ được đổi thông qua đặt chỗ

Yêu cầu ví dụ

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

Câu trả lời mẫu

{
 "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 đưa nhiều thuộc tính của tham số voucherData. Điều này đặc biệt quan trọng khi bạn đang có nhiều chương trình khuyến mãi với nhiều giá trị sản phẩm khác nhau. Chúng tôi khuyên bạn nên sử dụng đặc biệt 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