Send Consumption Information của Apple giờ yêu cầu năm trường, không phải mười hai, và đây là từng trường một

Danh sách các dữ kiện mà Apple yêu cầu bạn khi một khách hàng muốn hoàn tiền đã ngắn đi rất nhiều. Payload Send Consumption Information, câu trả lời duy nhất mà một nhà phát triển được gửi vào quyết định hoàn tiền của App Store, trước đây có mười hai trường. Giờ nó còn năm. Apple đã tinh giản nó vào khoảng WWDC24 và gộp phần lớn các câu hỏi lập hồ sơ tài khoản cũ thành hai câu hỏi đơn giản và một con số. Ít trường hơn không phải là một chỉnh sửa nhỏ. Nó thay đổi bằng chứng nào Apple cân nhắc, và thay đổi những trường nào bạn không thể để sai.

Đây là lý do vì sao điều này đáng để bạn chú ý chứ không chỉ là một ghi chú về lược đồ. Payload này là khoảnh khắc duy nhất trong một vụ hoàn tiền của Apple khi phía câu chuyện của bạn đến được với quyết định. Việc hoàn tiền cho một mặt hàng tiêu dùng đảo ngược khoản doanh thu mà bạn đã bỏ tiền thật ra để phân phối, và năm trường là cách bạn nói với Apple rằng sản phẩm đã được phân phối và sử dụng. Bỏ lỡ cửa sổ 12 giờ hoặc điền sai một trường, và Apple sẽ phán quyết chỉ dựa trên khiếu nại của khách hàng.

Send Consumption Information là gì

Send Consumption Information là endpoint App Store Server API mà bạn gọi sau khi Apple gửi đến máy chủ của bạn một thông báo CONSUMPTION_REQUEST. Thông báo đó có nghĩa là một khách hàng đã yêu cầu Apple hoàn tiền cho một giao dịch mua trong ứng dụng và Apple muốn có ý kiến của bạn trước khi quyết định. Bạn trả lời bằng cách PUT một body JSON nhỏ, tức ConsumptionRequest, đến endpoint. Apple đọc nó, cân nhắc nó với lịch sử của khách hàng, và đưa ra quyết định. Bạn không bao giờ quyết định việc hoàn tiền. Bạn cung cấp dữ kiện.

Body chính là toàn bộ giao diện. Không có biểu mẫu riêng, không có kháng nghị, và không có lần gửi thứ hai nào được tính. Bất cứ điều gì bạn gửi trong một payload đó là toàn bộ lập luận của bạn, nên ý nghĩa của mỗi trường quan trọng hơn những gì số lượng trường gợi ra.

Năm trường mà Apple yêu cầu hiện nay

ConsumptionRequest hiện tại có năm thành viên. Ba bắt buộc và hai tùy chọn. Mọi thứ Apple từng hỏi về tài khoản của khách hàng, thời gian gắn bó, tổng chi tiêu trọn đời, tổng số tiền hoàn trọn đời, thời gian sử dụng, đã bị loại khỏi những gì bạn gửi.

customerConsented là cổng chặn

customerConsented là một Boolean, và đó là trường quyết định liệu bạn có gửi bất cứ thứ gì hay không. Nó ghi lại việc khách hàng có đồng ý cho phép bạn chia sẻ dữ liệu tiêu thụ với Apple hay không. Hướng dẫn của Apple rất rõ ràng: nếu khách hàng không đồng ý, đừng gửi thông tin tiêu thụ. Vậy nên đây không phải trường bạn bật thành true để củng cố lập luận của mình. Nó phản ánh một câu trả lời có hoặc không thực sự mà bạn phải nắm giữ sẵn, và giá trị false ở đây có nghĩa là phần còn lại của payload không nên được gửi.

deliveryStatus là trường làm dịch chuyển các vụ hoàn tiền

deliveryStatus là một enum chuỗi, và đó là đòn bẩy mạnh nhất bạn có. Nó cho Apple biết liệu ứng dụng của bạn có thực sự phân phối một giao dịch mua trong ứng dụng hoạt động được hay không. Một giá trị nói có. Bốn giá trị còn lại nói không, mỗi giá trị vì một lý do khác nhau, và mỗi giá trị cho Apple biết khách hàng có một khiếu nại chính đáng.

