Checkout cho Miva

Trong vòng 24 giờ sau khi đăng ký, một đại diện onboarding chuyên dụng sẽ liên hệ với bạn để bắt đầu quá trình tích hợp được tùy chỉnh.

Quan trọng: Các bước được liệt kê dưới đây được cung cấp cho tham khảo của bạn và bạn sẽ được hướng dẫn qua chúng bởi đại diện onboarding của bạn.

1. Tải xuống mô-đun từ Miva App Store, hoặc yêu cầu tệp zonos.mvc trực tiếp từ Zonos.
2. Trong trang quản trị Miva của bạn, đi tới Domain Settings -> Modules -> Add Module, tải lên tệp zonos.mvc, sau đó nhấp vào Add.

3. Đi tới Settings -> Modules, tìm Zonos, và nhấp vào Install. Xác nhận nó hiển thị là Installed.

Trong Miva, đi tới Users -> API Tokens và nhấp vào Add API Token. Định cấu hình như sau:

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- nhấp vào Generate để tạo khóa ký
• Timestamp: Require Timestamp Within 30 seconds

Trên màn hình tiếp theo, bật Customer Service & Sales để cho phép token tạo và sửa đổi đơn hàng. Nhấp vào Save.

Điều hướng đến mô-đun Checkout trong Miva bằng cách đi tới Miva -> Utility Settings -> Zonos, sau đó điền vào các trường sau:

1. Store ID: Sao chép Zonos account number của bạn từ Dashboard -> Settings -> Account -> Integrations.
2. Zonos API Key: Khóa API bí mật của bạn (không bao giờ chia sẻ khóa này).
3. Zonos Public Key: Khóa công khai của bạn.
4. Store Currency: Đơn vị tiền tệ cơ bản của cửa hàng bạn (ví dụ: USD).
5. Environment: Chọn Live cho môi trường sản xuất hoặc Test để kiểm tra.
6. Checkout Button Selector: Bộ chọn CSS cho nút thanh toán của bạn (ví dụ: a[href*="checkout.html"]).
7. Hidden Selectors: Để ẩn các tùy chọn thanh toán nội địa và các chi tiết khác có thể không liên quan đến khách hàng quốc tế.
8. Import Orders: Đánh dấu để tự động nhập các đơn hàng Zonos đã hoàn thành vào trang quản trị Miva. Điều này yêu cầu webhook phải được đăng ký ở bước tiếp theo.

Nhấp vào Update ở phía trên bên phải để lưu trước khi tiếp tục.

Đơn hàng được nhập qua webhook trong mô-đun 10.x. Các phiên bản mô-đun trước đây sử dụng URL/endpoint thành công đơn hàng thay thế.

Sau khi lưu cài đặt của bạn, nhấp vào Register Webhooks. Thao tác này kết nối cửa hàng của bạn với Zonos để các đơn hàng đã hoàn thành được tự động nhập, việc hủy đơn được đồng bộ hóa, và các cập nhật vận chuyển được đẩy trở lại Miva.

Webhook phải được đăng ký trước khi việc nhập đơn hàng, đồng bộ hủy đơn và cập nhật vận chuyển hoạt động. Hộp kiểm Import Orders yêu cầu webhook phải được đăng ký.

Cuộn xuống để hoàn thành các trường còn lại:

1. Miva API Token: Access Token từ API Token bạn đã tạo trong bước Tạo API token.
2. Miva API Signature: Signing Key từ cùng mục API Token đó.
3. Image Type: Chọn kích thước hình ảnh sản phẩm nào được hiển thị trong Zonos checkout (Main phù hợp với hầu hết các cửa hàng).
4. Additional Field Mappings: Tùy chọn ánh xạ các trường tùy chỉnh của Miva với các thuộc tính/metadata của Zonos (màu sắc, chất liệu, kích thước, v.v.). Chúng tôi khuyên bạn ánh xạ mã HS nếu bạn đã đặt mã HS cụ thể sản phẩm trong danh sách sản phẩm Miva của bạn. Điều này không bắt buộc để tạo ra báo giá thuế và phí vì chúng tôi có thể sử dụng mã HS cụ thể sản phẩm mà bạn đã nhập vào Catalog hoặc sử dụng mã HS mặc định của bạn. Tuy nhiên, điều này được khuyến nghị; độ chính xác của các tính toán Landed cost sẽ tăng lên đáng kể với các sản phẩm được phân loại chính xác. Để ánh xạ một trường trong Miva, hãy tạo một trường tùy chỉnh cho mã HS, sau đó ánh xạ nó dưới Utility Settings -> Zonos.

