HƯỚNG DẪN ĐỐI TÁC
Čeština Němčina Angličtina Chorvatština Maďarština Polština Slovenština Vietnamština
Giới thiệu Hướng dẫn thực hành Các mặt hàng API hàng hóa bên thứ 3

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 thao tác trong giao diện đối tác Slevomat, chỉ được xem. Việc xử lý 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.

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 giữ cẩn thận.

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ô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ệ – có thể thiếu hoặc không hợp lệ các thông số liên quan đến đặc tả
  • 403 Forbidden – ủy quyền ứng dụng khách 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ì (một 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 JSON.

Trong trường hợp có lỗi4xx 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 cho biết 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

Đơ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  xử lý vớ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ụ: 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à 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.

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 mới giao thành công, từ "Đơn hàng mới thanh toán" bạn có thể chuyển thẳng sang "Đang đi"/ "Sẵn sàng thu cá nhân" rồi đến "Đã giao cho khách – đang chờ khách 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

Đố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  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 thiết lập trạng thái "Hàng đã giao cho khách", lô hàng phải được tự động thiết lập trạng thái "Hàng sẵn sàng để lấy"

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ể. Giá trị trong dấu ngoặc kép trừ khi có quy định khác"" 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 Slevomat ⇒ Đối tác

Phần này của API được triển khai ở phía đối tác và Slevomat gọi nó.

URL gốc của API bắt buộc do đối tác truyền đạt, URL 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 , mà các yêu cầu đến được chứng minh là thực sự đến từ Slevomat.

Tham số này được chuyển vào 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 , do đó, 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 dữ liệu thử nghiệm với các đơn đặt hàng sắc nét.

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: 

  • 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 vận chuyển dự kiến 
  • https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered
    – Chuyển trạng thái đơn hàng thành "Đã giao cho khách – chờ khách 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 cho bộ sưu tập 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 đặt hàng nào, các yêu cầu API đối tác được thực hiện 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 VàX-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 giao thông đông đúc.

Dữ liệu gửi đi 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ỉ ra một trường trong JSON trong phần 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ấtslevomatId . Nếu một bản sao xuất hiện trong APIslevomatId , API đối tác sẽ bỏ qua yêu cầu (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 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. 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 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 có địa chỉ của khách hàng, trong trường hợp nhận hàng cá nhân, địa chỉ của cơ sở nơi khách hàng 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 chứa tên phương tiện vận tải hoặc tên cơ sở.

delivery .expec­tedShippingDa­te (ngày giao hàng ước tính) 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 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": "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 đặt 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 bao gồm trường ID đơn đặt 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 ở phía Slevomat 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).

ghi chú hủy bỏ (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 đã thực sự nhận được. Khi đơn đặt hàng được đánh dấu là được chấp nhận, điểm cuối này đượ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 cho bộ sưu tập cá nhân"

Điểm cuối này đượ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ớiautoMarkRea­dyForPickuptrue và về phía Slevomat, đơ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" 

POST /order/$slevo­matId/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", "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 thiết lập vớiautoMarkDeli­veredtrue và bên phía Slevomat, đơn hàng đã tự động chuyển sang trạng thái "Đã giao cho khách – chờ khách xác nhận". 

POST /order/$slevo­matId/mark-delivered
{}

Đối tác truyền thông ⇒ Slevomat

Phần này của API được triển khai ở phía Slevomat và được gọi bởi hệ thống đối tác.

URL gốc của API là 

 https://www.slevomat.cz/zbozi-api/v1

thư viện PHP

Thư viện PHP đã chuẩn bị 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à 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 , đượ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

Tất cả các hành động có thể được gọi trên nó giống như trên một giao diện sắc nét.

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ó di chuyển giữa các trạng thái chính xác hay không và liệu đơn hàng đó có chứa các mục 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 trả về mã thành công 200 hoặc 204. 

Tạo hủy bỏ

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).

ghi chú hủy bỏ (note ) Là tùy chọn.

ĐĂNG /đơn hàng/$slevomatId/hủy 

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Chuyển 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"

Thứ tự có thể được tham số hóaautoMarkDelivered 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 

{ "autoMarkDeli­vered": true }

Phản hồi 200 

{ "expectedDeli­veryDate": "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"

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 đã đặ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ờ 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ề.

Câu trả lời chứa ngày giao hàng ước tính được cập nhật.

POST /order/$discountId/mark-getting-ready-for-pickup 

{ "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 cho bộ sưu tập 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 lấy hàng tại một loại điểm thu 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 }

Chuyển trạng thái đơn hàng thành "Đã giao cho khách – chờ khách 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à không thể thay đổi địa điểm nhận hàng cá nhân).

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
Nahoru