API hàng hóa bên thứ 3

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

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ông
  • 204 No Content – yêu cầu đã được xử lý, phản hồi không có nội dung
  • 400 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ật
  • 403 Forbidden – ủy quyền khách hàng không thành công
  • 404 Not Found – không tìm thấy điểm cuối hoặc dữ liệu được yêu cầu
  • 405 Method Not Allowed – điểm cuối không hỗ trợ phương thức HTTP này
  • 422 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_se­cret , 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:

  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order
     – Đơn hàng mới
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 
     – Cập nhật hàng loạt ngày giao hàng dự kiến
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 
     – 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.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 
     – Thay đổi trạng thái đơn hàng thành “Sẵn sàng nhận hàng cá nhân”
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 
     – Xác nhận giao hàng
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 
     – Từ chối tiếp quản
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 
     – Hủy bỏ

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-PartnerTokenX-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 .expec­tedShippingDa­te (ngày dự kiến ​​giao hàng) adelivery .expec­tedDeliveryDa­te (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", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.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ě", "expectedShip­pingDate": "2021–09–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.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
{ "expectedShip­pingDate": "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/$slevo­matId/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/$slevo­matId/confirm-delivery
{}

Từ chối tiếp quản

POST /order/$slevo­matId/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ằngautoMarkRea­dyForPickuptrue 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/$slevo­matId/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ằngautoMarkDeli­veredtrue 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/$slevo­matId/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_tokenapi_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-PartnerTokenX-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

{ "autoMarkDeli­vered": true }

Phản hồi 200

{ "expectedDeli­veryDate": "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óaautoMarkReady­ForPickup để 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ốautoMarkReady­ForPickup 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

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Phản hồi 200

{ "expectedDeli­veryDate": "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/$slevo­matId/mark-ready-for-pickup
{ "autoMarkDeli­vered": 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/$slevo­matId/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/$slevo­matId/update-shipping-address
{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }

Nhật ký thay đổi

Quay lại danh sách bài viết

Những bài viết liên quan


Bên trên