API được sử dụng để truyền thông tin về các đơn đặt hàng giữa Máy giảm giá và hệ thống của đối tác kinh doanh. API yêu cầu triển khai giao tiếp hai chiều – hệ thống Zlávomat gọi API của đối tác và đối tác gọi API Zlávomat.
Các đơn đặt hàng được xuất sang API đối tác không còn có thể được thao tác trong giao diện đối tác của Złavomat, chỉ được xem. Việc thao tác các đơn đặt hàng đã xuất hiện chỉ có thể diễn ra thông qua API.
Tất cả các yêu cầu phải được thực hiện qua HTTPS và tất cả dữ liệu ở định dạng JSON.
khả năng truy cập API
Bạn có thể truy cập API từ tab Cài đặt trong giao diện đối tác của mình. Nếu muốn lấy dữ liệu, bạn cần nhập mã URL gốc của phần đối tác của API để sử dụng theo hướng Zľavomat → Đối tác, ví dụ:
https://example.com/slevomat-zbozi-apiDữ liệu truy cập sẽ chỉ được hiển thị khi API được cung cấp, hãy giữ cẩn thận.
Ngay sau khi API được cung cấp, hệ thống sẽ bắt đầu xuất các đơn đặt hàng mới được tạo sang nó.
Xuất dữ liệu ban đầu
Bạn có thể sử dụng tính năng xuất một lần sang CSV trong giao diện đối tác để chuyển các đơn đặt hàng hiện có khi API được cung cấp.
Khi bạn đã có các đơn đặt hàng hiện có (được tạo trước khi API được cung cấp) trong hệ thống của riêng mình và bạn muốn bắt đầu làm việc với chúng thông qua API, hãy sử dụng chức năng "Bắt đầu làm việc với các đơn đặt hàng được đánh dấu thông qua API" trong "Hành động hàng loạt với đơn đặt hàng".
Mô tả các phản hồi HTTP phổ biến
200 OK– yêu cầu đã được xử lý thành công204 No Content– yêu cầu đã được xử lý thành công, phản hồi không có nội dung400 Bad Request– yêu cầu không hợp lệ – có thể thiếu hoặc thông số không hợp lệ so với đặc tả403 Forbidden– ủy quyền ứng dụng khách không thành công404 Not Found– không tìm thấy điểm cuối hoặc dữ liệu được yêu cầu405 Method Not Allowed– điểm cuối không hỗ trợ phương thức HTTP này422 Unprocessable Entity– lỗi dự kiến trong quá trình xử lý yêu cầu (xem phần Trạng thái lỗi )500 Internal Server Error– xảy ra lỗi ở phía máy chủ502 Bad Gateway– xảy ra lỗi ở phía máy chủ503 Service Unavailable– máy chủ đang ở chế độ bảo trì (việc triển khai phiên bản mới hoặc tắt máy theo kế hoạch có thể đang diễn ra)504 Gateway Timeout– xảy ra lỗi ở phía máy chủ
Phản hồi HTTP 5×x không cần sử dụng định dạng JSON.
Trong trường hợp có lỗi4xx có lỗi trong yêu cầu gửi đi và phải được sửa trước khi thử lại.
sai lầm5xx chúng chỉ ra lỗi máy chủ và yêu cầu có thể được lặp lại mà không thay đổi nó. Trong trường hợp503 người gọi nên tôn trọng tiêu đề phản hồiRetry-After và chỉ lặp lại lần thử tiếp theo sau khi hết thời gian được chỉ định trong tiêu đề.
trạng thái đơn hàng
Đơn hàng luôn ở một trong các trạng thái sau:
| Giá trị trạng thái | Sự miêu tả |
| 1 | Đơn đặt hàng mới thanh toán |
| 2 | phục hồi |
| 3 | Đang trên đường (chỉ vận chuyển đơn đặt hàng) |
| 4 | Nó đang được chuẩn bị cho bộ sưu tập cá nhân – ví dụ: vận chuyển đến chi nhánh đang được tiến hành |
| 5 | Sẵn sàng cho bộ sưu tập cá nhân |
| 6 | Đã giao cho khách hàng – Đang chờ xác nhận của khách hàng |
| 7 | Giao hàng và xác nhận bởi khách hàng |
| số 8 | Khách hàng từ chối xác nhận đã nhận đơn hàng |
| 9 | đơn hàng đã hủy |
Khách hàng được thông báo về bất kỳ thay đổi nào về trạng thái qua e‑mail.
Đơn hàng không nhất thiết phải trải qua tất cả các trạng thái mới giao thành công, từ trạng thái “Đơn hàng mới thanh toán” có thể chuyển thẳng sang trạng thái “Đang đi”/ “Sẵn sàng thu tiền” rồi đến “Đã giao đến nơi”. khách hàng – chờ khách hàng xác nhận". Tuy nhiên, việc sử dụng tất cả các trạng thái dẫn đến thông tin tốt hơn cho khách hàng về tiến trình xử lý đơn hàng và chúng tôi khuyên bạn nên làm như vậy.
Trạng thái lỗi
Trong trường hợp mã HTTP 4×x, phản hồi luôn chứa khóastatus (xem mặt số bên dưới) và trườngmessages với văn bản mô tả lỗi.
| Giá trị trạng thái | Sự miêu tả |
| 1 | Yêu cầu không hợp lệ – giá trị bị thiếu hoặc không hợp lệ |
| 2 | Thông tin đăng nhập không hợp lệ |
| 3 | thứ tự không tồn tại |
| 4 | Mục đặt hàng không tồn tại |
| 5 | Chuyển đơn đặt hàng sang trạng thái trái phép |
| 6 | Hủy không hợp lệ – hủy nhiều mục hơn tồn tại |
| 7 | Một sai lầm khác |
| số 8 | Đơn hàng chưa được xuất sang API đối tác – không thể thao tác đơn hàng thông qua API |
| 9 | Để tự động cài đặt trạng thái “Hàng đã giao cho khách”, lô hàng phải được tự động cài đặt trạng thái “Hàng sẵn sàng nhận” |
Vật mẫu:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Loại dữ liệu
Các loại dữ liệu của các khóa riêng lẻ trong các yêu cầu và phản hồi luôn được mô tả cho các điểm cuối cụ thể. Trừ khi có quy định khác, giá trị nằm trong dấu ngoặc kép"" luôn luôn là một chuỗi bắt buộc. Trừ khi có quy định khác, giá trị số luôn là số nguyên bắt buộc.
Truyền thông Zlavomat ⇒ Đối tác
Phần này của API được triển khai ở phía đối tác và Zľavomat gọi nó.
URL gốc của API bắt buộc được đối tác chia sẻ, URL phải ở dạng
https://www.example.com/slevomat-zbozi-api/v1Ủy quyền yêu cầu
Khi API được bật, đối tác sẽ nhận đượcpartner_api_secret , chứng minh rằng các yêu cầu đến thực sự đến từ Złavomat.
Tham số này được chuyển vào tiêu đề HTTPX-PartnerApiSecret .
Giao diện thử nghiệm
Máy giảm giá bao gồm chức năng gọi API ở phía đối tác và hiển thị phản hồi. Nó được đính kèm với URL gốc do đối tác cung cấp khi cung cấp API-test , do đó, là một phần của thử nghiệm, API được gọi tại ví dụ:
https://example.com/slevomat-zbozi-api-testđể tránh trộn lẫn dữ liệu thử nghiệm với các đơn đặt hàng rõ ràng.
Thử nghiệm API đối tác được thực hiện bằng cách sử dụng các yêu cầu POST tới các địa chỉ sau:
– Đơn hàng mớihttps://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order
– Cập nhật hàng loạt dữ liệu vận chuyển dự kiếnhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates
– Chuyển trạng thái đơn hàng thành “Đã giao cho khách – chờ khách xác nhận”https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered
– Thay đổi trạng thái của đơn hàng thành "Sẵn sàng cho bộ sưu tập cá nhân"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup
– Xác nhận giao hànghttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery
– Từ chối tiếp quảnhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery
– Đã hủyhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel
Một phần của URL<orderId> thay thế bằng bất kỳ số đơn đặt hàng nào, các yêu cầu API đối tác sẽ được chuyển đổi bằng số đơn đặt hàng này.
Các yêu cầu cho giao diện thử nghiệm này cần được cấp quyền với các tiêu đềX-PartnerToken MộtX-ApiSecret .
Trong quá trình gọi thử API đối tác, hệ thống sẽ gửi tiêu đềX-PartnerApiSecret cũng như trong hoạt động sắc nét.
Dữ liệu được gửi cùng với đơn hàng mới mang tính chất thử nghiệm và được tạo ngẫu nhiên.
Trong trường hợp gửi yêu cầu hủy đơn hàng, cần chỉ định trường trong JSON trong nội dung POST của yêu cầuitems (ở cùng định dạng như được gửi bởi API), mà giao diện thử nghiệm xác thực và chuyển tiếp tới API đối tác ở cùng một định dạng.
đơn hàng mới
Yêu cầu chứa dữ liệu của đơn đặt hàng mới được tạo.
Đơn hàng luôn là duy nhấtzlavomatId . Nếu một bản sao đến trong APIzlavomatId , API đối tác sẽ bỏ qua yêu cầu (yêu cầu chuyển đầu tiên được Zľavomat đánh giá là không thành công và do đó chúng tôi lặp lại yêu cầu đó) và cũng phản hồi bằng HTTP 204.
created là một ngày ở định dạng ISO 8601, nghĩa làYYYY-MM-DD'T'HH:mm:ss+zz:zz .
productId chứa ID hành động, variantId ID của biến thể đã mua.
Không bắt buộcinternalId có nghĩa là ID nội bộ đã nhập cho biến thể hành động khi nó được tạo trong giao diện đối tác. Nó dùng để nhận diện sản phẩm trong hệ thống của đối tác.
TRONGbillingAddress (địa chỉ lập hóa đơn) chỉ cần tên (name ) của khách hàng.
TRONGshippingAddress (địa chỉ giao hàng) là một công ty tùy chọn (company ). Trường hợp giao hàng đến địa chỉshippingAddress chứa địa chỉ của khách hàng, trong trường hợp nhận hàng cá nhân, địa chỉ của doanh nghiệp nơi khách hàng nhận hàng.
Chìa khóadelivery .type có thể thu được các giá trịaddress (giao hàng tận nơi) hoặcpickup (sưu tầm cá nhân).delivery .name chứa tên của vận chuyển hoặc tên của hoạt động.
delivery .expectedShippingDate (ngày giao hàng ước tính) adelivery .expectedDeliveryDate (ngày giao hàng ước tính) là dữ liệu ở định dạngYYYY-MM-DD .
Chìa khóaweight chứa trọng lượng của đơn hàng tính bằng kilôgam. Trong trường hợp chúng tôi không biết trọng lượng của tất cả các mặt hàng của đơn đặt hàng, nó sẽ có giá trịnull .
POST /order/$discountId
{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShippingDate": "2021–09–08", "expectedDeliveryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }POST /order/$discountId
{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShippingDate": "2021–09–07", "expectedDeliveryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }Cập nhật hàng loạt dữ liệu vận chuyển dự kiến
Trong trường hợp người quản lý giao dịch, theo yêu cầu của đối tác, di chuyển dữ liệu vận chuyển của các đơn đặt hàng đã chọn hàng loạt, hệ thống sẽ thông báo cho API đối tác về bản cập nhật này.
Dữ liệu đã gửi chứa một trường có ID đơn đặt hàng và ngày giao hàng dự kiến mới.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }Đã hủy
Việc hủy bỏ có thể được thực hiện ở cả phía Thẻ Giảm giá và hệ thống đối tác. Điểm cuối này xử lý việc tạo yêu cầu hủy ở phía Zlavomat và việc chuyển giao yêu cầu đó sang hệ thống của đối tác.
Tạo một hủy bỏ các mặt hàng đặt hàng với số lượng được chỉ định. Nếu đơn hàng bị hủy toàn bộ, tất cả các mặt hàng có số lượng tương ứng sẽ được liệt kê.
Các mặt hàng riêng lẻ có thể bị hủy một phần (ví dụ: 1 mặt hàng trong số hai mặt hàng).
Lưu ý khi hủy (note ) Là tùy chọn.
POST /order/$slevomatId/cancel
{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }xác nhận giao hàng
Sau khi bạn đánh dấu đơn hàng là "Đã giao cho khách hàng", chúng tôi sẽ yêu cầu khách hàng xác nhận đã thực sự nhận được. Khi đơn đặt hàng được đánh dấu là đã nhận, điểm cuối này sẽ được gọi.
POST /order/$slevomatId/confirm-delivery
{}Từ chối tiếp quản
POST /order/$slevomatId/reject-delivery
{ "rejectionReason": "Důvod odmítnutí zákazníkem" }Thay đổi trạng thái đơn hàng thành "Sẵn sàng cho bộ sưu tập cá nhân"
Điểm cuối này sẽ được gọi khi trạng thái trước đó "Chuẩn bị cho bộ sưu tập cá nhân" được đặt vớiautoMarkReadyForPickuptrue và đơn hàng đã tự động chuyển sang trạng thái "Sẵn sàng cho bộ sưu tập cá nhân" trên trang Zľvomat
POST /order/$slevomatId/delivery-ready-for-pickup
{}Chuyển trạng thái đơn hàng thành "Đã giao cho khách – chờ khách xác nhận"
Điểm cuối này được gọi khi trạng thái trước đó "Đang trên đường", "Đang chuẩn bị cho bộ sưu tập cá nhân" hoặc "Sẵn sàng cho bộ sưu tập cá nhân" được đặt vớiautoMarkDeliveredtrue và đơn hàng đã tự động chuyển sang trạng thái "Đã giao cho khách – chờ khách xác nhận" trên trang Zľavomat.
POST /order/$slevomatId/mark-delivered
{}Đối tác truyền thông ⇒ Máy giảm giá
Phần này của API được triển khai ở phía Zľavomat và được gọi bởi hệ thống đối tác của nó.
URL gốc của API là
https://www.zlavomat.sk/zbozi-api/v1thư viện PHP
Để triển khai phần này của API, có thể sử dụng thư viện PHP đã chuẩn bị. Kničnica hiện yêu cầu phiên bản PHP 5.4 trở lên và sử dụng công cụ Composer.
Hướng dẫn sử dụng thư viện và mã nguồn có trên GitHub .
Ủy quyền yêu cầu
Khi API được bật, đối tác sẽ nhận đượcpartner_token Mộtapi_secret , điều này đã được chứng minh khi gọi API Zlavomat.
Các thông số này được bán trong tiêu đềX-PartnerToken MộtX-ApiSecret .
Giao diện thử nghiệm
URL gốc của giao diện thử nghiệm là
https://www.zlavomat.sk/zbozi-api/v1-testCó thể gọi tất cả các hành động trên đó như trên giao diện khác.
Giao diện thử nghiệm kiểm tra ủy quyền của các yêu cầu (tính chính xác của mã thông báo đối tác và bí mật API) và tính hợp lệ của các nội dung yêu cầu đến (JSON). Về những khía cạnh này, nó hoạt động giống hệt với API sắc nét.
Tuy nhiên, giao diện thử nghiệm không hoạt động với các đơn đặt hàng thực. Do đó, nó không xác thực liệu đơn hàng có chuyển giữa các trạng thái chính xác hay không và liệu nó có chứa các mặt hàng có ID đã cho hay không. Sau khi biểu mẫu yêu cầu được ủy quyền và xác thực, giao diện thử nghiệm luôn phản hồi với mã thành công là 200 hoặc 204.
Tạo hủy bỏ
Tạo hủy các mặt hàng đặt hàng với số lượng được chỉ định. Nếu toàn bộ đơn đặt hàng bị hủy, tất cả các mặt hàng có số lượng yêu cầu sẽ được liệt kê.
Các mặt hàng riêng lẻ có thể bị hủy một phần (ví dụ: 1 mặt hàng trong số hai mặt hàng).
Lưu ý khi hủy (note ) Là tùy chọn.
ĐĂNG /đơn hàng/$slevomatId/hủy
{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }Thay đổi trạng thái đơn hàng thành "Đang xử lý"
POST /order/$slevomatId/mark-pending
{}Thay đổi trạng thái đơn hàng thành "Đang thực hiện"
Nó là một tham số khi đặt hàngautoMarkDelivered xác định xem sau khoảng thời gian giao hàng đã thiết lập (“Thời gian từ khi gửi hàng đến khi giao hàng”) có tự động chuyển sang trạng thái “Đã giao cho khách hàng – chờ khách hàng xác nhận hay không”.
Câu trả lời chứa ngày giao hàng ước tính được cập nhật.
POST /order/$slevomatId/mark-en-route
{ "autoMarkDelivered": true }Phản hồi 200
{ "expectedDeliveryDate": "2021–08–25" }Thay đổi trạng thái đơn hàng thành "Đang chuẩn bị cho bộ sưu tập cá nhân"
Nó là một tham số khi đặt hàngautoMarkReadyForPickup xác định xem sau khoảng thời gian từ khi gửi hàng đến khi giao hàng tại một loại điểm thu gom nhất định, hàng hóa có tự động chuyển sang trạng thái "Sẵn sàng để nhận hàng cá nhân" hay không.
Nó là một tham số khi đặt hàngautoMarkDelivered xác định xem, sau khoảng thời gian đã đặt về số ngày để nhận tại một loại điểm thu nhất định, nó có tự động chuyển từ trạng thái "Sẵn sàng để nhận cá nhân" sang trạng thái "Đã giao cho khách hàng – chờ xác nhận của khách hàng “.
Sự kết hợp của các tham sốautoMarkReadyForPickup sai mộtautoMarkDelivered đúng là không được phép. Trong trường hợp này, mã lỗi 9 được trả về.
Câu trả lời chứa ngày giao hàng ước tính được cập nhật.
POST /order/$slevomatId/mark-getting-ready-for-pickup
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }Phản hồi 200
{ "expectedDeliveryDate": "2021–09–06" }Thay đổi trạng thái đơn hàng thành "Sẵn sàng cho bộ sưu tập cá nhân"
Nó là một tham số khi đặt hàngautoMarkDelivered xác định xem sau thời hạn quy định số ngày lấy hàng tại loại điểm lấy hàng nhất định có tự động chuyển sang trạng thái “Đã giao cho khách hàng – chờ khách hàng xác nhận hay không”.
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Chuyển trạng thái đơn hàng thành "Đã giao cho khách – chờ khách xác nhận"
POST /order/$slevomatId/mark-delivered
{}Thay đổi địa chỉ giao hàng
Chỉ có thể thay đổi địa chỉ giao hàng trong quá trình giao hàng đến địa chỉ (nghĩa là không thể thay đổi địa điểm nhận hàng tương tự).
Tất cả các phím ngoại trừcompany là bắt buộc.
Giá trị hợp lệ cho khóastate họ đangcz (Cộng hòa Séc) ask (Slovakia).
POST /order/$slevomatId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }