Giải pháp Hậu mãi cho Dịch vụ Khách hàng

Giải pháp Hậu mãi cho Dịch vụ Khách hàng

Tình huống Kinh doanh và Trường hợp Sử dụng

Tài liệu này cung cấp hướng dẫn tích hợp kỹ thuật toàn diện cho các Nhà cung cấp Phần mềm Độc lập (ISVs) và các nhà phát triển của người bán nhằm xây dựng các ứng dụng dịch vụ khách hàng nâng cao trên TikTok Shop Open Platform. Trọng tâm là tận dụng Message Cards để quản lý các hành động hậu mãi—cụ thể là trả hàng, hoàn tiền và hủy đơn—trực tiếp bên trong nền tảng dịch vụ khách hàng của bên thứ ba.

Trong một tình huống hậu mãi điển hình, người mua khởi tạo một yêu cầu (ví dụ: trả lại sản phẩm) thông qua giao diện trò chuyện. Khi đó, nhân viên dịch vụ khách hàng phải điều hướng đến TikTok Shop Seller Center để quản lý yêu cầu này, tạo ra một quy trình làm việc rời rạc và kém hiệu quả.

Giải pháp này mang lại trải nghiệm liền mạch, trong đó các sự kiện hậu mãi được quản lý hoàn toàn bên trong không gian làm việc chính của nhân viên. Ví dụ:

1. Khởi tạo dựa trên thẻ (Card-based Initiation): Người mua không hài lòng với một giao dịch sẽ gửi một tin nhắn. Nhân viên, thay vì trả lời bằng văn bản thuần túy, có thể gửi một Return/Refund Card tương tác. Người mua điền các thông tin cần thiết (lý do, bằng chứng) sau khi được chuyển hướng đến trang khởi tạo hậu mãi từ thẻ này.
2. Hành động trong Chat (In-Chat Actions): Yêu cầu đã gửi, lúc này chứa yêu cầu hậu mãi của người mua, sẽ xuất hiện trong thanh bên của cửa sổ trò chuyện sau khi ISV tích hợp các API trả hàng/hoàn tiền/hủy đơn của TikTok Shop. Nhân viên xem lại thông tin trong ngữ cảnh trò chuyện và sử dụng các nút hành động trên thanh bên (ví dụ: Approve, Reject) để xử lý yêu cầu.
3. Điều phối dựa trên API (API-driven Orchestration): Việc nhấp vào một nút hành động sẽ kích hoạt một lệnh gọi đến endpoint TikTok Shop Open API tương ứng (ví dụ: POST /return_refund/.../approve).
4. Cập nhật Trạng thái Thời gian thực (Real-time Status Updates): Trạng thái của quy trình trả hàng (ví dụ: AWAITING_BUYER_SHIP, REFUND_COMPLETED) được cập nhật theo thời gian thực. Điều này có thể đạt được bằng cách cập nhật thẻ tin nhắn gốc, gửi một tin nhắn hệ thống mới, hoặc hiển thị trạng thái trong một bảng UI chuyên dụng, tất cả đều được hỗ trợ bởi các thông báo Webhook (RETURN_STATUS_CHANGED).

Bằng cách tích hợp message cards với các API hậu mãi, ISVs có thể mang lại trải nghiệm vượt trội cho nhân viên, giảm thời gian giải quyết, và cung cấp một quy trình minh bạch, tương tác cho người mua.

Khởi tạo Yêu cầu Hậu mãi dựa trên Thẻ

Khởi tạo dựa trên thẻ biến một tin nhắn khiếu nại không có cấu trúc thành một luồng hậu mãi có hướng dẫn. Thay vì yêu cầu người mua điều hướng đến một trang trả hàng riêng biệt, nhân viên gửi một Return/Refund Card có cấu trúc từ cuộc trò chuyện, và người mua hoàn tất yêu cầu trong vài bước có hướng dẫn.

Stage	Actor	Message / Card in Chat	Backend Action / API	Expected Outcome
1. Issue discovered	Buyer	Người mua gửi một tin nhắn văn bản thuần túy (tùy chọn kèm hình ảnh/video) mô tả vấn đề với đơn hàng.	Ứng dụng ISV xác định người mua và ngữ cảnh đơn hàng bằng các Customer Service API hiện có (liên kết cuộc trò chuyện và đơn hàng).	Đơn hàng liên quan được xác định và hiển thị cho nhân viên cùng với tin nhắn của người mua.
2. Card offered	Agent	Nhân viên gửi một RETURN_REFUND_CARD (tùy chọn kèm theo một ORDER_CARD) thay vì một câu trả lời tự do.	POST /customer_service/202309/conversations/{conversation_id}/messages với type: "RETURN_REFUND_CARD" và content chứa order_id và sku_id. Có thể kiểm tra điều kiện trước qua GET /return_refund/.../aftersale_eligibility.	Người mua nhận được một thẻ có cấu trúc hiển thị (các) dòng đơn hàng, các tùy chọn hậu mãi đủ điều kiện và một lời kêu gọi hành động rõ ràng.
3. Buyer fills details	Buyer	Người mua mở thẻ, chọn các mặt hàng bị ảnh hưởng, chọn reason, tải lên evidence và xác nhận yêu cầu.	Backend của ISV nhận được nội dung gửi và gọi API hậu mãi phù hợp, ví dụ POST /return_refund/202309/returns (Create Return) hoặc POST /return_refund/202309/cancellations (Create Cancellation).	Một return_id hoặc cancel_id mới được tạo trên TikTok Shop và được lưu trong hệ thống ISV cùng với các định danh cuộc trò chuyện.
4. Confirmation in chat	System	Hệ thống gửi một RETURN_REFUND_CARD đã cập nhật hoặc một tin nhắn xác nhận tóm tắt yêu cầu của người mua (mặt hàng, số tiền, lý do).	ISV tùy chọn gọi Search Returns / Search Cancellations để xác minh yêu cầu đã tạo và sau đó gửi một thẻ đã cập nhật qua Send Message.	Cả người mua và nhân viên đều thấy cùng một chế độ xem có cấu trúc của vụ việc hậu mãi mới tạo trong cuộc trò chuyện.
5. Next-step guidance	System	Thẻ chỉ rõ bước tiếp theo (ví dụ: "Awaiting seller review", "Awaiting buyer shipment").	Trạng thái được suy ra từ đối tượng hậu mãi (ví dụ: RETURN_OR_REFUND_REQUEST_PENDING, AWAITING_BUYER_SHIP) và ánh xạ vào các trường của thẻ.	Người mua biết được điều gì sẽ xảy ra tiếp theo mà không cần rời khỏi cuộc trò chuyện, giảm các lần liên hệ lặp lại và sự nhầm lẫn.

Các tình huống khởi tạo dựa trên thẻ điển hình (theo hướng message-card):

• Yêu cầu chỉ hoàn tiền (không trả hàng):

Người mua báo cáo rằng một mặt hàng không bao giờ đến hoặc không thể sử dụng được. Nhân viên gửi một RETURN_REFUND_CARD được cấu hình cho refund only, và ISV gọi Create Return tiếp theo là Approve Return với decision: APPROVE_REFUND.

• Yêu cầu trả hàng & hoàn tiền:

Người mua đã nhận được mặt hàng nhưng không hài lòng (ví dụ: sai kích cỡ, bị hỏng). Thẻ hiển thị các tùy chọn cho return & refund. Sau khi gửi, ISV gọi Create Return và sau đó hướng dẫn người mua gửi trả lại mặt hàng.

• Hủy đơn hàng trước khi giao hàng:

Người mua yêu cầu hủy một đơn hàng chưa được giao. Nhân viên gửi một thẻ chuyên dụng để hủy đơn (hoặc một ORDER_CARD với CTA Cancel order), và ISV gọi POST /return_refund/202309/cancellations để tạo một yêu cầu hủy đơn.

• Hoàn tiền một phần hoặc hoàn tiền không trả hàng:

Chỉ một phần của đơn hàng nhiều dòng bị lỗi, hoặc người bán chọn cấp một returnless refund cho các mặt hàng giá trị thấp. RETURN_REFUND_CARD cho phép người mua hoặc nhân viên chọn các SKU và số tiền liên quan. ISV gọi Approve Return với decision: APPROVE_REFUND và buyer_keep_item: true khi áp dụng.

Hành động trong Chat & Cập nhật Trạng thái Thời gian thực

Khi một yêu cầu hậu mãi đã được tạo, nhân viên nên có thể xem lại và giải quyết nó mà không cần rời khỏi cửa sổ trò chuyện. ISV hiển thị yêu cầu trong một bảng thanh bên và/hoặc dưới dạng một thẻ tin nhắn đã cập nhật, sao cho các hành động như Approve, Reject, hoặc Modify refund amount vẫn hoàn toàn nằm trong ngữ cảnh.

Stage	Actor	Message / Card in Chat	Backend Action / API	Expected Outcome
1. Request surfaces to agent	System	Một RETURN_REFUND_CARD mới hoặc đã cập nhật xuất hiện, và thanh bên hiển thị một bảng tóm tắt hậu mãi cho cuộc trò chuyện hiện tại.	ISV lắng nghe các Webhook RETURN_STATUS_CHANGED / CANCELLATION_STATUS_CHANGED hoặc thăm dò (poll) Search Returns / Search Cancellations, sau đó liên kết bản ghi hậu mãi mới nhất với cuộc trò chuyện.	Nhân viên ngay lập tức thấy đơn hàng và mặt hàng nào đang được xem xét, mà không cần tìm kiếm trong Seller Center.
2. Context review	Agent	Nhân viên kiểm tra thẻ và thanh bên: chi tiết đơn hàng (qua ORDER_CARD), thông tin vận chuyển (qua LOGISTICS_CARD), và tin nhắn/bằng chứng của người mua.	ISV lấy chi tiết qua Get Order Detail, Search Returns, và các API vận chuyển liên quan để điền vào bảng bên và các trường của thẻ.	Nhân viên có tất cả ngữ cảnh cần thiết (dòng thời gian, trạng thái, các lần thử trước) trong một chế độ xem duy nhất.
3. Action selection	Agent	Nhân viên nhấp vào một nút hành động như Approve, Reject, Refund only, Partial refund, hoặc Cancel order từ thanh bên hoặc thẻ.	ISV gọi endpoint phù hợp, ví dụ: Approve Return, Reject Return, Approve Cancellation, hoặc Cancel Order. Các lệnh gọi ghi bao gồm một idempotency key và xác thực điều kiện trước khi thực thi.	Bản ghi hậu mãi trên TikTok Shop chuyển sang trạng thái tiếp theo dựa trên hành động đã chọn.
4. Buyer notified in chat	System	Thẻ và tin nhắn trong cuộc trò chuyện được cập nhật để hiển thị quyết định (ví dụ: "Return approved – please ship the item", "Refund approved – no need to return", "Request rejected with reason").	Webhooks kích hoạt làm mới UI; ISV cập nhật RETURN_REFUND_CARD hoặc gửi một tin nhắn hệ thống mới qua Send Message. Hướng dẫn vận chuyển có thể được chia sẻ qua LOGISTICS_CARD.	Người mua nhận được một cập nhật có cấu trúc ngay lập tức và các bước tiếp theo rõ ràng ngay trong cuộc trò chuyện.
5. Case closure	System	Trạng thái cuối cùng (ví dụ: "Refund completed", "Cancellation completed") được phản ánh trong một thẻ chỉ đọc trong chat và thanh bên.	Webhook cuối cùng (ví dụ: RETURN_OR_REFUND_REQUEST_COMPLETE) được xử lý; ISV đánh dấu vụ việc là đã giải quyết và cập nhật UI tương ứng.	Nhân viên có thể đóng ticket hoặc cuộc trò chuyện, biết rằng luồng hậu mãi đã hoàn tất thành công.

