API được sử dụng để chuyển thông tin về đơn đặt hàng giữa Slevomat 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 Slevomat gọi API của đối tác và đối tác gọi API Slevomat.
Các đơn đặt hàng được xuất sang API đối tác không còn có thể được xử lý trong giao diện đối tác Slevomat mà chỉ được xem. Việc xử lý các đơn 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 đều ở định dạng JSON.
Cung cấp API
Bạn có thể tìm thấy dữ liệu truy cập vào API trong tab Cài đặt trong giao diện đối tác của mình. Để lấy dữ liệu, bạn cần cung cấp URL gốc của phần đối tác của API để sử dụng theo hướng Slevomat → Đối tác, ví dụ:
https://example.com/slevomat-zbozi-api
Dữ liệu truy cập chỉ được hiển thị một lần khi API được cung cấp, vui lòng lưu nó cẩn thận.
Sau khi API được cung cấp, hệ thống sẽ bắt đầu xuất các đơn hàng mới được tạo sang API đó.
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 hàng hiện có khi API được cung cấp.
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 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 hàng được đánh dấu qua API" trong "Hành động hàng loạt với thực đơ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ý, phản hồi không có nội dung400 Bad Request
– yêu cầu không hợp lệ – nó có thể thiếu hoặc các tham số không hợp lệ liên quan đến thông số kỹ thuật403 Forbidden
– ủy quyền khách hàng 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 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ì (phiên bản mới có thể được triển khai hoặc có thể đang tiến hành tắt máy 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 cần sử dụng định dạng JSON.
Trường hợp có sai sót4xx
là 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ỉ ra lỗi máy chủ và yêu cầu có thể được lặp lại mà không thay đổi nó. Khi503
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
Lệnh 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 thanh toán mới |
2 | Xử lý bằng |
3 | Hàng đã được vận chuyển (chỉ áp dụng cho đơn hàng vận chuyển) |
4 | Nó đang được chuẩn bị cho việc thu thập cá nhân – ví dụ: nó đang được vận chuyển đến một 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 hàng và được khách hàng xác nhận |
số 8 | Khách hàng từ chối xác nhận đã nhận đơn hàng |
9 | Đơn hàng bị 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 bằng 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ừ “Đơn hàng mới thanh toán” bạn có thể vào thẳng “Hàng đã gửi”/ “Sẵn sàng nhận hàng” rồi đến “Đã giao cho khách – 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ẽ mang lại 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
Đối với mã HTTP 4×x, phản hồi luôn chứa khóastatus
(xem mặt số bên dưới) và các 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 không hợp lệ |
3 | Đơn hàng không tồn tại |
4 | Mục đặt hàng không tồn tại |
5 | Chuyển đơn 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 thông qua API |
9 | Để tự động đặt trạng thái “Hàng giao cho khách”, lô hàng phải được tự động đặ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 yêu cầu và phản hồi luôn được mô tả cho các điểm cuối cụ thể. Giá trị trong dấu ngoặc kép trừ khi có quy định khác""
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.
Giao Tiếp Slevomat ⇒ Đối Tác
Phần API này được triển khai ở phía đối tác và Slevomat gọi nó.
URL gốc API bắt buộc do đối tác cung cấp và phải ở dạng
https://www.example.com/slevomat-zbozi-api/v1
Yêu cầu ủy quyền
Khi API được bật, đối tác sẽ nhận đượcpartner_api_secret
, trong đó các yêu cầu đến được chứng minh là thực sự đến từ Slevomat.
Tham số này được truyền trong tiêu đề HTTPX-PartnerApiSecret
.
Giao diện thử nghiệm
Slevomat 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 thêm vào URL gốc do đối tác cung cấp khi cung cấp API-test
, vì vậy, như 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 mệnh lệnh rõ ràng.
Kiểm tra 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.slevomat.cz/test-zbozi-partner-api/v1/new-order
– Cập nhật hàng loạt ngày giao hàng dự kiếnhttps://www.slevomat.cz/test-zbozi-partner-api/v1/update-shipping-dates
– Thay đổi trạng thái đơn hàng thành “Đã giao cho khách – chờ khách hàng xác nhận”https://www.slevomat.cz/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.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup
– Xác nhận giao hànghttps://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery
– Từ chối tiếp quảnhttps://www.slevomat.cz/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery
– Hủy bỏhttps://www.slevomat.cz/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 API của đối tác sẽ được thực hiện bằng số đơn hàng này.
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 tiêu đềX-PartnerToken
VàX-ApiSecret
.
Trong cuộc gọi thử nghiệm API đối tác, hệ thống sẽ gửi tiêu đềX-PartnerApiSecret
cũng như khi giao thông đông đúc.
Dữ liệu được gửi cùng với đơn đặt 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 lệnh hủy, cần chỉ định một trường bằng JSON trong phần POST của yêu cầuitems
(ở cùng định dạng do API gửi), giao diện thử nghiệm sẽ xác thực và chuyển tiếp đến API đối tác ở cùng một biểu mẫu.
Đơn hàng mới
Yêu cầu chứa dữ liệu của đơn hàng mới được tạo.
Đơn đặt hàng luôn là duy nhấtslevomatId
. Nếu một bản sao xuất hiện trong APIslevomatId
, yêu cầu sẽ bị API đối tác bỏ qua (Slevomat đánh giá yêu cầu đầu tiên 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ồiHTTP 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 sự kiện, variantId
ID của biến thể đã mua.
Không bắt buộcinternalId
nghĩa là ID nội bộ được nhập cho biến thể hành động khi nó được tạo trong giao diện đối tác. Dùng để nhận diện sản phẩm trong hệ thống của đối tác.
TRONGbillingAddress
(địa chỉ thanh toán) chỉ cần có 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 thu hộ cá nhân thì địa chỉ cơ sở nơi khách hàng đến nhận hàng.
Chìa khóadelivery
.type
có thể thu được giá trịaddress
(giao hàng đến địa chỉ) hoặcpickup
(sưu tầm cá nhân).delivery
.name
có tên phương tiện vận tải hoặc tên cơ sở.
delivery
.expectedShippingDate
(ngày dự kiến giao hàng) adelivery
.expectedDeliveryDate
(ngày giao hàng ước tính) là ngày ở đị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 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ẽ nhận được một giá trịnull
.
POST /order/$discountId
{ "slevomatId": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "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": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShippingDate": "2021–08–27", "expectedDeliveryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }
POST /order/$discountId
{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "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–02", "expectedDeliveryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@example.com" }, "weight": 1.2 }
Cập nhật hàng loạt ngày 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, thay đổi hàng loạt ngày giao hàng của các đơn hàng đã chọn, 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 vận chuyển chứa trường ID đơn hàng và ngày vận chuyển dự kiến mới.
POST /update-shipping-dates
{ "expectedShippingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }
Hủy bỏ
Việc hủy bỏ có thể được thực hiện ở cả phía Slevomat và phía hệ thống đối tác. Điểm cuối này xử lý việc tạo yêu cầu hủy từ phía Slevomat và chuyển nó sang hệ thống của đối tác.
Tạo sự hủy bỏ các mặt hàng trong đơn 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ục riêng lẻ có thể bị hủy một phần (ví dụ: 1 trong số hai mục).
Thông báo 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 rằng họ đã thực sự nhận được hàng. Khi đơn hàng được đánh dấu là đã chấp 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 nhận hàng cá nhân"
Điểm cuối này được gọi khi trạng thái trước đó "Đang chuẩn bị thu thập cá nhân" được đặt bằngautoMarkReadyForPickup
true
và về phía Slevomat, đơn hàng được 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 – chờ khách hàng xác nhận"
Điểm cuối này được gọi khi trạng thái trước đó "Hàng đã gửi", "Đang chuẩn bị nhận cá nhân" hoặc "Sẵn sàng nhận cá nhân" được đặt bằngautoMarkDelivered
true
còn về phía Slevomat, đơn hàng được tự động chuyển sang trạng thái “Đã giao cho khách – chờ khách hàng xác nhận”.
POST /order/$slevomatId/mark-delivered
{}
Đối tác truyền thông ⇒ Slevomat
Phần API này được triển khai ở phía Slevomat và được hệ thống đối tác gọi.
URL gốc API là
https://www.slevomat.cz/zbozi-api/v1
thư viện PHP
Thư viện PHP đã chuẩn bị sẵn có thể được sử dụng để triển khai phần này của API. Thư viện hiện yêu cầu PHP 5.4 trở lên và giả định sử dụng Composer.
Hướng dẫn sử dụng thư viện và mã nguồn có trên GitHub .
Yêu cầu ủy quyền
Khi API được bật, đối tác sẽ nhận đượcpartner_token
Vàapi_secret
, điều này được thể hiện khi gọi API Slevomat.
Các tham số này được truyền trong 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.slevomat.cz/zbozi-api/v1-test
Mọi hành động đều có thể được thực hiện trên đó giống như trên một giao diện sắc nét.
Giao diện kiểm tra kiểm tra việc ủy quyền 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) cũng như tính hợp lệ của các nội dung yêu cầu đến (JSON). Ở 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 hàng thực. Do đó, nó không xác thực liệu đơn hàng có di 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 nhất định hay không. Khi biểu mẫu yêu cầu được ủy quyền và xác thực, giao diện kiểm tra luôn trả về mã thành công 200 hoặc 204.
Tạo yêu cầu hủy
Tạo sự hủy bỏ các mặt hàng trong đơn 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ục riêng lẻ có thể bị hủy một phần (ví dụ: 1 trong số hai mục).
Thông báo hủy (note
) Là tùy chọn.
POST /order/$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 "Hàng đã vận chuyển"
Thứ tự có thể được tham số hóaautoMarkDelivered
xác định sau thời gian giao hàng đã ấn định ("Thời gian từ khi gửi hàng đến khi giao") có tự động chuyển sang trạng thái "Đã giao cho khách – chờ khách hàng xác nhận" hay không.
Thư trả lời có chứa 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 "Chuẩn bị nhận hàng cá nhân"
Thứ tự có thể được tham số hóaautoMarkReadyForPickup
để xác định xem có nên tự động chuyển sang trạng thái "Sẵn sàng để nhận hàng cá nhân" sau khi hết thời gian từ khi vận chuyển hàng hóa đến khi giao hàng tại loại điểm thu gom nhất định hay không.
Thứ tự có thể được tham số hóaautoMarkDelivered
xác định xem, sau khoảng thời gian quy định về số ngày thu gom tại một loại điểm thu gom nhất định, có nên tự động chuyển từ trạng thái “Sẵn sàng cho cá nhân thu gom” sang trạng thái “Giao cho khách hàng – chờ khách hàng xác nhận hay khô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ề.
Thư trả lời có chứa ngày giao hàng dự kiến được cập nhật.
POST /order/$discountId/mark-sẵn sàng nhận hàng
{ "autoMarkReadyForPickup": true, "autoMarkDelivered": true }
Phản hồi 200
{ "expectedDeliveryDate": "2021–08–25" }
Thay đổi trạng thái đơn hàng thành "Sẵn sàng nhận hàng cá nhân"
Thứ tự có thể được tham số hóaautoMarkDelivered
xác định xem sau khoảng thời gian quy định số ngày thu gom tại một loại điểm thu gom 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 }
Thay đổi trạng thái đơn hàng thành "Đã giao cho khách – chờ khách hàng xác nhận"
POST /order/$slevomatId/mark-delivered
{}
Thay đổi địa chỉ giao hàng
Địa chỉ giao hàng chỉ có thể được thay đổi để giao hàng đến địa chỉ (tức là địa điểm nhận hàng cá nhân 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
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" }
03/02/2016
11/09/2015
20/10/2015
10/13/2015
24/09/2015
23/09/2015
18/09/2015
17/09/2015
09/10/2015
09/07/2015
9/1/2015
17/8/2015
2/8/2015: Phiên bản đầu tiên |