Nhấp vào Update để lưu tất cả cài đặt.

Bây giờ bạn đã thiết lập tài khoản và mô-đun của mình, bạn đã sẵn sàng để kiểm tra bằng cách thực hiện các bước sau:

• Kiểm tra báo giá vận chuyển
• Đặt đơn hàng kiểm tra trên trang web của bạn
• Kiểm tra luồng đơn hàng thông qua các hệ thống của bạn
• Kiểm tra trang web của bạn

Tìm hiểu cách chạy các bài kiểm tra này. Bạn sẽ cần đặt trường Environment của mô-đun thành Test trong khi kiểm tra.

Sau khi hoàn thành kiểm tra, bạn hiện đã sẵn sàng để hoạt động! Đặt Environment thành Live, xác nhận thông tin đăng nhập Zonos của bạn chính xác, và đảm bảo webhook đã được đăng ký trên cửa hàng trực tiếp của bạn.

1. Đi tới dashboard.zonos.com -> Hello -> Hello Settings.
2. Bật Currency behavior.
3. Nhập bộ chọn CSS nhắm đến các phần tử giá sản phẩm của bạn (ví dụ: .price).

Zonos Hello sẽ tự động chuyển đổi và hiển thị giá bằng đơn vị tiền tệ địa phương của người mua khi tính năng này được bật.

Kích thước vận chuyển, quốc gia xuất xứ và mã HS được đặt trong danh mục Miva sẽ tự động ánh xạ sang Zonos và được sử dụng cho báo giá Landed cost / vận chuyển nếu đã được điền. Không cần ánh xạ bổ sung nào để định cấu hình.

Nếu cửa hàng của bạn bán các sản phẩm có thể tùy chỉnh mà tất cả các biến thể dùng chung một SKU, Product Shipping Rules tiêu chuẩn của Miva lưu trữ một bộ kích thước cho mỗi sản phẩm, vì vậy mọi cấu hình đều được xử lý như cùng một kích thước bất kể khách hàng đã chọn gì.

Miva và Zonos hỗ trợ kích thước ở cấp độ biến thể, nhưng điều đó yêu cầu thiết lập từng biến thể riêng lẻ. Điều này có thể không khả thi đối với các cửa hàng có hàng trăm hoặc hàng nghìn cấu hình không ánh xạ tới các biến thể rời rạc.

Tính năng này giải quyết vấn đề đó bằng cách đọc kích thước theo từng cấu hình trực tiếp từ giỏ hàng tại checkout, sử dụng bất kỳ logic tùy chỉnh nào mà cửa hàng của bạn đã có sẵn để tính toán chúng -- ví dụ, phân tích kích thước từ mô tả sản phẩm.

Yêu cầu

• Cửa hàng của bạn phải đã điền các cột kích thước tùy chỉnh trên các mặt hàng trong giỏ hàng khi các mặt hàng được thêm vào giỏ (được xử lý ở phía Miva, ngoài phạm vi của mô-đun Zonos).
• Bạn cần biết chính xác tên cột bạn đang sử dụng.

Cấu hình

Nhập các tên cột đó vào ba trường tương ứng trong trang quản trị mô-đun Zonos. Để trống để quay về Product Shipping Rules tiêu chuẩn -- tính năng này hoàn toàn tùy chọn và sẽ không ảnh hưởng đến các cửa hàng không sử dụng nó.

Khi nhãn vận chuyển được tạo hoặc mã theo dõi được nhập trong Zonos Dashboard, mã theo dõi và trạng thái vận chuyển sẽ tự động được đẩy đến đơn hàng tương ứng trong trang quản trị Miva. Điều này yêu cầu webhook phải được đăng ký (xem bước Đăng ký webhook ở trên).