Các tình huống hành động trong chat điển hình (theo hướng message-card):

• Phê duyệt trả hàng & hoàn tiền tiêu chuẩn:

Trong thanh bên, nhân viên xem lại một RETURN_REFUND_CARD đang chờ xử lý cho một đơn hàng đã giao và nhấp Approve return. ISV gọi Approve Return (decision: APPROVE_RETURN), sau đó gọi Confirm goods received (decision: APPROVE_RECEIVED_PACKAGE) khi gói hàng đến nơi.

• Phê duyệt chỉ hoàn tiền hoặc hoàn tiền không trả hàng:

Đối với các mặt hàng giá trị thấp hoặc không yêu cầu trả lại, nhân viên chọn Refund only từ thẻ. ISV gọi Approve Return với decision: APPROVE_REFUND và có thể đặt buyer_keep_item: true để triển khai một returnless refund.

• Hủy đơn hàng trong chat:

Đối với một đơn hàng AWAITING_SHIPMENT, nhân viên kích hoạt Cancel order từ thẻ liên quan đến đơn hàng. ISV gọi Cancel Order và dùng các Webhook CANCELLATION_STATUS_CHANGED để cập nhật thẻ và đánh dấu các dòng mặt hàng đã hủy.

• Hoàn tiền một phần trên đơn hàng nhiều dòng:

Khi chỉ một SKU trong một đơn hàng nhiều mặt hàng có vấn đề, thanh bên cho phép nhân viên chọn các dòng mặt hàng bị ảnh hưởng và số tiền hoàn. ISV truyền các mặt hàng đã chọn và số tiền vào các lệnh gọi Create Return và Approve Return, và thẻ làm nổi bật những mặt hàng nào đã được hoàn tiền.

• Từ chối các yêu cầu không hợp lệ hoặc lạm dụng:

Nếu các kiểm tra điều kiện thất bại (ví dụ: ngoài thời hạn, sai lý do), nhân viên nhấp Reject từ thẻ, chọn một lý do từ chối chuẩn hóa, và ISV gọi Reject Return. Thẻ trở thành chỉ đọc và ghi lại quyết định trong lịch sử cuộc trò chuyện.

Message Cards được Sử dụng (theo từng trường hợp sử dụng)

Hành trình hủy đơn (Cancel journey)

Tổng quan: Các thẻ hủy đơn cho phép người bán hoặc chatbot hiển thị trải nghiệm hủy đơn một lần nhấp cho các đơn hàng vẫn còn có thể hủy (thường là UNPAID, ON_HOLD, AWAITING_SHIPMENT). Thẻ trình bày các dòng đơn hàng và các lý do hủy đủ điều kiện, sau đó tạo một yêu cầu hủy và đưa quyết định cuối cùng trở lại cuộc trò chuyện bằng cách sử dụng seller_im_order_cancellation_text_card, seller_im_order_cancellation_notification_card, seller_im_order_cancellation_voucher_card, seller_im_chatbot_cancel_order, và seller_im_chatbot_cancel_order_result.

Các API liên quan:

• POST /return_refund/202309/cancellations — Cancel Order (hủy đơn do người bán khởi tạo, hỗ trợ hủy một phần qua skus hoặc order_line_item_ids ở một số thị trường).
• POST /return_refund/202309/cancellations/search — Search Cancellations (liệt kê và lọc các bản ghi hủy theo đơn hàng, người mua, trạng thái hoặc khoảng thời gian).
• POST /return_refund/202309/cancellations/{cancel_id}/approve — Approve Cancellation (người bán chấp nhận một yêu cầu hủy do người mua khởi tạo).
• POST /return_refund/202309/cancellations/{cancel_id}/reject — Reject Cancellation (người bán từ chối một yêu cầu hủy do người mua khởi tạo với một lý do có cấu trúc).
• GET /return_refund/202309/reject_reasons — Get Reject Reasons (trả về các văn bản đã bản địa hóa cho các lý do từ chối hợp lệ cho một yêu cầu hủy cụ thể).

Điều kiện đủ (Eligibility):

• GET /return_refund/202512/orders/{order_id}/aftersale_eligibility:

Gọi trước khi hiển thị seller_im_order_cancellation_text_card hoặc seller_im_chatbot_cancel_order. Truyền initiate_aftersale_user là SELLER hoặc BUYER và bao gồm CANCEL trong request_types. Sử dụng sku_eligibility[].line_item_eligibility[].eligible và available_reason_names để quyết định những dòng mặt hàng nào vẫn có thể hủy và những mã cancel_reason nào cần hiển thị trong thẻ. GET /return_refund/202512/orders/{order_id}/aftersale_eligibility

: - Gọi trước khi hiển thị seller_im_order_cancellation_text_card hoặc seller_im_chatbot_cancel_order.

• Truyền initiate_aftersale_user là SELLER hoặc BUYER và bao gồm CANCEL trong request_types.

• Sử dụng sku_eligibility[].line_item_eligibility[].eligible và available_reason_names để quyết định những dòng mặt hàng nào vẫn có thể hủy và những mã cancel_reason nào cần hiển thị trong thẻ.

• GET /return_refund/202601/decision_eligibility:

Gọi với return_or_cancel_id = cancel_id và check_decisions bao gồm APPROVE_REQUEST_CANCEL và REJECT_REQUEST_CANCEL trước khi hiển thị các nút Approve/Reject trên seller_im_order_cancellation_notification_card hoặc seller_im_chatbot_cancel_order_result. Sử dụng decisions[].eligible, ineligible_reason và available_reject_reasons để bật/tắt các hành động và điền sẵn các bộ chọn lý do từ chối. GET /return_refund/202601/decision_eligibility

: - Gọi với return_or_cancel_id = cancel_id và check_decisions bao gồm APPROVE_REQUEST_CANCEL và REJECT_REQUEST_CANCEL trước khi hiển thị các nút Approve/Reject trên seller_im_order_cancellation_notification_card hoặc seller_im_chatbot_cancel_order_result.

• Sử dụng decisions[].eligible, ineligible_reason và available_reject_reasons để bật/tắt các hành động và điền sẵn các bộ chọn lý do từ chối.

Ánh xạ Hành động → Trạng thái:

Action	API call	Next state label
Tạo yêu cầu hủy do người bán khởi tạo	POST /return_refund/202309/cancellations	CANCELLATION_REQUEST_PENDING (hoặc CANCELLATION_REQUEST_SUCCESS khi được xử lý ngay lập tức)
Phê duyệt yêu cầu hủy của người mua	POST /return_refund/202309/cancellations/{cancel_id}/approve	CANCELLATION_REQUEST_SUCCESS
Từ chối yêu cầu hủy của người mua	POST /return_refund/202309/cancellations/{cancel_id}/reject	CANCELLATION_REQUEST_CANCEL
Nền tảng hoàn tất việc hủy và hoàn tiền	Webhook + Search Cancellations (không có API ghi trực tiếp)	CANCELLATION_REQUEST_COMPLETE
Những thành phần thiết yếu của payload:

• Đối với Cancel Order (POST /return_refund/202309/cancellations):

order_id (id đơn hàng TikTok Shop bắt buộc). skus[].sku_id, skus[].quantity hoặc order_line_item_ids[] để hủy một phần khi được hỗ trợ. cancel_reason (bắt buộc; sử dụng một tên lý do từ các bảng Cancel reasons khớp với trạng thái đơn hàng hiện tại). Envelope truy vấn chuẩn: app_key, sign, timestamp, shop_cipher. Headers: x-tts-access-token, content-type: application/json. For Cancel Order

(POST /return_refund/202309/cancellations

): - order_id (id đơn hàng TikTok Shop bắt buộc).

• skus[].sku_id, skus[].quantity hoặc order_line_item_ids[] để hủy một phần khi được hỗ trợ.

• cancel_reason (bắt buộc; sử dụng một tên lý do từ các bảng Cancel reasons khớp với trạng thái đơn hàng hiện tại).

• Envelope truy vấn chuẩn: app_key, sign, timestamp, shop_cipher.

• Headers: x-tts-access-token, content-type: application/json.

• Đối với Approve/Reject Cancellation:

cancel_id (tham số đường dẫn). Đối với reject: reject_reason (từ Get Reject Reasons), tùy chọn comment, tùy chọn images[].image_id với metadata cơ bản. For Approve/Reject Cancellation: - cancel_id (tham số đường dẫn).

• Đối với reject: reject_reason (từ Get Reject Reasons), tùy chọn comment, tùy chọn images[].image_id với metadata cơ bản.

Ghi chú vận hành:

• Sử dụng idempotency_key trên các lệnh gọi Cancel/Approve/Reject để loại bỏ trùng lặp do nhấp thẻ nhiều lần hoặc lỗi mạng.
• Ánh xạ các lỗi phổ biến thành các thông báo ở cấp thẻ:

25001021 Reason not match order status → cập nhật thẻ để báo cho nhân viên rằng lý do này không còn áp dụng cho trạng thái đơn hàng hiện tại. 25001045 / 25001051 → đơn hàng đã được giao hoặc đã hoàn tất và không thể hủy; hướng dẫn nhân viên sử dụng luồng hoàn tiền/trả hàng thay thế. 25001011 → một yêu cầu hủy hoặc trả hàng đã đang được xử lý; liên kết lại với vụ việc hiện có thay vì tạo một vụ mới. Map common errors into card-level messages: - 25001021 Reason not match order status → cập nhật thẻ để báo cho nhân viên rằng lý do này không còn áp dụng cho trạng thái đơn hàng hiện tại.

• 25001045 / 25001051 → đơn hàng đã được giao hoặc đã hoàn tất và không thể hủy; hướng dẫn nhân viên sử dụng luồng hoàn tiền/trả hàng thay thế.

• 25001011 → một yêu cầu hủy hoặc trả hàng đã đang được xử lý; liên kết lại với vụ việc hiện có thay vì tạo một vụ mới.

• Sử dụng Search Cancellations để điều khiển các dòng thời gian trong chat và để khôi phục sau khi bỏ lỡ các Webhook; lọc theo cancel_status, cancel_types, và khoảng thời gian.

• Các giới hạn tốc độ rõ ràng không được liệt kê theo từng endpoint; hãy triển khai điều tiết (throttling) phía client và exponential backoff, và dựa vào tài liệu nền tảng cho bất kỳ giới hạn toàn cục nào.

Hành trình chỉ hoàn tiền / hoàn tiền không trả hàng (Refund-only / Returnless refund journey)