sampleContentProvided trả lời một câu hỏi về sự công bằng

sampleContentProvided là một Boolean. Nó ghi lại việc bạn có cung cấp cho khách hàng một bản mẫu miễn phí, một bản dùng thử, hoặc thông tin rõ ràng về việc giao dịch mua làm gì trước khi họ mua hay không. Một giá trị true ở đây là một tín hiệu công bằng nhỏ: khách hàng đã có cơ hội biết mình đang mua gì. Bản thân nó không quyết định điều gì, nhưng nó là một trong chỉ ba trường bắt buộc, nên rõ ràng Apple muốn có nó trong mọi phản hồi.

consumptionPercentage giờ là một con số, không phải một trạng thái

Đây là trường thay đổi nhiều nhất. Payload cũ có consumptionStatus, một enum bốn bậc: UNDECLARED, NOT_CONSUMED, PARTIALLY_CONSUMED, FULLY_CONSUMED. Payload mới thay nó bằng consumptionPercentage, một số nguyên đo bằng milliunits. 100,000 milliunits nghĩa là mặt hàng đã được tiêu thụ hoàn toàn, nên 50,000 là một nửa và 0 là chưa động tới. Một con số chính xác tốt hơn một cách chia bốn ô, vì nó cho phép bạn nói rằng một khách hàng đã dùng hết 90 phần trăm gói tín dụng thay vì làm tròn xuống thành tiêu thụ một phần.

Một lưu ý khiến nhiều người vấp phải. Đối với các gói đăng ký tự động gia hạn, Apple tự tính toán mức tiêu thụ từ thời gian đã trôi qua, nên consumptionPercentage dành cho các giao dịch mua tiêu dùng và không gia hạn. Hãy gửi nó ở nơi nó áp dụng, và để Apple tự suy ra ở nơi nó không áp dụng.

refundPreference nêu một sự ưu tiên, không phải một phán quyết

refundPreference là một chuỗi tùy chọn, và đó là nơi bạn cho Apple biết kết quả bạn mong muốn. Nó cũng đã đổi hình thức. Trường cũ là một con số với các giá trị như prefer-grant, prefer-decline, và no-preference. Trường mới là một chuỗi có tên với ba giá trị.

Apple đã bỏ đi những gì, và vì sao điều đó quan trọng

ConsumptionRequest cũ có mười hai trường. Bảy trong số đó đã biến mất khỏi những gì bạn gửi. accountTenure, lifetimeDollarsPurchased, lifetimeDollarsRefunded, playTime, userStatus, platform, và appAccountToken là nửa lập hồ sơ tài khoản của payload, những trường yêu cầu bạn phân loại một khách hàng theo việc họ đã có tài khoản bao lâu, họ đã chi bao nhiêu, họ đã được hoàn bao nhiêu, và họ đã dùng ứng dụng bao lâu.

Apple đã cắt chúng vì một lý do đáng ghi nhận. Những trường đó yêu cầu nhà phát triển giao nộp một hồ sơ về khách hàng, và phần lớn nhà phát triển hoặc để trống hoặc đoán. Năm trường còn lại là về giao dịch mua và việc phân phối, những dữ kiện bạn thực sự có thể xác minh từ hệ thống của chính mình. Sự dịch chuyển là từ việc khách hàng là ai sang việc gì đã xảy ra với giao dịch mua cụ thể này.

Endpoint và chiếc đồng hồ

Bạn gửi payload bằng một HTTP PUT đến endpoint Send Consumption Information, được khóa theo id giao dịch của giao dịch mua đang tranh chấp: PUT /inApps/v1/transactions/consumption/{transactionId}. Một lần thành công trả về 202 Accepted, và body phản hồi rỗng. Phản hồi rỗng đó là điều được mong đợi, không phải một lỗi. Nó xác nhận Apple đã xếp dữ liệu của bạn vào hàng đợi, và nó không cho bạn biết gì về kết quả cuối cùng, thứ đến sau đó dưới dạng một thông báo REFUND hoặc REFUND_DECLINED.