Mã theo dõi cũng có thể được nhập trực tiếp trong Miva. Sử dụng hộp thoại nhập Enter Tracking Number trên bất kỳ đơn hàng Zonos nào -- mã theo dõi và trạng thái vận chuyển sẽ tự động đồng bộ trở lại Zonos Dashboard.

Nhật ký gỡ lỗi có thể truy cập bên trong trang quản trị Miva, dưới cài đặt mô-đun Zonos. Nó ghi lại toàn bộ vòng đời của mọi sự kiện đơn hàng mà mô-đun xử lý -- nhập, đồng bộ theo dõi, hủy đơn và các yêu cầu hủy gửi đi đến Zonos -- bao gồm cả thành công và thất bại theo dòng thời gian.

Mỗi mục bao gồm mã đơn hàng Zonos, mã đơn hàng Miva, và, khi có liên quan, các chi tiết cấp khách hàng như phản hồi lỗi từ API của Miva hoặc Zonos. Điều này khiến nó trở thành nguồn thông tin đầy đủ nhất để chẩn đoán sự cố.

Nhật ký chỉ lưu giữ 500 dòng gần nhất. Các mục cũ hơn không được lưu trữ, vì vậy hãy kiểm tra ngay sau khi sự cố xảy ra -- các sự kiện trước đó có thể đã bị ghi đè.

Nhật ký lỗi công khai (không yêu cầu đăng nhập) 

Một nhật ký thứ hai, hướng tới công khai, có sẵn thông qua URL trực tiếp -- không cần đăng nhập trang quản trị Miva. Nó chỉ ghi lại lỗi (không có thành công) và không chứa PII của khách hàng hoặc dữ liệu nhạy cảm. Mỗi mục được gắn tiền tố phiên bản mô-đun (ví dụ: [v10.09]) để nhận dạng nhanh.

Định dạng URL:

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Ví dụ:

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code: miva_store_code được trả về trong mảng metadata của phản hồi API cho tất cả các đơn hàng dashboard.

Tất cả các khoản hoàn tiền thanh toán phải được xử lý trực tiếp qua Zonos dashboard. Các nút Refund, Capture và Void trong Miva không khả dụng đối với các đơn hàng được nhập từ Zonos, theo thiết kế. Bất kỳ khoản hoàn tiền nào được xử lý trong Zonos sẽ không tự động cập nhật số tiền thanh toán trên đơn hàng Miva tương ứng -- đơn hàng Miva giữ nguyên số tiền đã ghi nhận ban đầu và không được đồng bộ với hoạt động hoàn tiền trong Zonos.

Đối với việc hủy đơn hàng, hành vi phụ thuộc vào trạng thái hiện tại của đơn hàng:

• Open (chưa được vận chuyển): Hủy đơn trong Miva cũng sẽ hủy đơn trong Zonos và vô hiệu hóa việc ủy quyền thanh toán. Vì Zonos không ghi nhận thanh toán cho đến khi đơn hàng được vận chuyển, khách hàng thực sự không bao giờ bị tính phí và không cần hoàn tiền riêng.
• Shipped hoặc Completed: Hủy đơn trong Miva sẽ đánh dấu đơn hàng Miva là đã hủy, nhưng Zonos sẽ từ chối việc hủy vì đơn hàng đã được hoàn tất và không còn đủ điều kiện để hủy tự động. Trong trường hợp này, một ghi chú chỉ dành cho quản trị viên được thêm vào đơn hàng Miva -- chỉ hiển thị cho nhân viên cửa hàng và không bao giờ hiển thị cho khách hàng -- giải thích rằng đơn hàng cần được xử lý trong Zonos. Một thông báo email cũng được gửi đến địa chỉ email chính của tài khoản cửa hàng để cảnh báo người bán thực hiện hành động trong Zonos dashboard, nơi họ có thể xử lý thủ công bất kỳ khoản hoàn tiền phù hợp nào.

Triệu chứng: Đơn hàng hoàn tất trong Zonos Checkout và xuất hiện trong Zonos dashboard, nhưng không có gì hiển thị trong trang quản trị Miva.