Tổng quan: Các thẻ chỉ hoàn tiền và hoàn tiền không trả hàng hỗ trợ các luồng bồi thường tiền tệ nhanh mà không buộc người mua phải gửi trả lại các mặt hàng. Các thẻ như seller_im_quick_refund_confirmation, seller_im_quick_refund_succeeded, seller_im_approve_refund_withdout_return, và seller_im_chatbot_aftersales_check_status cho phép nhân viên cấp hoàn tiền toàn phần hoặc một phần, tùy chọn với buyer_keep_item = true cho các returnless refund.

Các API liên quan:

• POST /return_refund/202309/returns — Create Return (sử dụng return_type = REFUND cho các trường hợp chỉ hoàn tiền, với tùy chọn refund_total và currency).
• POST /return_refund/202309/refunds/calculate — Calculate Refund (xem trước các số tiền có thể hoàn theo đơn hàng/dòng trước khi hiển thị chúng trên thẻ).
• POST /return_refund/202309/returns/{return_id}/approve — Approve Return (đặt decision = APPROVE_REFUND, tùy chọn buyer_keep_item = true và/hoặc một số tiền partial_refund).
• POST /return_refund/202309/returns/{return_id}/reject — Reject Return (với decision = REJECT_REFUND khi yêu cầu chỉ hoàn tiền không hợp lệ).
• POST /return_refund/202309/returns/search — Search Returns (liệt kê các vụ hoàn tiền và trạng thái của chúng cho một cửa hàng hoặc đơn hàng).
• GET /return_refund/202309/returns/{return_id}/records — Get Return Records (dòng thời gian dùng để làm phong phú seller_im_chatbot_aftersales_check_status).

Điều kiện đủ (Eligibility):

• GET /return_refund/202512/orders/{order_id}/aftersale_eligibility:

Gọi với request_types chứa REFUND trước khi hiển thị các tùy chọn hoàn tiền nhanh. Sử dụng sku_eligibility[].line_item_eligibility[].eligible để giới hạn các hành động chỉ hoàn tiền cho các dòng đủ điều kiện và để điều khiển những SKU nào có thể được chọn sẵn trong thẻ. GET /return_refund/202512/orders/{order_id}/aftersale_eligibility

: - Gọi với request_types chứa REFUND trước khi hiển thị các tùy chọn hoàn tiền nhanh.

• Sử dụng sku_eligibility[].line_item_eligibility[].eligible để giới hạn các hành động chỉ hoàn tiền cho các dòng đủ điều kiện và để điều khiển những SKU nào có thể được chọn sẵn trong thẻ.

• GET /return_refund/202601/decision_eligibility:

Gọi với return_or_cancel_id = return_id và check_decisions bao gồm APPROVE_REFUND, DIRECT_REFUND, OFFER_PARTIAL_REFUND, và REJECT_REFUND khi được hỗ trợ. Sử dụng phản hồi để bật hoặc tắt các nút trên seller_im_quick_refund_confirmation và để lấy available_reject_reasons khi nhân viên chọn từ chối. GET /return_refund/202601/decision_eligibility

: - Gọi với return_or_cancel_id = return_id và check_decisions bao gồm APPROVE_REFUND, DIRECT_REFUND, OFFER_PARTIAL_REFUND, và REJECT_REFUND khi được hỗ trợ.

• Sử dụng phản hồi để bật hoặc tắt các nút trên seller_im_quick_refund_confirmation và để lấy available_reject_reasons khi nhân viên chọn từ chối.

Ánh xạ Hành động → Trạng thái:

Action	API call	Next state label
Tạo yêu cầu chỉ hoàn tiền (toàn phần hoặc một phần)	POST /return_refund/202309/returns (return_type = REFUND)	RETURN_OR_REFUND_REQUEST_PENDING
Phê duyệt chỉ hoàn tiền / hoàn tiền không trả hàng	POST /return_refund/202309/returns/{return_id}/approve (decision = APPROVE_REFUND, tùy chọn buyer_keep_item, partial_refund)	RETURN_OR_REFUND_REQUEST_SUCCESS
Nền tảng hoàn tất việc chi trả hoàn tiền	Webhook + Search Returns (không có API ghi trực tiếp)	RETURN_OR_REFUND_REQUEST_COMPLETE
Từ chối yêu cầu chỉ hoàn tiền	POST /return_refund/202309/returns/{return_id}/reject (decision = REJECT_REFUND)	REFUND_OR_RETURN_REQUEST_REJECT
Những thành phần thiết yếu của payload:

• Đối với Calculate Refund:

order_id (bắt buộc), request_type (REFUND hoặc CANCEL), reason_name (từ Refund reasons), order_line_item_ids[] và/hoặc skus[] (mỗi cái với sku_id, quantity) để giới hạn phạm vi hoàn tiền, tùy chọn shipment_type và handover_method cho các tình huống sau này có thể chuyển thành trả hàng & hoàn tiền. For Calculate Refund

: - order_id (bắt buộc), request_type (REFUND hoặc CANCEL), reason_name (từ Refund reasons),

• order_line_item_ids[] và/hoặc skus[] (mỗi cái với sku_id, quantity) để giới hạn phạm vi hoàn tiền,

• tùy chọn shipment_type và handover_method cho các tình huống sau này có thể chuyển thành trả hàng & hoàn tiền.

• Đối với Create Return (chỉ hoàn tiền):

order_id, return_type = REFUND, return_reason (tên lý do khớp với các bảng Refund reasons), tùy chọn refund_total và currency (không được vượt quá số tiền có thể hoàn đã tính toán), order_line_item_ids[] và/hoặc skus[] để hỗ trợ hoàn tiền một phần. For Create Return

(refund-only): - order_id, return_type = REFUND, return_reason (tên lý do khớp với các bảng Refund reasons),

• tùy chọn refund_total và currency (không được vượt quá số tiền có thể hoàn đã tính toán),

• order_line_item_ids[] và/hoặc skus[] để hỗ trợ hoàn tiền một phần.

• Đối với Approve Return (chỉ hoàn tiền):

return_id, decision = APPROVE_REFUND, tùy chọn buyer_keep_item (true cho returnless), tùy chọn partial_refund.currency và partial_refund.amount cho hoàn tiền một phần. For Approve Return

(refund-only): - return_id, decision = APPROVE_REFUND,

• tùy chọn buyer_keep_item (true cho returnless),
• tùy chọn partial_refund.currency và partial_refund.amount cho hoàn tiền một phần.

Ghi chú vận hành:

• Luôn gọi Calculate Refund trước khi xác nhận một thẻ hoàn tiền nhanh, và hiển thị refund_total, refund_shipping_fee, refund_tax và các thành phần khác một cách minh bạch cho nhân viên.
• Nếu Create Return được gọi với refund_total lớn hơn số tiền có thể hoàn do nền tảng tính toán, API trả về 25005005; hãy hiển thị lỗi này trong thẻ và đồng bộ lại số tiền từ Calculate Refund.
• Chỉ sử dụng buyer_keep_item = true ở những nơi mà chính sách của bạn và chính sách TikTok Shop cho phép rõ ràng các returnless refund; các thẻ như seller_im_approve_refund_withdout_return nên truyền đạt rõ ràng rằng người mua có thể giữ lại các mặt hàng.
• Đối với hoàn tiền một phần trên các đơn hàng nhiều dòng, hãy giữ ánh xạ giữa order_line_item_ids / skus và các dòng UI sao cho seller_im_quick_refund_succeeded có thể làm nổi bật chính xác những mặt hàng nào đã được hoàn tiền.
• Xử lý các lỗi xác thực phổ biến (25001014/25001020 lý do không xác định hoặc đã ngoại tuyến, 25005011 các dòng mặt hàng vượt quá giới hạn) bằng cách vô hiệu hóa nút xác nhận và yêu cầu nhân viên điều chỉnh lựa chọn thay vì gọi API lặp đi lặp lại.

Hành trình trả hàng & hoàn tiền (Return & refund journey)

Tổng quan: Các thẻ trả hàng & hoàn tiền xử lý toàn bộ luồng trả hàng vật lý: người bán xem xét, người mua gửi hàng, người bán kiểm tra và hoàn tiền cuối cùng. Các thẻ như seller_im_seller_approve_return_request_card, seller_im_seller_reject_return_request_card, và seller_im_chatbot_aftersales_check_status giữ cho cả người mua và nhân viên đồng bộ với các trạng thái nền tảng như AWAITING_BUYER_SHIP, BUYER_SHIPPED_ITEM, và RETURN_OR_REFUND_REQUEST_COMPLETE.

Các API liên quan:

• POST /return_refund/202309/returns — Create Return (sử dụng return_type = RETURN_AND_REFUND cho các lần trả hàng tiêu chuẩn với hàng hóa vật lý được gửi trả lại).
• POST /return_refund/202309/returns/{return_id}/approve — Approve Return:

phê duyệt ban đầu (decision = APPROVE_RETURN) chuyển vụ việc sang "awaiting buyer shipment"; phê duyệt sau đó (decision = APPROVE_RECEIVED_PACKAGE) xác nhận gói hàng đã trả lại và kích hoạt hoàn tiền. POST /return_refund/202309/returns/{return_id}/approve

— Approve Return: - phê duyệt ban đầu (decision = APPROVE_RETURN) chuyển vụ việc sang "awaiting buyer shipment";

• phê duyệt sau đó (decision = APPROVE_RECEIVED_PACKAGE) xác nhận gói hàng đã trả lại và kích hoạt hoàn tiền.

• POST /return_refund/202309/returns/{return_id}/reject — Reject Return (với decision = REJECT_RETURN hoặc REJECT_RECEIVED_PACKAGE tùy thuộc vào việc người bán đang từ chối chính yêu cầu hay gói hàng đã nhận).

• POST /return_refund/202309/returns/search — Search Returns (nguồn chính của trạng thái trả hàng, trạng thái phân xử, và các hành động tiếp theo của người bán).

• GET /return_refund/202309/returns/{return_id}/records — Get Return Records (nhật ký sự kiện theo trình tự thời gian dùng để làm phong phú các thẻ kiểm tra trạng thái).

• GET /return_refund/202309/reject_reasons — Get Reject Reasons (cho các lần trả hàng).

Điều kiện đủ (Eligibility):

• GET /return_refund/202512/orders/{order_id}/aftersale_eligibility:

Gọi với request_types bao gồm RETURN_AND_REFUND trước khi bật các CTA "Return & refund" trên thẻ. Sử dụng các cờ eligible theo từng SKU và available_reason_names để kiểm soát những dòng nào có thể được trả lại và những lý do trả hàng nào cần hiển thị trong seller_im_seller_approve_return_request_card. GET /return_refund/202512/orders/{order_id}/aftersale_eligibility

: - Gọi với request_types bao gồm RETURN_AND_REFUND trước khi bật các CTA "Return & refund" trên thẻ.

• Sử dụng các cờ eligible theo từng SKU và available_reason_names để kiểm soát những dòng nào có thể được trả lại và những lý do trả hàng nào cần hiển thị trong seller_im_seller_approve_return_request_card.

• GET /return_refund/202601/decision_eligibility:

Đối với một return_id hiện có, gọi với return_or_cancel_id = return_id và check_decisions bao gồm APPROVE_RETURN, APPROVE_RECEIVED_PACKAGE, REJECT_RETURN, và REJECT_RECEIVED_PACKAGE. Sử dụng decisions[].eligible để quyết định có hiển thị hay vô hiệu hóa các nút Approve/Reject trên thẻ cho trạng thái hiện tại không, và available_reject_reasons để điền vào dropdown lý do từ chối. GET /return_refund/202601/decision_eligibility