Chiếc đồng hồ là phần bạn không thể kéo giãn. Apple cho bạn 12 giờ kể từ CONSUMPTION_REQUEST để phản hồi. Chỉ phản hồi đầu tiên của bạn được dùng, nên payload đầu tiên phải là bản đầy đủ và chính xác. Apple có thể gửi CONSUMPTION_REQUEST nhiều hơn một lần cho cùng một giao dịch mua, nhưng hạn chót của mỗi lần là cố định, và một lần rà soát thủ công hiếm khi vừa trong 12 giờ qua các múi giờ và cuối tuần.

Một trường bị xử lý sai khiến bạn tốn kém thế nào

Tiền đã rời khỏi túi trước khi việc hoàn tiền diễn ra

Việc hoàn tiền cho một mặt hàng tiêu dùng không phải là một sự đảo ngược gọn gàng. Đến lúc một khách hàng đòi lại tiền cho một gói tín dụng hoặc một loạt sản phẩm do AI tạo ra, bạn đã chi để phân phối nó: suy luận trên GPU cho mỗi yêu cầu, các lệnh gọi API mô hình bên thứ ba tính phí theo token, lưu trữ cho bất cứ thứ gì bạn tạo ra, và mọi khoản chi trả cho nhà sáng tạo hoặc đối tác gắn với việc sử dụng đó. Giá cửa hàng quay về khách hàng. Chi phí phân phối của bạn không quay về với bạn. Vậy nên một vụ hoàn tiền mà lẽ ra bạn có thể phản đối không phải là một sự kiện hòa vốn, nó là một khoản lỗ ròng bằng mọi thứ bạn đã trả để phục vụ tài khoản đó.

Năm trường là cách bạn tránh phải trả hai lần

deliveryStatus được đặt thành DELIVERED và một consumptionPercentage cao là hai dữ kiện cho Apple biết khách hàng đã nhận và đã sử dụng sản phẩm. Chúng là bằng chứng của bạn rằng phần tính toán, các lệnh gọi API, và phần lưu trữ đều đã làm tròn nhiệm vụ. Cứ để payload không được gửi và Apple sẽ không bao giờ nghe thấy điều đó. Apple quyết định dựa trên khiếu nại của khách hàng, việc hoàn tiền dễ được thông qua hơn, và bạn gánh cả khoản doanh thu bị đảo ngược lẫn chi phí phân phối đằng sau nó.

Chargeback là cánh cửa tệ hơn, và sự im lặng chỉ về phía đó

Một khách hàng không thể được thỏa mãn qua quy trình hoàn tiền của Apple vẫn có thể tranh chấp khoản phí với ngân hàng của họ. Một vụ chargeback thẻ là chung cuộc, nó kèm một khoản phí tranh chấp cố định, và nó lấy quyết định ra khỏi tay Apple và tay bạn. Trả lời CONSUMPTION_REQUEST cho tốt giữ cho tranh chấp nằm trong hệ thống của Apple, nơi bạn có tiếng nói. Phớt lờ nó đẩy những trường hợp ranh giới về phía kênh duy nhất nơi bạn không có tiếng nói.

RefundHalt xử lý việc này thế nào

Năm trường trông đơn giản cho đến khi bạn phải điền chúng cho đúng, trong vòng 12 giờ, cho mỗi CONSUMPTION_REQUEST, khóa vào đúng giao dịch. RefundHalt bắt lấy thông báo, đọc chính hồ sơ phân phối và sử dụng của bạn cho giao dịch mua đó, và gửi payload một cách tự động trước khi cửa sổ đóng lại. deliveryStatus phản ánh những gì nhật ký của bạn thực sự cho thấy, consumptionPercentage đến từ mức sử dụng thực chứ không phải một phỏng đoán, và refundPreference tuân theo chính sách bạn đặt một lần. Bạn có được vụ hoàn tiền có thể phản đối được xem xét kèm bằng chứng, chứ không phải một hạn chót bị bỏ lỡ và một quyết định được đưa ra mà không có bạn.