API được sử dụng để truyền thông tin về đơn hàng giữa Discount Machine 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 Discount Machine gọi API của đối tác và đối tác gọi API Discount Machine.
Các đơn hàng đã xuất sang API đối tác không còn có thể được thao tác trong giao diện đối tác Zlavomat nữa, mà chỉ có thể được xem. Các đơn hàng đã xuất giờ chỉ có thể được thao tác thông qua API.
Mọi yêu cầu phải được thực hiện qua HTTPS và tất cả dữ liệu đều ở định dạng JSON.
Khả năng truy cập API
Bạn có thể truy cập API trong tab Cài đặt của giao diện đối tác. Để truy xuất dữ liệu, bạn phải nhập URL gốc của phần đối tác trong API để sử dụng theo hướng Zlavomat → Đối tác, ví dụ:
https://example.com/slevomat-zbozi-apiDữ liệu truy cập sẽ chỉ được hiển thị khi truy cập API, vì vậy hãy giữ an toàn.
Khi API được cung cấp, hệ thống sẽ bắt đầu xuất các đơn hàng mới tạo vào đó.
Xuất dữ liệu ban đầu
Để chuyển các đơn hàng hiện có tại thời điểm API được cung cấp, bạn có thể sử dụng chức năng xuất một lần sang CSV trong giao diện đối tác.
Khi bạn đã có các đơn hàng hiện có (được tạo trước khi API được cung cấp) trong hệ thống của mình và bạn muốn bắt đầu làm việc với các đơn hà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 hàng đã đánh dấu thông qua API" trong menu "Hành động hàng loạt với đơn 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ể có các tham số bị thiếu hoặc không hợp lệ so với thông số kỹ thuật403 Forbidden– ủy quyền máy 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 giao thức HTTP này422 Unprocessable Entity– lỗi dự kiến trong khi 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ì (có thể đang triển khai phiên bản mới hoặc thời gian ngừng hoạt động theo kế hoạch)504 Gateway Timeout– đã xảy ra lỗi ở phía máy chủ
Phản hồi HTTP 5×x không nhất thiết phải 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à cần phải sửa lỗi trước khi thử lại.
Lỗi5xx chỉ ra lỗi máy chủ và yêu cầu có thể được lặp lại mà không cần thay đổi nó. Trong trường hợp503 người gọi phải 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 thời gian được chỉ định trong tiêu đề đã trôi qua.
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 hàng mới thanh toán |
| 2 | Đang được chuẩn bị. |
| 3 | Trên đường đi (chỉ những đơn hàng có kèm phí vận chuyển) |
| 4 | Đang chuẩn bị cho việc nhận hàng cá nhân – ví dụ: đang vận chuyển đến chi nhá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 và xác nhận bởi khách hàng |
| 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 sẽ được thông báo về bất kỳ thay đổi nào về trạng thái qua email.
Một đơn hàng không nhất thiết phải trải qua tất cả các trạng thái để được giao thành công; từ trạng thái "Đơn hàng mới thanh toán", bạn có thể chuyển thẳng đến "Đang vận chuyển" / "Sẵn sàng để nhận hàng" rồi đến "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng". Tuy nhiên, việc sử dụng tất cả các trạng thái sẽ giúp khách hàng nắm rõ hơn về tiến độ đơn hàng và chúng tôi khuyến nghị 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 một khóastatus (xem danh sách mã bên dưới) và trườngmessages có mô tả lỗi bằng văn bản.
| 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 đơn hàng không tồn tại |
| 5 | Lệnh chuyển sang trạng thái không được phép |
| 6 | Hủy không hợp lệ – hủy nhiều mục hơn số lượng có sẵn |
| 7 | Một lỗi khác |
| 8 | Đơn hàng vẫn 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 đặt trạng thái thành "Hàng đã giao cho khách hàng", cần phải tự động đặt trạng thái lô hàng thành "Hàng sẵn sàng để nhận" |
Vật mẫu:
{ "status": 3, "messages": [ "Order #1234 was not found." ] }Kiểu dữ liệu
Kiểu dữ liệu của từng khóa riêng lẻ trong 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ó ghi chú khác, giá trị trong dấu ngoặc kép"" luôn là một chuỗi bắt buộc. Trừ khi có quy định khác, giá trị số luôn là một số nguyên bắt buộc.
Máy giảm giá truyền thông ⇒ Đối tác
Phần này của API được triển khai ở phía đối tác và Zlavovamat gọi phần đó.
URL gốc API bắt buộc sẽ được đối tác chia sẻ, URL này 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 , điều này chứng minh rằng các yêu cầu đến thực sự đến từ Zlavomat.
Tham số này được truyề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 từ phía đối tác và hiển thị phản hồi. URL gốc do đối tác chỉ định khi cung cấp API sẽ được đính kèm vào-test , vì vậy, như một phần của thử nghiệm, API được gọi đến, 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 lệnh thực tế.
Kiểm tra API đối tác được thực hiện bằng cách sử dụng yêu cầu POST tới các địa chỉ sau:
– Trật tự mớihttps://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order
– Cập nhật hàng loạt ngày giao hàng dự kiếnhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates
– Thay đổi trạng thái đơn hàng thành "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng"https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered
– Thay đổi trạng thái đơn hàng thành "Sẵn sàng để nhận hàng 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 chấp nhậnhttps://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery
– Hủy bỏhttps://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 hàng nào, các yêu cầu tới API đối tác sẽ được thực hiện bằng số đơn hàng này.
Các yêu cầu đối với giao diện thử nghiệm này cần phải được ủy quyền bằng các tiêu đềX-PartnerToken VàX-ApiSecret .
Khi kiểm tra lệnh gọi API của đối tác, hệ thống sẽ gửi một tiêu đềX-PartnerApiSecret giống như trong hoạt động thực tế.
Dữ liệu được gửi kèm theo đơn hàng mới có 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 phải bao gồm trường JSON trong nội dung yêu cầu POST.items (cùng định dạng với định dạng mà API gửi), giao diện thử nghiệm sẽ xác thực và chuyển tiếp đến API đối tác theo cùng định dạng.
Trật tự mới
Yêu cầu chứa dữ liệu của đơn hàng mới được tạo.
Đơn hàng luôn luôn duy nhấtzlavomatId Nếu có bản sao trong APIzlavomatId , API đối tác phải bỏ qua yêu cầu (yêu cầu đầu tiên do Zľavomat thực hiện được đánh giá là không thành công và do đó chúng tôi sẽ lặp lại yêu cầu đó) và cũng phản hồi bằng HTTP 204.
created là ngày theo định dạng ISO 8601, tức 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 là ID nội bộ được nhập cho biến thể hành động khi tạo biến thể đó trong giao diện đối tác. ID này được sử dụng để nhận dạng sản phẩm trong hệ thống đối tác.
TRONGbillingAddress (địa chỉ thanh toán) chỉ cần tên (là bắt buộc)name ) của khách hàng.
TRONGshippingAddress (địa chỉ giao hàng) là một công ty tùy chọn (company ). Trong 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 đến lấy hàng trực tiếp, là địa chỉ của cửa hàng nơi khách hàng sẽ đến lấy hàng.
Chìa khóadelivery .type có thể đảm nhận các giá trịaddress (giao hàng đến địa chỉ) hoặcpickup (bộ sưu tập cá nhân).delivery .name chứa tên của phương tiện vận chuyển hoặc tên của hoạt động.
delivery .expectedShippingDate (ngày dự kiến giao hàng) vàdelivery .expectedDeliveryDate (ngày giao hàng dự kiến) là dữ liệu theo đị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. Nếu chúng ta không biết trọng lượng của tất cả các mặt hàng trong đơn hàng, nó sẽ lấy giá trịnull .
POST /order/$slevomatId
{ "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/$slevomatId
{ "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 ngày giao hàng dự kiến
Nếu người quản lý giao dịch, theo yêu cầu của đối tác, di chuyển ngày giao hàng của các đơn hàng đã chọn theo số lượng lớn, hệ thống sẽ thông báo cho API của đối tác về bản cập nhật này.
Dữ liệu được gửi bao gồm một trường có ID đơn 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 bỏ
Có thể tạo lệnh hủy trên cả phía Zlavomat và hệ thống đối tác. Điểm cuối này xử lý việc tạo lệnh hủy trên phía Zlavomat và chuyển lệnh hủy sang hệ thống đối tác.
Tạo lệnh hủy đơn hàng với số lượng đã chỉ định. Nếu hủy toàn bộ đơn hàng, 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ũng có thể bị hủy một phần (ví dụ: 1 trong 2 mặt hàng).
Ghi chú hủy bỏ (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 rằng họ đã thực sự nhận được đơn hàng. Khi đơn 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 chấp nhậ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 để nhận hàng cá nhân"
Điểm cuối này sẽ được gọi nếu trạng thái trước đó "Đang chuẩn bị cho bộ sưu tập cá nhân" được đặt thànhautoMarkReadyForPickuptrue và về phía Zlavomat, đơn hàng đã tự động chuyển sang trạng thái "Sẵn sàng để nhận hàng cá nhân"
POST /order/$slevomatId/delivery-ready-for-pickup
{}Thay đổi trạng thái đơn hàng thành "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng"
Điểm cuối này sẽ được gọi nếu trạng thái trước đó là "Đang trên đường", "Đang chuẩn bị nhận cá nhân" hoặc "Sẵn sàng nhận cá nhân" được đặt thànhautoMarkDeliveredtrue và về phía Máy giảm giá, đơn hàng đã tự động chuyển sang trạng thái "Đã giao cho khách hàng – đang chờ khách hàng xác nhận".
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 hệ thống đối tác gọi.
URL gốc của API là
https://www.zlavomat.sk/zbozi-api/v1Thư viện PHP
Để triển khai trang API này, bạn có thể sử dụng thư viện PHP có sẵn. Thư viện hiện yêu cầu PHP phiên bản 5.4 trở lên và giả định sử dụng công cụ Composer.
Hướng dẫn và mã nguồn của thư việ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 Vàapi_secret , được sử dụng để chứng minh khi gọi API Zlavomat.
Các tham số này được truyền vào tiêu đềX-PartnerToken VàX-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 giao diện này như trên giao diện khác.
Giao diện thử nghiệm kiểm tra tính xác thực 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 nội dung yêu cầu đến (JSON). Về các khía cạnh này, giao diện thử nghiệm hoạt động giống hệt với API trực tiếp.
Tuy nhiên, giao diện kiểm tra không hoạt động với các đơn hàng thực tế. Nó không xác thực liệu đơn hàng có đang chuyển đổi 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 ủy quyền và xác thực biểu mẫu yêu cầu thành công, giao diện kiểm tra luôn phản hồi với mã thành công là 200 hoặc 204.
Tạo lệnh hủy
Tạo các mặt hàng hủy đơn hàng với số lượng cụ thể. Nếu toàn bộ đơn hàng cần hủy, 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ũng có thể bị hủy một phần (ví dụ: 1 trong 2 mặt hàng).
Ghi chú hủy bỏ (note ) là tùy chọn.
POST /order/$slevomatId/cancel
{ "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 trên đường"
Khi đặt hàng, tham số làautoMarkDelivered xác định xem trạng thái có tự động chuyển sang "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng" sau thời gian vận chuyển đã đặt ("Thời gian từ khi giao hàng đến khi nhận hàng") hay không
Phản hồi bao gồm ngày giao hàng dự kiến đượ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ị nhận hàng cá nhân"
Khi đặt hàng, tham số làautoMarkReadyForPickup xác định xem trạng thái có tự động chuyển sang "Sẵn sàng để nhận cá nhân" hay không sau khi thời gian từ lúc vận chuyển đến lúc giao hàng cho một loại điểm nhận hàng nhất định đã trôi qua.
Khi đặt hàng, tham số làautoMarkDelivered xác định xem trạng thái có tự động chuyển từ "Sẵn sàng để nhận hàng" sang "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng" sau số ngày quy định để nhận hàng tại một loại điểm nhận hàng nhất định hay không.
Kết hợp tham sốautoMarkReadyForPickup sai vàautoMarkDelivered Không cho phép trả về true. Trong trường hợp này, mã lỗi 9 sẽ được trả về.
Phản hồi bao gồm ngày giao hàng dự kiến đượ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 để nhận hàng cá nhân"
Khi đặt hàng, tham số làautoMarkDelivered xác định xem trạng thái có tự động chuyển sang "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng" sau số ngày nhất định để nhận hàng tại một loại điểm nhận hàng nhất định hay không.
POST /order/$slevomatId/mark-ready-for-pickup
{ "autoMarkDelivered": true }Thay đổi trạng thái đơn hàng thành "Đã giao cho khách hàng – đang chờ xác nhận của khách hàng"
POST /order/$slevomatId/mark-delivered
{}Thay đổi địa chỉ giao hàng
Địa chỉ giao hàng chỉ có thể thay đổi khi giao hàng đến địa chỉ đó (tức là địa điểm nhận hàng tương tự không thể thay đổi).
Tất cả các phím ngoại trừcompany là bắt buộc.
Giá trị hợp lệ cho khóastate làcz (Cộng hòa Séc) vàsk (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" }