: - Đối với một return_id hiện có, gọi với return_or_cancel_id = return_id và check_decisions bao gồm APPROVE_RETURN, APPROVE_RECEIVED_PACKAGE, REJECT_RETURN, và REJECT_RECEIVED_PACKAGE.

• Sử dụng decisions[].eligible để quyết định có hiển thị hay vô hiệu hóa các nút Approve/Reject trên thẻ cho trạng thái hiện tại không, và available_reject_reasons để điền vào dropdown lý do từ chối.

Ánh xạ Hành động → Trạng thái:

Action	API call	Next state label
Tạo yêu cầu trả hàng & hoàn tiền	POST /return_refund/202309/returns (return_type = RETURN_AND_REFUND)	RETURN_OR_REFUND_REQUEST_PENDING
Phê duyệt yêu cầu trả hàng (yêu cầu người mua gửi hàng)	POST /return_refund/202309/returns/{return_id}/approve (decision = APPROVE_RETURN)	AWAITING_BUYER_SHIP
Người mua gửi hàng và vận chuyển cập nhật trạng thái	Cập nhật vận chuyển → Webhook RETURN_STATUS_CHANGED hoặc Search Returns	BUYER_SHIPPED_ITEM
Xác nhận đã nhận hàng và vượt qua kiểm tra	POST /return_refund/202309/returns/{return_id}/approve (decision = APPROVE_RECEIVED_PACKAGE)	RETURN_OR_REFUND_REQUEST_SUCCESS
Nền tảng hoàn tất việc chi trả hoàn tiền	Webhook + Search Returns	RETURN_OR_REFUND_REQUEST_COMPLETE
Từ chối yêu cầu hoặc từ chối gói hàng sau khi kiểm tra	POST /return_refund/202309/returns/{return_id}/reject (decision = REJECT_RETURN hoặc REJECT_RECEIVED_PACKAGE)	REFUND_OR_RETURN_REQUEST_REJECT hoặc REJECT_RECEIVE_PACKAGE
Những thành phần thiết yếu của payload:

• Đối với Create Return (trả hàng & hoàn tiền):

order_id (bắt buộc), return_type = RETURN_AND_REFUND, return_reason (tên lý do từ các bảng Return reasons khớp với trạng thái đơn hàng và danh mục), order_line_item_ids[] và/hoặc skus[] (sku_id, quantity) mô tả các mặt hàng cần trả lại, tùy chọn refund_total và currency (phải nằm trong số tiền có thể hoàn cho các dòng đó), shipment_type (PLATFORM hoặc BUYER_ARRANGE) và, khi là PLATFORM, một handover_method (DROP_OFF hoặc PICKUP). For Create Return

(return & refund): - order_id (bắt buộc), return_type = RETURN_AND_REFUND,

• return_reason (tên lý do từ các bảng Return reasons khớp với trạng thái đơn hàng và danh mục),

• order_line_item_ids[] và/hoặc skus[] (sku_id, quantity) mô tả các mặt hàng cần trả lại,

• tùy chọn refund_total và currency (phải nằm trong số tiền có thể hoàn cho các dòng đó),

• shipment_type (PLATFORM hoặc BUYER_ARRANGE) và, khi là PLATFORM, một handover_method (DROP_OFF hoặc PICKUP).

• Đối với Approve Return / Reject Return:

return_id (tham số đường dẫn), decision khớp với giai đoạn hiện tại (APPROVE_RETURN, APPROVE_RECEIVED_PACKAGE, REJECT_RETURN, REJECT_RECEIVED_PACKAGE), đối với approve: tùy chọn buyer_keep_item và partial_refund (cho các luồng nâng cao như hoàn tiền một phần sau khi kiểm tra), đối với reject: reject_reason (từ Get Reject Reasons), tùy chọn comment, tùy chọn images[]. For Approve Return

/ Reject Return

: - return_id (tham số đường dẫn),

• decision khớp với giai đoạn hiện tại (APPROVE_RETURN, APPROVE_RECEIVED_PACKAGE, REJECT_RETURN, REJECT_RECEIVED_PACKAGE),
• đối với approve: tùy chọn buyer_keep_item và partial_refund (cho các luồng nâng cao như hoàn tiền một phần sau khi kiểm tra),
• đối với reject: reject_reason (từ Get Reject Reasons), tùy chọn comment, tùy chọn images[].

Ghi chú vận hành:

• Sử dụng idempotency_key trên Create Return, Approve Return, và Reject Return để phòng tránh việc nhấp trùng lặp trên seller_im_seller_approve_return_request_card hoặc seller_im_seller_reject_return_request_card.
• Xử lý các lỗi điển hình một cách hợp lý trong UI:

25001010 / 25001011 cho biết một lần trả hàng đã tồn tại hoặc đã hoàn tất; thay vì để hành động thất bại một cách âm thầm, hãy liên kết lại thẻ với return_id hiện có. 25005005 / 25005011 cho biết số tiền hoàn hoặc số lượng mặt hàng không hợp lệ; làm mới các số tiền đã tính toán qua Calculate Refund. 25001014 / 25001020 cho biết các lý do không hợp lệ hoặc đã ngoại tuyến; làm mới danh sách lý do từ các API reasons/eligibility. Handle typical errors gracefully in the UI: - 25001010 / 25001011 cho biết một lần trả hàng đã tồn tại hoặc đã hoàn tất; thay vì để hành động thất bại một cách âm thầm, hãy liên kết lại thẻ với return_id hiện có.

• 25005005 / 25005011 cho biết số tiền hoàn hoặc số lượng mặt hàng không hợp lệ; làm mới các số tiền đã tính toán qua Calculate Refund.

• 25001014 / 25001020 cho biết các lý do không hợp lệ hoặc đã ngoại tuyến; làm mới danh sách lý do từ các API reasons/eligibility.

• Kết hợp Webhooks (RETURN_STATUS_CHANGED) với Search Returns và Get Return Records để giữ cho seller_im_chatbot_aftersales_check_status đồng bộ với trạng thái nền tảng có thẩm quyền, bao gồm cả kết quả phân xử và các sự kiện gói hàng.

Xác nhận vận chuyển & địa chỉ (chủ động) (Logistics & address confirmations (proactive))

Các thẻ vận chuyển và địa chỉ chủ động—seller_im_proactive_confirm_address, seller_im_proactive_order_received, và seller_im_proactive_abnormal_logistics—chủ yếu là các bề mặt thông báo. Việc gửi các thẻ này tự nó không nên kích hoạt các lệnh gọi API đơn hàng, trả hàng, hoặc hủy đơn: backend xem chúng như các tin nhắn trạng thái hoặc xác nhận chỉ đọc. Chỉ khi người mua hoặc nhân viên nhấp vào một deep link hoặc CTA bên trong thẻ (ví dụ: để chỉnh sửa địa chỉ giao hàng hoặc mở một trang khởi tạo trả hàng) thì ISV mới nên gọi các API quy trình tương ứng (cập nhật địa chỉ, yêu cầu vận chuyển, hoặc khởi tạo hậu mãi). Điều này giữ cho tin nhắn vận chuyển chủ động không có tác dụng phụ trong khi vẫn cho phép các hành động deep-link bắt đầu các luồng hậu mãi đầy đủ khi được yêu cầu rõ ràng.

Hướng dẫn Hiển thị trên Seller Workbench & Dự phòng Văn bản

Các Loại Tin nhắn được Hỗ trợ & Quy tắc Hiển thị

Sử dụng bộ ba content / data / plaintext từ đặc tả Message Types làm cơ sở để hiển thị:

• content: metadata tối thiểu dùng để xác định tài nguyên (đơn hàng, sản phẩm, coupon, gói hàng, v.v.).
• data: payload nghiệp vụ phong phú để xây dựng UI tùy chỉnh; chỉ hiện diện khi need_data = true.
• plaintext: mô tả văn bản đã được làm phẳng sẵn cho các client đơn giản hoặc dự phòng; chỉ hiện diện khi need_plaintext = true.

Trên seller workbench, luôn ưu tiên data để hiển thị thẻ phong phú và giữ plaintext làm dự phòng.

• Văn bản (TEXT)

Các trường tối thiểu: content.content (văn bản thuần túy). Tùy chọn plaintext cho biểu diễn văn bản đầy đủ. Hiển thị: Hiển thị dưới dạng văn bản căn trái nhiều dòng; hỗ trợ tự động tạo liên kết URL; giữ nguyên các ngắt dòng và dấu câu cơ bản. Không cắt ngắn theo mặc định; nếu cần cắt ngắn, hãy cung cấp một tùy chọn mở rộng "". Khả năng tiếp cận: Đảm bảo độ tương phản màu sắc đầy đủ và kích thước phông chữ có thể điều chỉnh; phơi bày toàn bộ văn bản cho trình đọc màn hình. Text (TEXT)

• Các trường tối thiểu: content.content (văn bản thuần túy). Tùy chọn plaintext cho biểu diễn văn bản đầy đủ.

• Hiển thị: Hiển thị dưới dạng văn bản căn trái nhiều dòng; hỗ trợ tự động tạo liên kết URL; giữ nguyên các ngắt dòng và dấu câu cơ bản. Không cắt ngắn theo mặc định; nếu cần cắt ngắn, hãy cung cấp một tùy chọn mở rộng "".

• Khả năng tiếp cận: Đảm bảo độ tương phản màu sắc đầy đủ và kích thước phông chữ có thể điều chỉnh; phơi bày toàn bộ văn bản cho trình đọc màn hình.

• Hình ảnh / Emoji (IMAGE / emoticons)

Các trường tối thiểu: content.url, content.width, content.height. Hiển thị: Hiển thị một thumbnail được thu nhỏ giữ nguyên tỷ lệ khung hình và vừa với chiều rộng chat; nhấp vào thumbnail sẽ mở xem trước kích thước đầy đủ. Đối với các hình ảnh kiểu emoji, bạn có thể hiển thị chúng nội tuyến với văn bản khi thích hợp. Khả năng tiếp cận: Nếu plaintext hiện diện, hãy dùng nó làm alt text/nhãn truy cập. Khi hình ảnh không tải được, hãy hiển thị một placeholder với cùng alt text thay vì một ô trống. Image / Emoji (IMAGE / emoticons)

• Các trường tối thiểu: content.url, content.width, content.height.

• Hiển thị: Hiển thị một thumbnail được thu nhỏ giữ nguyên tỷ lệ khung hình và vừa với chiều rộng chat; nhấp vào thumbnail sẽ mở xem trước kích thước đầy đủ. Đối với các hình ảnh kiểu emoji, bạn có thể hiển thị chúng nội tuyến với văn bản khi thích hợp.

• Khả năng tiếp cận: Nếu plaintext hiện diện, hãy dùng nó làm alt text/nhãn truy cập. Khi hình ảnh không tải được, hãy hiển thị một placeholder với cùng alt text thay vì một ô trống.

• Video (VIDEO)