Nguyên nhân: Zonos gửi một webhook ORDER_CREATED (HTTP POST) đến endpoint /mm5/json.mvc của cửa hàng bạn. Trên các trang dev, bảo mật cấp máy chủ thường chặn yêu cầu này trước khi nó đến được Miva. Các nguyên nhân phổ biến:

• HTTP Basic Auth -- Nếu trang dev có lời nhắc mật khẩu (Plesk, cPanel, .htaccess, v.v.), webhook sẽ bị từ chối với lỗi 401 Unauthorized. Đưa các IP của Zonos vào danh sách trắng trong cấu hình .htaccess hoặc Plesk của bạn để chúng bỏ qua lời nhắc xác thực.
• Cloudflare WAF / IP Access Rules -- Nếu trang web được ủy quyền qua Cloudflare, các quy tắc bảo mật của nó có thể chặn yêu cầu POST trước khi nó đến được máy chủ của bạn. Thêm một quy tắc WAF để cho phép các yêu cầu POST có đường dẫn URL chứa /mm5/json.mvc, hoặc đưa các IP của Zonos vào danh sách trắng trực tiếp trong IP Access Rules của Cloudflare.
• Danh sách IP được phép cấp máy chủ -- Nếu trang dev chỉ giới hạn lưu lượng truy cập cho các IP cụ thể (thường gặp trên các môi trường staging bị khóa với IP văn phòng hoặc nền tảng), các yêu cầu webhook của Zonos sẽ bị âm thầm loại bỏ mà không có phản hồi. Thêm tất cả các IP gửi webhook của Zonos vào danh sách được phép của máy chủ bạn (Plesk IP Access Restriction Manager, cPanel IP Blocker, hoặc các quy tắc bảo mật tường lửa/bảng điều khiển hosting của bạn).

Các IP gửi webhook của Zonos

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

Điều này thường chỉ ảnh hưởng đến các trang dev/staging -- các trang Miva sản xuất thường công khai và không cần đưa IP vào danh sách trắng. Nếu không chắc chắn cách định cấu hình việc này, hãy liên hệ với nhà cung cấp hosting hoặc hỗ trợ Miva của bạn.

Thông tin sản phẩm có thể ảnh hưởng đến số tiền thuế và phí do và chi phí vận chuyển. Bạn cung cấp càng nhiều thông tin sản phẩm cho Zonos, thì báo giá được trả về sẽ càng chính xác. Zonos có thể tạo ra báo giá ngay cả khi thông tin này không có sẵn, nhưng khuyên bạn cung cấp các chi tiết sản phẩm chính sau để cải thiện độ chính xác:

• Weight: Trọng lượng ảnh hưởng đến chi phí vận chuyển của bạn, điều này có thể ảnh hưởng đến thuế hoặc phí. Trọng lượng trong danh sách sản phẩm Miva của bạn được Zonos sử dụng tự động khi có.
• Dimensions: Kích thước có thể ảnh hưởng đến chi phí vận chuyển của bạn, điều này có thể ảnh hưởng đến thuế hoặc phí. Zonos có thể sử dụng kích thước sản phẩm (chiều dài, chiều rộng và chiều cao) được đặt trên từng sản phẩm trong Miva, nhưng bạn phải ánh xạ nó trong ứng dụng Zonos để tích hợp đúng.
• HS codes: Mã HS ảnh hưởng đến tỷ lệ thuế quan và đôi khi có thể ảnh hưởng đến thuế. Zonos có thể sử dụng mã HS được đặt trong danh sách sản phẩm của bạn trong Miva, nhưng bạn phải ánh xạ trường mã HS trong ứng dụng Zonos.
• Country of origin: Quốc gia xuất xứ của sản phẩm ảnh hưởng đến tỷ lệ thuế quan và có thể ảnh hưởng đến thuế. Miva không thể gửi quốc gia xuất xứ cho các sản phẩm của bạn tới Zonos nên chúng phải được thêm bằng cách sử dụng Zonos Catalog.

Chi tiết sản phẩm được chuyển đến Zonos bởi Miva 

Lưu ý: Ngoài ra, bạn có thể nhập bất kỳ thông tin nào ở trên vào Catalog, ghi đè thông tin được lưu trữ và được chuyển từ Miva.

Tìm hiểu thêm về thông tin sản phẩm theo nền tảng.