Các trường tối thiểu: content.url và content.cover; khi có sẵn, cũng dùng width, height, duration. Hiển thị: Hiển thị ảnh bìa với một biểu tượng phát rõ ràng. Không tự động phát trong danh sách cuộc trò chuyện; mở một trình phát modal hoặc bảng bên khi nhấp. Chỉ thị thời lượng trên thumbnail khi có sẵn. Khả năng tiếp cận: Cung cấp một nhãn truy cập như "Video message" và đọc to thời lượng; đảm bảo tiêu điểm bàn phím có thể đến được nút phát. Video (VIDEO)

• Các trường tối thiểu: content.url và content.cover; khi có sẵn, cũng dùng width, height, duration.

• Hiển thị: Hiển thị ảnh bìa với một biểu tượng phát rõ ràng. Không tự động phát trong danh sách cuộc trò chuyện; mở một trình phát modal hoặc bảng bên khi nhấp. Chỉ thị thời lượng trên thumbnail khi có sẵn.

• Khả năng tiếp cận: Cung cấp một nhãn truy cập như "Video message" và đọc to thời lượng; đảm bảo tiêu điểm bàn phím có thể đến được nút phát.

• Order Card (ORDER_CARD)

Các trường tối thiểu: content.order_id. Để hiển thị phong phú, dựa vào data.order_status, data.product_name, data.product_image, data.paid_price, data.quantity, data.order_link. Hiển thị: Hiển thị một thẻ gọn với thumbnail sản phẩm, tiêu đề, số lượng, trạng thái đơn hàng, và số tiền đã thanh toán. CTA chính nên là View order details, sử dụng data.order_link hoặc một deep link nội bộ đến bảng chi tiết đơn hàng của người bán. Khả năng tiếp cận: Làm cho toàn bộ thẻ có thể nhận tiêu điểm như một đơn vị duy nhất với một nhãn rõ ràng (ví dụ: "Order card – {product_name}, status {order_status}"). Đảm bảo CTA có thể đến được bằng bàn phím. Order Card (ORDER_CARD)

• Các trường tối thiểu: content.order_id. Để hiển thị phong phú, dựa vào data.order_status, data.product_name, data.product_image, data.paid_price, data.quantity, data.order_link.

• Hiển thị: Hiển thị một thẻ gọn với thumbnail sản phẩm, tiêu đề, số lượng, trạng thái đơn hàng, và số tiền đã thanh toán. CTA chính nên là View order details, sử dụng data.order_link hoặc một deep link nội bộ đến bảng chi tiết đơn hàng của người bán.

• Khả năng tiếp cận: Làm cho toàn bộ thẻ có thể nhận tiêu điểm như một đơn vị duy nhất với một nhãn rõ ràng (ví dụ: "Order card – {product_name}, status {order_status}"). Đảm bảo CTA có thể đến được bằng bàn phím.

• Product Card (PRODUCT_CARD)

Các trường tối thiểu: content.product_id. Đối với UI, dùng data.product_name, data.product_image, data.product_lowest_price, data.product_highest_price, data.sold_quantity, data.product_link. Hiển thị: Hiển thị hình ảnh sản phẩm, tên, khoảng giá và các tín hiệu bán hàng chính (ví dụ: số lượng đã bán). CTA chính: View product (mở product_link hoặc một trang sản phẩm nội bộ). Trong các luồng vận chuyển chủ động, điều này có thể được dùng để đề xuất các mặt hàng thay thế hoặc bán thêm khi giao hàng bị trễ. Khả năng tiếp cận: Cung cấp một nhãn như "Product card – {product_name}, price from {product_lowest_price}"; đảm bảo các thẻ có thể điều hướng bằng bàn phím. Product Card (PRODUCT_CARD)

• Các trường tối thiểu: content.product_id. Đối với UI, dùng data.product_name, data.product_image, data.product_lowest_price, data.product_highest_price, data.sold_quantity, data.product_link.

• Hiển thị: Hiển thị hình ảnh sản phẩm, tên, khoảng giá và các tín hiệu bán hàng chính (ví dụ: số lượng đã bán). CTA chính: View product (mở product_link hoặc một trang sản phẩm nội bộ). Trong các luồng vận chuyển chủ động, điều này có thể được dùng để đề xuất các mặt hàng thay thế hoặc bán thêm khi giao hàng bị trễ.

• Khả năng tiếp cận: Cung cấp một nhãn như "Product card – {product_name}, price from {product_lowest_price}"; đảm bảo các thẻ có thể điều hướng bằng bàn phím.

• Coupon Card (COUPON_CARD)

Các trường tối thiểu: content.coupon_id. Đối với UI, dùng data.coupon_title, data.discount, data.threshold, data.scope, data.start_time, data.end_time, data.coupon_link. Hiển thị: Hiển thị nổi bật số tiền hoặc tỷ lệ phần trăm giảm giá, kèm điều kiện (ngưỡng) và thời hạn hiệu lực. CTA chính: View coupon hoặc Apply coupon, dẫn đến coupon_link hoặc một bảng coupon trong ứng dụng. Khả năng tiếp cận: Thông báo mức giảm giá, ngưỡng và hạn dùng dưới dạng văn bản thuần túy để trình đọc màn hình có thể truyền đạt toàn bộ ưu đãi. Coupon Card (COUPON_CARD)

• Các trường tối thiểu: content.coupon_id. Đối với UI, dùng data.coupon_title, data.discount, data.threshold, data.scope, data.start_time, data.end_time, data.coupon_link.

• Hiển thị: Hiển thị nổi bật số tiền hoặc tỷ lệ phần trăm giảm giá, kèm điều kiện (ngưỡng) và thời hạn hiệu lực. CTA chính: View coupon hoặc Apply coupon, dẫn đến coupon_link hoặc một bảng coupon trong ứng dụng.

• Khả năng tiếp cận: Thông báo mức giảm giá, ngưỡng và hạn dùng dưới dạng văn bản thuần túy để trình đọc màn hình có thể truyền đạt toàn bộ ưu đãi.

• Logistics Card (LOGISTICS_CARD)

Các trường tối thiểu: content.order_id, content.package_id. Đối với UI chi tiết, dùng data.packages[*].product_name, product_image, quantity, tracking_number, shipping_provider_name, predict_delivery_time_*, và lịch sử tracking. Hiển thị: Tóm tắt gói hàng chính trong tiêu đề thẻ (đơn vị vận chuyển, số theo dõi, trạng thái mới nhất và dấu thời gian), tiếp theo là các thumbnail và tên sản phẩm. CTA chính: Track package, mở một chế độ xem theo dõi chuyên dụng được xây dựng từ data.tracking hoặc một liên kết theo dõi bên ngoài. Khả năng tiếp cận: Đảm bảo văn bản trạng thái mới nhất (ví dụ: "Out for delivery") luôn hiện diện ở dạng văn bản và không chỉ được biểu diễn bằng biểu tượng hoặc màu sắc. Logistics Card (LOGISTICS_CARD)

• Các trường tối thiểu: content.order_id, content.package_id. Đối với UI chi tiết, dùng data.packages[*].product_name, product_image, quantity, tracking_number, shipping_provider_name, predict_delivery_time_*, và lịch sử tracking.

• Hiển thị: Tóm tắt gói hàng chính trong tiêu đề thẻ (đơn vị vận chuyển, số theo dõi, trạng thái mới nhất và dấu thời gian), tiếp theo là các thumbnail và tên sản phẩm. CTA chính: Track package, mở một chế độ xem theo dõi chuyên dụng được xây dựng từ data.tracking hoặc một liên kết theo dõi bên ngoài.

• Khả năng tiếp cận: Đảm bảo văn bản trạng thái mới nhất (ví dụ: "Out for delivery") luôn hiện diện ở dạng văn bản và không chỉ được biểu diễn bằng biểu tượng hoặc màu sắc.

• Các thẻ vận chuyển & địa chỉ chủ động (seller_im_proactive_confirm_address, seller_im_proactive_order_received, seller_im_proactive_abnormal_logistics)

Các trường tối thiểu: Cùng khung cấu trúc cốt lõi với LOGISTICS_CARD (các định danh đơn hàng và gói hàng). Khi hiện diện, cũng hiển thị tên giao hàng, số điện thoại, và tóm tắt địa chỉ của người mua cho seller_im_proactive_confirm_address, và sự kiện vận chuyển mới nhất cho seller_im_proactive_abnormal_logistics. Hiển thị:

Làm nổi bật tình huống trong tiêu đề thẻ (ví dụ: "Confirm shipping address", "We have received your order", "Issue with your delivery"). Sử dụng một CTA chính duy nhất cho mỗi thẻ: Confirm address, Track package, hoặc Open support options, mà nên deep link vào luồng chỉnh sửa địa chỉ, theo dõi, hoặc khởi tạo hậu mãi phù hợp. Xem thẻ như là trạng thái/thông báo chỉ đọc trong seller workbench; bất kỳ hành động thay đổi trạng thái nào cũng chỉ được xảy ra sau khi người dùng tương tác rõ ràng với CTA.

Khả năng tiếp cận: Cung cấp các mô tả văn bản rõ ràng về điều mà thẻ đang yêu cầu người mua làm (xác nhận, xem lại, hoặc liên hệ hỗ trợ) sao cho ngay cả trong các tình huống chỉ-văn-bản hoặc trình đọc màn hình thì ý định vẫn rõ ràng. Proactive logistics & address cards (seller_im_proactive_confirm_address, seller_im_proactive_order_received, seller_im_proactive_abnormal_logistics)

• Các trường tối thiểu: Cùng khung cấu trúc cốt lõi với LOGISTICS_CARD (các định danh đơn hàng và gói hàng). Khi hiện diện, cũng hiển thị tên giao hàng, số điện thoại, và tóm tắt địa chỉ của người mua cho seller_im_proactive_confirm_address, và sự kiện vận chuyển mới nhất cho seller_im_proactive_abnormal_logistics.
• Hiển thị:

Làm nổi bật tình huống trong tiêu đề thẻ (ví dụ: "Confirm shipping address", "We have received your order", "Issue with your delivery"). Sử dụng một CTA chính duy nhất cho mỗi thẻ: Confirm address, Track package, hoặc Open support options, mà nên deep link vào luồng chỉnh sửa địa chỉ, theo dõi, hoặc khởi tạo hậu mãi phù hợp. Xem thẻ như là trạng thái/thông báo chỉ đọc trong seller workbench; bất kỳ hành động thay đổi trạng thái nào cũng chỉ được xảy ra sau khi người dùng tương tác rõ ràng với CTA. Display

: - Làm nổi bật tình huống trong tiêu đề thẻ (ví dụ: "Confirm shipping address", "We have received your order", "Issue with your delivery").

• Sử dụng một CTA chính duy nhất cho mỗi thẻ: Confirm address, Track package, hoặc Open support options, mà nên deep link vào luồng chỉnh sửa địa chỉ, theo dõi, hoặc khởi tạo hậu mãi phù hợp.

• Xem thẻ như là trạng thái/thông báo chỉ đọc trong seller workbench; bất kỳ hành động thay đổi trạng thái nào cũng chỉ được xảy ra sau khi người dùng tương tác rõ ràng với CTA.

• Khả năng tiếp cận: Cung cấp các mô tả văn bản rõ ràng về điều mà thẻ đang yêu cầu người mua làm (xác nhận, xem lại, hoặc liên hệ hỗ trợ) sao cho ngay cả trong các tình huống chỉ-văn-bản hoặc trình đọc màn hình thì ý định vẫn rõ ràng.

Cơ chế Dự phòng Văn bản

Thiết kế seller workbench để suy giảm một cách hợp lý khi không thể hiển thị thẻ phong phú.

• Khi nào dự phòng

type không xác định hoặc chưa được hỗ trợ bởi ma trận khả năng UI của bạn. type đã biết nhưng cấu trúc data mong đợi bị thiếu hoặc không vượt qua xác thực. Các tài nguyên media (URL hình ảnh/video) không tải được hoặc đã hết hạn. Nền tảng từ chối việc gửi hoặc cập nhật một thẻ vì giới hạn tốc độ, vấn đề quyền, hoặc các kiểm tra chính sách/kiểm duyệt. When to fallback

• type không xác định hoặc chưa được hỗ trợ bởi ma trận khả năng UI của bạn.

• type đã biết nhưng cấu trúc data mong đợi bị thiếu hoặc không vượt qua xác thực.

• Các tài nguyên media (URL hình ảnh/video) không tải được hoặc đã hết hạn.

• Nền tảng từ chối việc gửi hoặc cập nhật một thẻ vì giới hạn tốc độ, vấn đề quyền, hoặc các kiểm tra chính sách/kiểm duyệt.

• Thứ tự ưu tiên dự phòng

Card UI: Hiển thị một thẻ tương tác đầy đủ bằng type và data bất cứ khi nào có thể. Chế độ xem rich text: Nếu bạn không thể hỗ trợ thành phần thẻ cho một type nhất định, hãy định dạng data thành một khối văn bản có cấu trúc (ví dụ: tóm tắt đơn hàng, trạng thái vận chuyển, chi tiết coupon) và hiển thị nó như một tin nhắn không tương tác, giữ lại các giá trị chính. Chế độ xem plain text: Nếu data không có sẵn hoặc phân tích cú pháp thất bại, hãy dự phòng về plaintext (khi hiện diện) hoặc xây dựng một mẩu văn bản tối thiểu từ content (ví dụ: "Logistics update for order {order_id} – tracking number {tracking_number}"). Fallback priority

1. Card UI: Hiển thị một thẻ tương tác đầy đủ bằng type và data bất cứ khi nào có thể.
2. Chế độ xem rich text: Nếu bạn không thể hỗ trợ thành phần thẻ cho một type nhất định, hãy định dạng data thành một khối văn bản có cấu trúc (ví dụ: tóm tắt đơn hàng, trạng thái vận chuyển, chi tiết coupon) và hiển thị nó như một tin nhắn không tương tác, giữ lại các giá trị chính.
3. Chế độ xem plain text: Nếu data không có sẵn hoặc phân tích cú pháp thất bại, hãy dự phòng về plaintext (khi hiện diện) hoặc xây dựng một mẩu văn bản tối thiểu từ content (ví dụ: "Logistics update for order {order_id} – tracking number {tracking_number}").

• Các trường phải được bảo toàn trong bất kỳ dự phòng nào

Định danh đơn hàng: order_id, và nếu áp dụng sku_id hoặc order_line_item_ids. Định danh vận chuyển: package_id và/hoặc tracking_number. (Các) URL deep-link chính: liên kết chi tiết đơn hàng, liên kết theo dõi, liên kết khởi tạo hậu mãi, liên kết chỉnh sửa địa chỉ. Văn bản trạng thái dễ đọc cho con người (ví dụ: "Awaiting shipment", "Out for delivery", "Delivery exception"). Fields that must be preserved in any fallback

• Định danh đơn hàng: order_id, và nếu áp dụng sku_id hoặc order_line_item_ids.

• Định danh vận chuyển: package_id và/hoặc tracking_number.

• (Các) URL deep-link chính: liên kết chi tiết đơn hàng, liên kết theo dõi, liên kết khởi tạo hậu mãi, liên kết chỉnh sửa địa chỉ.

• Văn bản trạng thái dễ đọc cho con người (ví dụ: "Awaiting shipment", "Out for delivery", "Delivery exception").

• Cách diễn đạt CTA ở chế độ văn bản

Sử dụng văn bản rõ ràng, hướng hành động với các liên kết tường minh, ví dụ:

"View order details: {order_link}" "Track package: {tracking_link}" "Confirm shipping address: {address_link}" "Open return / refund page: {aftersales_link}"

Tránh phơi bày các tham số chuỗi truy vấn thô hoặc các ID nội bộ trong văn bản hiển thị; giữ các chi tiết kỹ thuật trong logs, không phải trong các CTA hiển thị cho người dùng. CTA phrasing in text mode

• Sử dụng văn bản rõ ràng, hướng hành động với các liên kết tường minh, ví dụ:

"View order details: {order_link}" "Track package: {tracking_link}" "Confirm shipping address: {address_link}" "Open return / refund page: {aftersales_link}" Use clear, action-oriented text with explicit links, for example: - "View order details: {order_link}"

• "Track package: {tracking_link}"

• "Confirm shipping address: {address_link}"

• "Open return / refund page: {aftersales_link}"

• Tránh phơi bày các tham số chuỗi truy vấn thô hoặc các ID nội bộ trong văn bản hiển thị; giữ các chi tiết kỹ thuật trong logs, không phải trong các CTA hiển thị cho người dùng.

Danh sách Kiểm tra Triển khai

• Phát hiện loại phía máy chủ

Phân tích cú pháp type, content, data, và plaintext cho mọi tin nhắn được trả về bởi các Customer Service API. Duy trì một ánh xạ từ type tin nhắn (và, khi liên quan, các định danh thẻ cụ thể như seller_im_proactive_confirm_address) tới các thành phần UI và các hành động được hỗ trợ. Server-side type detection

• Phân tích cú pháp type, content, data, và plaintext cho mọi tin nhắn được trả về bởi các Customer Service API.

• Duy trì một ánh xạ từ type tin nhắn (và, khi liên quan, các định danh thẻ cụ thể như seller_im_proactive_confirm_address) tới các thành phần UI và các hành động được hỗ trợ.

• Ma trận khả năng UI

Lưu trữ một cấu hình mô tả, cho mỗi loại tin nhắn, liệu seller workbench có hỗ trợ hiển thị thẻ đầy đủ, thẻ + hành động, hay chỉ-văn-bản hay không. Sử dụng ma trận này tại thời điểm hiển thị để quyết định giữa thẻ gốc, dự phòng rich-text, và dự phòng plain-text. UI capability matrix

• Lưu trữ một cấu hình mô tả, cho mỗi loại tin nhắn, liệu seller workbench có hỗ trợ hiển thị thẻ đầy đủ, thẻ + hành động, hay chỉ-văn-bản hay không.

• Sử dụng ma trận này tại thời điểm hiển thị để quyết định giữa thẻ gốc, dự phòng rich-text, và dự phòng plain-text.

• Hiển thị văn bản và HTML an toàn

Xem plaintext như văn bản không tin cậy: escape HTML, không thực thi scripts, và tránh chèn HTML thô từ data. Chỉ cho phép một tập hợp định dạng tối thiểu (ngắt dòng, nhấn mạnh cơ bản) trong seller workbench; tránh nhúng iframe hoặc các widget của bên thứ ba bên trong các thẻ. Safe text and HTML rendering

• Xem plaintext như văn bản không tin cậy: escape HTML, không thực thi scripts, và tránh chèn HTML thô từ data.

• Chỉ cho phép một tập hợp định dạng tối thiểu (ngắt dòng, nhấn mạnh cơ bản) trong seller workbench; tránh nhúng iframe hoặc các widget của bên thứ ba bên trong các thẻ.

• Xác thực deep-link

Đưa vào danh sách trắng các tên miền cho deep links (ví dụ: các tên miền chính thức của TikTok Shop và các tên miền ISV của riêng bạn). Xác thực các scheme URL trước khi điều hướng; mở các liên kết trong một webview hoặc tab trình duyệt được kiểm soát và xử lý lỗi một cách hợp lý (ví dụ: hiển thị "Link unavailable" nếu không thể đến được đích). Deep-link validation

• Đưa vào danh sách trắng các tên miền cho deep links (ví dụ: các tên miền chính thức của TikTok Shop và các tên miền ISV của riêng bạn).

• Xác thực các scheme URL trước khi điều hướng; mở các liên kết trong một webview hoặc tab trình duyệt được kiểm soát và xử lý lỗi một cách hợp lý (ví dụ: hiển thị "Link unavailable" nếu không thể đến được đích).

• Bề mặt lỗi và thử lại

Khi một hành động được kích hoạt từ một thẻ (ví dụ: "Confirm address", "Track package") thất bại, hãy hiển thị một trạng thái lỗi nội tuyến trên thẻ và ghi log thất bại với message_id, order_id liên quan và request_id của API. Triển khai thử lại có giới hạn với các idempotency key ở phía máy chủ; không bao giờ gửi lại cùng một hành động nhiều lần từ UI mà không có phản hồi rõ ràng. Error surfaces and retries

• Khi một hành động được kích hoạt từ một thẻ (ví dụ: "Confirm address", "Track package") thất bại, hãy hiển thị một trạng thái lỗi nội tuyến trên thẻ và ghi log thất bại với message_id, order_id liên quan và request_id của API.

• Triển khai thử lại có giới hạn với các idempotency key ở phía máy chủ; không bao giờ gửi lại cùng một hành động nhiều lần từ UI mà không có phản hồi rõ ràng.

• Ghi log kiểm toán và khả năng quan sát

Ghi log việc tiếp nhận tin nhắn, hiển thị thẻ, các tương tác của người dùng (nhấp vào các CTA), và các lệnh gọi API hạ nguồn theo cách có thể tương quan theo từng cuộc trò chuyện và đơn hàng. Nắm bắt đủ ngữ cảnh (type tin nhắn, các định danh, các chuyển đổi trạng thái) để tái tạo lại những gì người bán và người mua đã thấy trong workbench trong các cuộc điều tra sự cố. Audit logging and observability

• Ghi log việc tiếp nhận tin nhắn, hiển thị thẻ, các tương tác của người dùng (nhấp vào các CTA), và các lệnh gọi API hạ nguồn theo cách có thể tương quan theo từng cuộc trò chuyện và đơn hàng.

• Nắm bắt đủ ngữ cảnh (type tin nhắn, các định danh, các chuyển đổi trạng thái) để tái tạo lại những gì người bán và người mua đã thấy trong workbench trong các cuộc điều tra sự cố.

• Khả năng tiếp cận và quốc tế hóa

Đảm bảo tất cả các hành động của thẻ có thể được thao tác qua bàn phím và được thông báo cho trình đọc màn hình. Không mã hóa thông tin quan trọng về nghiệp vụ chỉ trong hình ảnh hoặc màu sắc; luôn bao gồm một dòng trạng thái dạng văn bản. Thiết kế các bố cục có thể chứa các chuỗi đã bản địa hóa với độ dài khác nhau mà không cắt ngắn thông tin chính. Accessibility and internationalization

• Đảm bảo tất cả các hành động của thẻ có thể được thao tác qua bàn phím và được thông báo cho trình đọc màn hình.
• Không mã hóa thông tin quan trọng về nghiệp vụ chỉ trong hình ảnh hoặc màu sắc; luôn bao gồm một dòng trạng thái dạng văn bản.
• Thiết kế các bố cục có thể chứa các chuỗi đã bản địa hóa với độ dài khác nhau mà không cắt ngắn thông tin chính.

Thiết kế Giải pháp API

Mô tả Giải pháp

Giải pháp này tập trung vào sự kết hợp mạnh mẽ của TikTok Shop Customer Service API và Return/Refund/Cancel API. Nó điều phối toàn bộ vòng đời hậu mãi thông qua các message cards tương tác được gửi trong một cuộc trò chuyện.

Các nguyên tắc kiến trúc cốt lõi là:

• Lớp Trình bày (Message Cards): Tất cả các hành động hậu mãi và hiển thị trạng thái được hiển thị dưới dạng các message cards có cấu trúc, tương tác bên trong cuộc trò chuyện chat. Điều này thay thế giao tiếp văn bản không cấu trúc, giảm sự mơ hồ và cải thiện hiệu quả. Thiết kế của các thẻ này được suy ra từ tài liệu Message Types.
• Lớp Hành động (Customer Service & Post-Sales APIs): Các hành động của nhân viên trên một message card (ví dụ: nhấp "Approve Refund") được ánh xạ trực tiếp tới các lệnh gọi API cụ thể. Send Message API được dùng để gửi các thẻ, trong khi các Return/Refund/Cancel API được dùng để thực thi logic nghiệp vụ.
• Lớp Quản lý Trạng thái (Webhooks & API Polling): Hệ thống chủ yếu dựa vào các sự kiện Webhook (ví dụ: RETURN_STATUS_CHANGED, CANCELLATION_STATUS_CHANGED) để đồng bộ trạng thái theo thời gian thực. Điều này được bổ sung bởi một cơ chế thăm dò (ví dụ: Search Returns API) để đối chiếu dữ liệu và xử lý mọi thất bại tiềm tàng trong việc gửi Webhook.
• Lớp Xác thực & Điều kiện đủ: Trước khi trình bày một hành động cho nhân viên, hệ thống dùng các API điều kiện đủ (ví dụ: Get Aftersale Eligibility) để đảm bảo hành động được yêu cầu là hợp lệ cho trạng thái hiện tại của đơn hàng hoặc lần trả hàng, ngăn ngừa lỗi và cung cấp một trải nghiệm có hướng dẫn cho nhân viên.

Thiết kế này tạo ra một hệ thống vòng kín nơi nhân viên có thể tự tin quản lý các quy trình hậu mãi phức tạp mà không bao giờ phải rời khỏi bảng điều khiển dịch vụ khách hàng của họ.

Tổng quan Quy trình Hậu mãi

Các sơ đồ bên dưới minh họa ba quy trình hậu mãi chính có thể được quản lý qua message cards:

• Cancel: Xảy ra trước khi một đơn hàng được giao. Đây là luồng đơn giản nhất, thường yêu cầu một bước phê duyệt duy nhất.
• Refund Only: Được dùng khi người mua không cần trả lại mặt hàng (ví dụ: sản phẩm không được nhận hoặc bị hư hỏng nghiêm trọng). Cốt lõi của quy trình này là quyết định của người bán về việc phê duyệt hay từ chối hoàn tiền.
• Return & Refund: Luồng phức tạp nhất, liên quan đến việc trả lại hàng hóa vật lý. Nó bao gồm nhiều giai đoạn: người bán phê duyệt, người mua gửi hàng, người bán nhận hàng và kiểm tra, và cuối cùng là nền tảng hoàn tiền.

Mỗi bước trong các luồng này có thể được biểu diễn bằng một cập nhật message card hoặc một tin nhắn hệ thống mới, giữ cho cả người mua và người bán được thông tin.

Sơ đồ trình tự này trình bày chi tiết các tương tác cho một quy trình Return & Refund điển hình được khởi tạo và quản lý qua message cards:

1. Khởi tạo dựa trên thẻ: Nhân viên gửi một RETURN_REFUND_CARD cho người mua. Người mua điền và gửi nó.
2. Hành động API: Ứng dụng ISV nhận được nội dung gửi của thẻ và gọi Create Return API.
3. Quyết định của Người bán qua Thẻ: Nhân viên nhận được một thẻ mới hoặc một chế độ xem cập nhật hiển thị yêu cầu đang chờ xử lý. Nhân viên nhấp "Approve", kích hoạt lệnh gọi Approve Return API.
4. Đồng bộ Trạng thái dựa trên Webhook: Nền tảng TikTok Shop xử lý việc phê duyệt và gửi một Webhook RETURN_STATUS_CHANGED. Ứng dụng ISV tiêu thụ sự kiện này để cập nhật trạng thái nội bộ của nó và làm mới UI (ví dụ: cập nhật thẻ để hiển thị "Awaiting Buyer Shipment").
5. Hoàn tất Quy trình: Các bước tiếp theo, như việc người bán xác nhận đã nhận mặt hàng được trả lại, tuân theo cùng một mô hình của các lệnh gọi API và các cập nhật dựa trên Webhook cho đến khi đạt được trạng thái cuối cùng "Refund Completed".

Trình tự này làm nổi bật bản chất phản ứng của việc tích hợp, nơi hệ thống phản hồi các sự kiện và các lệnh gọi API để dẫn dắt quy trình tiến lên phía trước.

Phân loại Thẻ cho các Hành động Hậu mãi

Một sự phân loại thẻ rõ ràng và nhất quán là thiết yếu để xây dựng một trải nghiệm trực quan cho nhân viên. Các thẻ sau đây, được suy ra từ tài liệu Message Types chính thức, là nền tảng cho các quy trình hậu mãi.

Card Type	Mục đích	Các trường content chính	Các trường data chính (để hiển thị UI)
RETURN_REFUND_CARD	Khởi tạo hoặc hiển thị trạng thái của một yêu cầu trả hàng hoặc hoàn tiền. Đây là thẻ chính cho các hành động hậu mãi.	order_id, sku_id	product_name, product_image, paid_price, quantity, return_status, return_reason, refund_amount
ORDER_CARD	Cung cấp ngữ cảnh về đơn hàng gốc liên quan đến yêu cầu hậu mãi.	order_id	order_status, product_name, quantity, paid_price, order_link
LOGISTICS_CARD	Hiển thị thông tin vận chuyển trả hàng, bao gồm các số theo dõi và các cập nhật trạng thái.	order_id, package_id	tracking_number, shipping_provider_name, tracking (history), delivery_option
PRODUCT_CARD	Chia sẻ các sản phẩm thay thế hoặc thay thế với người mua.	product_id	product_name, product_image, product_highest_price, product_link
TEXT, IMAGE, VIDEO	Được dùng cho giao tiếp bổ sung, như gửi hướng dẫn, yêu cầu thêm bằng chứng từ người mua, hoặc xác nhận các hành động.	content (text) hoặc url (media)	N/A

Payload và Xác thực

Khi gửi một thẻ bằng endpoint POST /customer_service/202309/conversations/{conversation_id}/messages, body phải được cấu trúc đúng cách.

Ví dụ: Gửi một RETURN_REFUND_CARD

JSONWord Wrap

{
"type": "RETURN_REFUND_CARD",
"content": "{\\"order_id\\":\\"580874485811283206\\",\\"sku_id\\":\\"7494560109732363423\\"}"
}

Quy tắc Xác thực:

• Trường content phải là một chuỗi JSON đã được tuần tự hóa (serialized).
• Đối với RETURN_REFUND_CARD, cả order_id và sku_id đều bắt buộc để xác định mặt hàng cụ thể trong quy trình hậu mãi.
• Trước khi gửi một RETURN_REFUND_CARD, một thực hành tốt nhất là gọi trước endpoint GET /return_refund/.../aftersale_eligibility để đảm bảo đơn hàng/mặt hàng đủ điều kiện cho việc trả hàng hoặc hoàn tiền. Điều này ngăn việc gửi một thẻ hành động không thể được thực hiện.

Ánh xạ Hành động và Điều phối Trạng thái

Ánh xạ Endpoint API

Bảng sau đây ánh xạ các hành động chính của nhân viên trong quy trình hậu mãi tới các endpoint API tương ứng của chúng.

Agent Action	HTTP Method & Endpoint	Key Parameters	Notes & Security
Check Eligibility	GET /return_refund/202512/orders/{order_id}/aftersale_eligibility	request_types (ví dụ: REFUND, CANCEL)	Sử dụng cái này một cách phòng ngừa để chỉ hiển thị các nút hành động hợp lệ cho nhân viên.
Approve Request	POST /return_refund/202309/returns/{return_id}/approve	decision (ví dụ: APPROVE_RETURN, APPROVE_REFUND)	Yêu cầu scope seller.return_refund.basic. Sử dụng một Idempotency-Key để ngăn các phê duyệt trùng lặp.
Reject Request	POST /return_refund/202309/returns/{return_id}/reject	decision, reject_reason, comment	reject_reason nên được chọn từ một danh sách lấy qua GET /return_refund/202309/reject_reasons API.
Confirm Goods Received	POST /return_refund/202309/returns/{return_id}/approve	decision (APPROVE_RECEIVED_PACKAGE)	Kích hoạt quy trình hoàn tiền cuối cùng bởi nền tảng. Hành động này không thể đảo ngược.
Cancel Order	POST /return_refund/202309/cancellations	order_id, cancel_reason	Cho các lần hủy do người bán khởi tạo. Kiểm tra điều kiện đủ trước. Sử dụng order_line_item_ids cho các lần hủy một phần.
Approve Cancellation	POST /return_refund/202309/cancellations/{cancel_id}/approve	cancel_id	Phê duyệt một yêu cầu hủy được khởi tạo bởi người mua.

Máy Trạng thái và Cập nhật Thẻ (Return & Refund)

Trạng thái của một lần trả hàng quyết định các hành động khả dụng và cách message card nên được hiển thị.

Current Status	Allowed Agent Actions	Next Status (on Success)	Card Update Strategy
RETURN_OR_REFUND_REQUEST_PENDING	Approve Return, Approve Refund (No Return), Reject	AWAITING_BUYER_SHIP, REQUEST_SUCCESS, REQUEST_REJECTED	Cập nhật thẻ với các nút hành động. Sau hành động, vô hiệu hóa các nút và hiển thị "Processing...". Khi Webhook xác nhận, cập nhật văn bản trạng thái.
AWAITING_BUYER_SHIP	(Chỉ đọc đối với nhân viên)	BUYER_SHIPPED_ITEM	Hiển thị trạng thái và địa chỉ/nhãn vận chuyển trả hàng. Lắng nghe Webhook.
BUYER_SHIPPED_ITEM	Confirm Goods Received, Reject Goods	REQUEST_SUCCESS, RECEIVE_REJECTED	Cập nhật thẻ với các nút hành động mới. Khi Webhook xác nhận, cập nhật thành "Refund Processing".
REQUEST_SUCCESS	(Chỉ đọc đối với nhân viên)	RETURN_OR_REFUND_REQUEST_COMPLETE	Hiển thị trạng thái "Refund Processing". Khi Webhook cuối cùng, cập nhật thành "Refund Completed".
REQUEST_REJECTED	(Chỉ đọc đối với nhân viên)	N/A	Hiển thị trạng thái cuối cùng "Request Rejected" và lý do được cung cấp.
RETURN_OR_REFUND_REQUEST_COMPLETE	(Chỉ đọc đối với nhân viên)	N/A	Hiển thị trạng thái cuối cùng "Completed".
Webhook vs. Polling: Luôn ưu tiên tích hợp Webhook cho các cập nhật trạng thái theo thời gian thực. Sử dụng thăm dò API (Search Returns, Search Cancellations) như một cơ chế dự phòng để đối chiếu các trạng thái định kỳ và khôi phục sau bất kỳ sự kiện bị bỏ lỡ nào. Sự kết hợp của cả hai đảm bảo một hệ thống mạnh mẽ và phản hồi nhanh.

Hướng dẫn Triển khai và Các Trường hợp Kiểm thử

Luồng Tích hợp Từng bước

1. Xác thực & Phân quyền:

Hướng dẫn người bán phân quyền cho ứng dụng của bạn, đảm bảo bạn yêu cầu các scope seller.return_refund.basic và seller.customer_service. Lưu trữ an toàn access-token và shop_cipher cho mỗi người bán. Authentication & Authorization

: - Hướng dẫn người bán phân quyền cho ứng dụng của bạn, đảm bảo bạn yêu cầu các scope seller.return_refund.basic và seller.customer_service.

• Lưu trữ an toàn access-token và shop_cipher cho mỗi người bán.

2. Đăng ký Webhook:

Trong cài đặt ứng dụng của bạn trên TikTok Shop Partner Center, đăng ký các sự kiện RETURN_STATUS_CHANGED và CANCELLATION_STATUS_CHANGED. Triển khai một endpoint công khai trong backend của bạn để nhận và xác thực các yêu cầu Webhook POST này. Webhook Subscription

: - Trong cài đặt ứng dụng của bạn trên TikTok Shop Partner Center, đăng ký các sự kiện RETURN_STATUS_CHANGED và CANCELLATION_STATUS_CHANGED.

• Triển khai một endpoint công khai trong backend của bạn để nhận và xác thực các yêu cầu Webhook POST này.

3. Xây dựng Logic Gửi Thẻ:

Tích hợp với endpoint POST /customer_service/202309/conversations/{conversation_id}/messages. Tạo một service xây dựng chuỗi content JSON cho mỗi loại thẻ (ví dụ: ORDER_CARD, RETURN_REFUND_CARD). Build the Card Sending Logic

: - Tích hợp với endpoint POST /customer_service/202309/conversations/{conversation_id}/messages.

• Tạo một service xây dựng chuỗi content JSON cho mỗi loại thẻ (ví dụ: ORDER_CARD, RETURN_REFUND_CARD).

4. Phát triển Trình xử lý Hành động:

Tạo một backend service ánh xạ các yêu cầu đến từ UI của bạn (ví dụ: một nhân viên nhấp "Approve") tới endpoint Post-Sales API đúng (ví dụ: Approve Return). Service này nên xử lý việc xây dựng tham số, ký API, và xử lý lỗi. Hãy nhớ triển khai Idempotency-Key cho tất cả các thao tác ghi. Develop the Action Handler

: - Tạo một backend service ánh xạ các yêu cầu đến từ UI của bạn (ví dụ: một nhân viên nhấp "Approve") tới endpoint Post-Sales API đúng (ví dụ: Approve Return).

• Service này nên xử lý việc xây dựng tham số, ký API, và xử lý lỗi. Hãy nhớ triển khai Idempotency-Key cho tất cả các thao tác ghi.

5. Thiết kế UI Cuộc trò chuyện:

Trong giao diện chat của nhân viên, tạo một cơ chế để hiển thị các message cards dựa trên các trường type và data của tin nhắn. Các phần tử có thể hành động (các nút) trên thẻ nên kích hoạt các lệnh gọi đến trình xử lý hành động backend của bạn. Design the Conversation UI

: - Trong giao diện chat của nhân viên, tạo một cơ chế để hiển thị các message cards dựa trên các trường type và data của tin nhắn.

• Các phần tử có thể hành động (các nút) trên thẻ nên kích hoạt các lệnh gọi đến trình xử lý hành động backend của bạn.

6. Triển khai Đồng bộ Trạng thái:

Endpoint Webhook của bạn nên phân tích cú pháp các sự kiện đến và cập nhật cơ sở dữ liệu cục bộ của bạn với trạng thái mới của lần trả hàng hoặc hủy đơn. Sử dụng một kênh giao tiếp thời gian thực (ví dụ: WebSockets) để đẩy các cập nhật này tới UI của nhân viên liên quan, đảm bảo thông tin thẻ và trạng thái luôn được cập nhật. Implement State Synchronization

: - Endpoint Webhook của bạn nên phân tích cú pháp các sự kiện đến và cập nhật cơ sở dữ liệu cục bộ của bạn với trạng thái mới của lần trả hàng hoặc hủy đơn.

• Sử dụng một kênh giao tiếp thời gian thực (ví dụ: WebSockets) để đẩy các cập nhật này tới UI của nhân viên liên quan, đảm bảo thông tin thẻ và trạng thái luôn được cập nhật.

7. Ghi log và Kiểm toán:

Ghi log mỗi lệnh gọi API, các tham số của nó, phản hồi, và bất kỳ request_id liên quan nào. Ghi log mỗi sự kiện Webhook đến. Điều này rất quan trọng để gỡ lỗi và kiểm toán toàn bộ quy trình hậu mãi. Logging and Auditing

: - Ghi log mỗi lệnh gọi API, các tham số của nó, phản hồi, và bất kỳ request_id liên quan nào.

• Ghi log mỗi sự kiện Webhook đến. Điều này rất quan trọng để gỡ lỗi và kiểm toán toàn bộ quy trình hậu mãi.

Các Payload Mẫu

Gửi một Order Card:

JSONWord Wrap

// POST /customer_service/202309/conversations/{conv_id}/messages
{
"type": "ORDER_CARD",
"content": "{\\"order_id\\":\\"576473917261320779\\"}"
}

Phê duyệt một Yêu cầu Trả hàng:

JSONWord Wrap

// POST /return_refund/202309/returns/4035319218955782461/approve
{
"decision": "APPROVE_RETURN",
"buyer_keep_item": false
}

Các Trường hợp Kiểm thử Đầu-cuối

Trường hợp Kiểm thử 1: Hoàn tiền Toàn phần (Mặt hàng Không được Nhận)

• Điều kiện tiên quyết: Đơn hàng ở trạng thái IN_TRANSIT. Người mua liên hệ hỗ trợ.
• Các bước:

Nhân viên gửi một ORDER_CARD để xác nhận đơn hàng. Nhân viên xác minh vấn đề và quyết định hoàn tiền. Nhân viên khởi tạo một REFUND bằng Create Return API. Nhân viên phê duyệt ngay lập tức bằng Approve Return API với decision: APPROVE_REFUND. Steps

: 1. Nhân viên gửi một ORDER_CARD để xác nhận đơn hàng. 2. Nhân viên xác minh vấn đề và quyết định hoàn tiền. 3. Nhân viên khởi tạo một REFUND bằng Create Return API. 4. Nhân viên phê duyệt ngay lập tức bằng Approve Return API với decision: APPROVE_REFUND.

• Kết quả Mong đợi: Trạng thái trả hàng chuyển sang REQUEST_SUCCESS. Một Webhook được nhận. Thẻ trong chat cập nhật thành "Refund Processing".

Trường hợp Kiểm thử 2: Trả hàng & Hoàn tiền Tiêu chuẩn

• Điều kiện tiên quyết: Đơn hàng ở trạng thái DELIVERED. Người mua muốn trả lại một mặt hàng.
• Các bước:

Nhân viên gửi một RETURN_REFUND_CARD. Người mua điền và gửi. Nhân viên nhấp "Approve" trên thẻ, gọi Approve Return (decision: APPROVE_RETURN). (Mô phỏng) Người mua gửi mặt hàng. Một Webhook BUYER_SHIPPED_ITEM đến. Nhân viên nhấp "Confirm Receipt", gọi Approve Return (decision: APPROVE_RECEIVED_PACKAGE). Các bước:

1. Nhân viên gửi một RETURN_REFUND_CARD. Người mua điền và gửi.
2. Nhân viên nhấp "Approve" trên thẻ, gọi Approve Return (decision: APPROVE_RETURN).
3. (Mô phỏng) Người mua gửi mặt hàng. Một Webhook BUYER_SHIPPED_ITEM đến.
4. Nhân viên nhấp "Confirm Receipt", gọi Approve Return (decision: APPROVE_RECEIVED_PACKAGE).

• Kết quả Mong đợi: Trạng thái tiến triển từ PENDING -> AWAITING_BUYER_SHIP -> BUYER_SHIPPED_ITEM -> REQUEST_SUCCESS. Mỗi thay đổi trạng thái được phản ánh trong UI.

Trường hợp Kiểm thử 3: Từ chối Yêu cầu Trả hàng Không hợp lệ

• Điều kiện tiên quyết: Đơn hàng ở trạng thái DELIVERED trong 30 ngày. Người mua yêu cầu trả hàng vì một lý do không liên quan đến chất lượng.
• Các bước:

Nhân viên kiểm tra điều kiện đủ và phát hiện cửa sổ trả hàng đã đóng. Nhân viên gửi một tin nhắn TEXT giải thích chính sách. Nếu người mua khăng khăng và tạo một yêu cầu, nhân viên nhấp "Reject" trên thẻ. Nhân viên chọn một lý do (ví dụ: "Exceeded return window") và thêm một bình luận. Steps

: 1. Nhân viên kiểm tra điều kiện đủ và phát hiện cửa sổ trả hàng đã đóng. 2. Nhân viên gửi một tin nhắn TEXT giải thích chính sách. 3. Nếu người mua khăng khăng và tạo một yêu cầu, nhân viên nhấp "Reject" trên thẻ. 4. Nhân viên chọn một lý do (ví dụ: "Exceeded return window") và thêm một bình luận.

• Kết quả Mong đợi: Reject Return API được gọi. Trạng thái chuyển sang REQUEST_REJECTED. Thẻ được cập nhật thành một trạng thái cuối cùng, không thể hành động.

Trường hợp Kiểm thử 4: Hủy Một phần do Người bán khởi tạo

• Điều kiện tiên quyết: Đơn hàng ở trạng thái AWAITING_SHIPMENT. Một mặt hàng hết hàng.
• Các bước:

Nhân viên thông báo cho người mua qua một tin nhắn TEXT. Người mua đồng ý hủy mặt hàng. Nhân viên sử dụng một tính năng UI gọi Cancel Order API, chỉ định order_line_item_ids của mặt hàng hết hàng. Các bước:

1. Nhân viên thông báo cho người mua qua một tin nhắn TEXT. Người mua đồng ý hủy mặt hàng.
2. Nhân viên sử dụng một tính năng UI gọi Cancel Order API, chỉ định order_line_item_ids của mặt hàng hết hàng.

• Kết quả Mong đợi: Một bản ghi hủy được tạo. Một Webhook CANCELLATION_STATUS_CHANGED được nhận. ORDER_CARD trong chat được cập nhật để hiển thị một mặt hàng là "Cancelled".

Nội dung này có hữu ích không?Hữu ích

Không hữu ích

PreviousNext