Xử lý trạng thái "đang thực hiện" khi kiểm tra đơn hàng qua API

Processing trong phản hồi API có nghĩa là gì

Trạng thái processing, in_progress hoặc một trạng thái tương đương khác có nghĩa là nhà cung cấp đã nhận đơn hàng vào xử lý nhưng chưa ghi nhận kết quả cuối cùng. Đối với dịch vụ quảng bá, đây có thể là kiểm tra liên kết, chờ đến lượt, khởi chạy tác vụ hoặc cung cấp dần khối lượng đã đặt.

Processing không xác nhận việc hoàn thành thành công và cũng không có nghĩa là lỗi. Sau đó đơn hàng có thể chuyển sang completed, partial, canceled hoặc failed. Khi nhà cung cấp vẫn trả về trạng thái trung gian, đừng tạo yêu cầu mới cho cùng liên kết và cùng khối lượng.

HTTP 200 với trạng thái processing có nghĩa là phản hồi API thành công, không phải đơn hàng đã hoàn thành thành công. Những sự kiện này cần được lưu trữ và xử lý riêng.

Những dữ liệu nào cần để kiểm tra đơn hàng

Để polling, cần ID đơn hàng bên ngoài mà nhà cung cấp trả về khi tạo. Hãy lưu nó cùng với ID nội bộ, khối lượng ban đầu, tham số dịch vụ, liên kết, thời gian tạo và phản hồi API ban đầu. Tìm đơn hàng theo tên kênh, liên kết hoặc khối lượng là không đáng tin cậy: những giá trị này có thể trùng ở nhiều yêu cầu.

Nếu sau khi tạo gặp thời gian chờ, đừng gửi lại yêu cầu tự động. Nhà cung cấp có thể đã nhận yêu cầu, còn phản hồi có thể bị mất trên đường. Trước tiên hãy dùng phương thức tìm kiếm đơn hàng nếu có trong tài liệu, hoặc chuyển trường hợp để kiểm tra.

Nhược điểm của việc chỉ lưu trạng thái hiện tại là khi có tranh chấp không thể khôi phục được khi nào đơn hàng chuyển sang processing, có tiến độ hay không và những phản hồi nào đã đến trước đó.

Ví dụ yêu cầu trạng thái qua curl

Địa chỉ chính xác, phương thức xác thực và tên trường hãy lấy từ tài liệu của nhà cung cấp. Dưới đây là mẫu: các giá trị trong dấu ngoặc nhọn cần được thay bằng dữ liệu của API cụ thể.

Yêu cầu GET cho một đơn hàng

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Ví dụ phản hồi:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Các trường completed_quantity và remains chỉ được nêu làm ví dụ về cấu trúc. Nhà cung cấp có thể dùng progress, start_count, balance hoặc các tên khác. Nhược điểm của cách tiếp cận GET là một số API chỉ chấp nhận kiểm tra trạng thái qua POST.

Ví dụ yêu cầu POST và kiểm tra hàng loạt

Yêu cầu POST trạng thái của một đơn hàng

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Đừng truyền khóa API trong chuỗi URL. Địa chỉ yêu cầu rơi vào nhật ký proxy, hệ thống phân tích, lịch sử trình duyệt và nhật ký kỹ thuật. Nhược điểm của POST là khó kiểm tra thủ công qua thanh địa chỉ hơn, nhưng đó không phải lý do để chuyển bí mật vào URL.

Yêu cầu hàng loạt cho các đơn hàng đang hoạt động

Nếu API hỗ trợ kiểm tra hàng loạt, hãy gửi nhiều ID trong một yêu cầu:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Hãy đối chiếu phản hồi với đơn hàng nội bộ theo ID bên ngoài, không theo vị trí phần tử trong mảng. Nhược điểm của kiểm tra hàng loạt: nhà cung cấp có thể không trả về tất cả đơn hàng, giới hạn kích thước danh sách hoặc chỉ báo lỗi cho một ID.

Cách lên lịch polling cho processing

Sau phản hồi processing đầu tiên, hãy đưa lần kiểm tra tiếp theo vào hàng đợi. Chọn khoảng thời gian theo tài liệu API, giới hạn tần suất và tính chất dịch vụ. Với các tác vụ mà trạng thái thay đổi nhanh, có thể kiểm tra thường xuyên hơn lúc đầu. Với quảng bá dần dần, các yêu cầu ngắn liên tục thường không mang lại thông tin mới.

Một cách thực tế là tăng khoảng nghỉ sau các phản hồi processing giống nhau. Lần kiểm tra đầu tiên diễn ra sau độ trễ khởi đầu, sau đó khoảng thời gian tăng dần đến mức tối đa đã đặt. Nếu API trả về tiến độ hoặc thời gian cập nhật mới, có thể bắt đầu tính từ thay đổi đó.

• Sau khi tạo đơn hàng, đừng kiểm tra trạng thái ngay lập tức nhiều lần liên tiếp: dịch vụ có thể cần thời gian để đưa vào hàng đợi.
• Khi processing lặp lại, hãy tăng khoảng thời gian giữa các yêu cầu thay vì giữ tần suất cố định.
• Thêm độ lệch ngẫu nhiên nhỏ vào thời điểm chạy tác vụ để các đơn hàng không truy vấn API cùng lúc.
• Nếu nhà cung cấp truyền Retry-After hoặc khuyến nghị tương tự, hãy ưu tiên sử dụng nó.
• Với đơn hàng có webhook, vẫn giữ polling kiểm soát: thông báo có thể không đến.

Nhược điểm của polling thưa là giao diện có thể hiển thị trạng thái cũ sau khi thực tế đã hoàn thành. Nhược điểm của polling quá thường xuyên là nguy cơ chạm giới hạn API, nhận 429 và tạo tải không cần thiết.

Những mốc thời gian nào cần lưu để kiểm soát processing

Để phân biệt thực hiện bình thường với bị treo, chỉ một trạng thái hiện tại là không đủ. Với mỗi đơn hàng đang hoạt động, hãy lưu thời gian tạo, lần đầu nhận processing, phản hồi API thành công gần nhất, lần thay đổi trạng thái bên ngoài gần nhất và lần thay đổi tiến độ gần nhất.

Cũng nên lưu khối lượng ban đầu, khối lượng đã xác nhận hoàn thành, phần còn lại và trạng thái gốc của nhà cung cấp. Nếu API không trả về tiến độ, đó không phải lý do để coi đơn hàng bị treo: hãy dựa vào thời gian phản hồi gần nhất và khoảng thời gian xử lý dự kiến nếu được nêu trong điều kiện dịch vụ.

Không thể đặt một con số thời gian chờ tối đa cho tất cả dịch vụ. Hãy dùng thời hạn mà nhà cung cấp nêu cho dịch vụ cụ thể, kèm dự phòng nội bộ cho hàng đợi và cập nhật dữ liệu. Nếu không có thời hạn, hãy đặt quy tắc riêng cho từng nhóm dịch vụ và xem xét lại theo lịch sử xử lý thực tế.

Phải làm gì nếu processing không thay đổi

Processing kéo dài không chứng minh có lỗi. Trước tiên hãy kiểm tra xem có phản hồi API thành công không, completed_quantity hoặc remains có thay đổi không, có webhook không và quy tắc dịch vụ có thay đổi không. Việc không thấy tăng trưởng có thể do độ trễ thống kê của nền tảng hoặc do nhà cung cấp chỉ cập nhật tiến độ ở bước cuối.

Khi vượt quá thời hạn chờ nội bộ, đừng tự động hủy đơn hàng. Hãy thực hiện kiểm tra trạng thái ngoài lịch, yêu cầu dữ liệu bằng phương thức riêng nếu có và kiểm tra lịch sử thông báo. Nếu nhà cung cấp vẫn xác nhận processing, hãy chuyển đơn hàng sang trạng thái nội bộ "cần kiểm tra", nhưng giữ nguyên trạng thái bên ngoài, không thay thế.

• Ghi lại thời gian phản hồi được xác nhận gần nhất và toàn bộ phản hồi API.
• Kiểm tra xem tiến độ có thay đổi kể từ lần truy vấn trước không.
• Giảm tần suất yêu cầu tự động sau khi đạt ngưỡng nội bộ.
• Chuyển cho bộ phận hỗ trợ ID bên ngoài, liên kết, tham số dịch vụ, lịch sử trạng thái và lỗi kỹ thuật.
• Không chạy lại phần còn lại cho đến khi có phản hồi của nhà cung cấp hoặc trạng thái cuối cùng rõ ràng.

Nhược điểm của kiểm tra thủ công là đơn hàng cần sự chú ý của bộ phận hỗ trợ. Nhưng hủy tự động hoặc tạo trùng còn nguy hiểm hơn: việc thực hiện có thể vẫn tiếp tục ở nhà cung cấp.

Cách phân biệt lỗi yêu cầu với trạng thái đơn hàng

Lỗi mạng, thời gian chờ, HTTP 429 và phản hồi 5xx không cho biết trạng thái của chính đơn hàng. Chúng chỉ có nghĩa là không lấy được trạng thái đáng tin cậy mới. Trong tình huống này, hãy giữ trạng thái được xác nhận gần nhất, ghi lỗi kỹ thuật và lên lịch kiểm tra mới.

Với 429, hãy tính đến Retry-After nếu header được truyền. Với lỗi mạng tạm thời và 5xx, hãy tăng khoảng nghỉ giữa các lần thử. Với lỗi xác thực, chữ ký hoặc quyền truy cập, đừng thử lại thường xuyên: cần kiểm tra khóa, thời hạn token, giới hạn IP và cài đặt truy cập.

Nếu API trả về HTTP 200 nhưng JSON không phân tích được hoặc phản hồi không có order_id và status, hãy lưu toàn bộ nội dung phản hồi và đánh dấu lần kiểm tra là không hợp lệ. Đừng thay thế việc thiếu trạng thái bằng completed, canceled hoặc processing.

Khi nào nên dừng các yêu cầu lặp tự động

Polling không nên kéo dài vô hạn. Hãy giới hạn số lần thử kỹ thuật cho lỗi tạm thời và kiểm soát riêng tổng thời gian đơn hàng ở trạng thái processing. Sau khi hết giới hạn thử lại, hãy chuyển tác vụ kiểm tra sang hàng đợi phân tích, thay vì tạo yêu cầu mới mỗi phút mà không có kết quả.

Lặp lại yêu cầu trạng thái thường an toàn nếu phương thức chỉ đọc dữ liệu. Các phương thức tạo, hủy, nạp tiền, khởi động lại và hoàn trả không được lặp lại máy móc sau thời gian chờ. Không có khóa idempotent hoặc xác nhận rõ ràng từ nhà cung cấp, việc lặp như vậy có thể thay đổi đơn hàng hai lần.

Nhược điểm của việc giới hạn thử lại là một phần cập nhật sẽ trở thành tác vụ thủ công. Thử lại vô hạn còn tệ hơn: chúng che giấu sự cố, tiêu tốn giới hạn và làm việc phân tích nhật ký phức tạp hơn.

Cách nhận trạng thái cuối cùng sau processing

Đừng để xảy ra chuyển ngược từ completed về processing do phản hồi polling muộn hoặc webhook cũ. Mỗi khi cập nhật, hãy so sánh thời gian sự kiện từ nhà cung cấp, số thứ tự phiên bản nếu có và trạng thái nội bộ hiện tại.

• new và pending có thể chuyển sang processing, canceled hoặc failed.
• processing có thể chuyển sang completed, partial, canceled hoặc failed.
• partial không nên tự động coi là completed.
• completed, canceled và failed thường được coi là cuối cùng và chặn việc quay lại tự động.
• Trạng thái không xác định hoặc chuyển đổi không hợp lệ cần được kiểm tra riêng.

Bảng chuyển đổi cứng nhắc cũng có nhược điểm: nhà cung cấp có thể thêm trạng thái mới hợp lệ. Vì vậy hãy lưu trạng thái gốc và không ghi đè nó bằng phân loại nội bộ.

Cách xử lý partial và phần còn lại của đơn hàng

Partial có nghĩa là chỉ một phần khối lượng ban đầu được xác nhận. Trong phản hồi API có thể có số lượng thực tế đã thực hiện, phần còn lại, lý do và dữ liệu về bồi hoàn. Hãy lưu các giá trị này riêng: không được thay thế khối lượng ban đầu của đơn hàng bằng số lượng đã thực hiện.

Ví dụ phản hồi cuối cùng có thể như sau:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Trước tiên hãy xác định API xác nhận chính xác điều gì: hoàn trả đã được thực hiện, hoàn trả chỉ mới được lên kế hoạch, phần còn lại đã bị hủy hay cần liên hệ bộ phận hỗ trợ. Nếu không có trường về hoàn trả, đừng coi phần còn lại đã được bồi hoàn tự động.

Đừng khởi động lại phần chưa thực hiện mà không có quyết định riêng. Nhà cung cấp có thể vẫn đang hoàn tất tính toán, thống kê nền tảng có thể cập nhật chậm, và yêu cầu mới có thể tạo quảng bá trùng lặp. Nhược điểm của việc chờ xác nhận là phần còn lại sẽ không được đóng ngay lập tức, nhưng sẽ không phát sinh đơn hàng thừa.

Webhook không thay thế kiểm tra kiểm soát

Webhook cho phép cập nhật thẻ đơn hàng ngay sau sự kiện mà không cần chờ polling tiếp theo. Trong trình xử lý, hãy tìm đơn hàng theo ID bên ngoài, kiểm tra chữ ký hoặc bí mật, lưu ID sự kiện và chỉ áp dụng chuyển đổi sau khi kiểm tra tính hợp lệ.

Việc gửi lại webhook phải an toàn: cùng một sự kiện không được coi là thay đổi mới. Các sự kiện cũng có thể đến không theo thứ tự, vì vậy đừng chuyển đơn hàng cuối cùng quay lại chỉ dựa trên processing muộn.

Polling kiểm soát vẫn cần thiết ngay cả khi webhook ổn định. Nhược điểm của webhook là cấu hình phức tạp hơn: cần trình xử lý khả dụng, bảo vệ khỏi yêu cầu giả mạo, loại bỏ trùng lặp và nhật ký sự kiện.

Nên hiển thị gì cho khách hàng khi processing và bị treo

Trong giao diện không cần hiển thị toàn bộ JSON kỹ thuật. Với processing, trạng thái "đơn hàng đang xử lý" là đủ. Nếu API truyền tiến độ đáng tin cậy, hãy hiển thị khối lượng đã xác nhận riêng với khối lượng ban đầu và không trình bày nó như kết quả cuối cùng.

Với đơn hàng đã vượt thời hạn kiểm soát nội bộ, hãy dùng trạng thái dễ hiểu như "đang kiểm tra thực hiện". Đừng thông báo về hủy, hoàn trả hoặc hoàn thành đầy đủ cho đến khi được phản hồi của nhà cung cấp xác nhận.

Thông báo hữu ích khi nhận đơn hàng, hoàn thành cuối cùng, partial, hủy, lỗi và cần kiểm tra. Tin nhắn sau mỗi lần polling tạo nhiễu và không giúp khách hàng hiểu trạng thái thực của yêu cầu.

Những bản ghi nào cần có trong nhật ký xử lý

Lịch sử phản hồi giúp phân tích processing bị treo, webhook bị mất, tranh chấp về thực hiện một phần và sai lệch giữa giao diện với API. Với mỗi lần gọi, hãy lưu ID bên ngoài, nguồn cập nhật, thời gian yêu cầu và phản hồi, mã HTTP, trạng thái gốc, trạng thái chuẩn hóa, tiến độ, phần còn lại và nội dung lỗi kỹ thuật.

Đừng ghi khóa API, token, chữ ký và các bí mật khác vào nhật ký thông thường. Hãy giới hạn quyền truy cập vào phản hồi thô: chúng có thể chứa dữ liệu không nên xuất hiện trong giao diện hỗ trợ.

Trước khi chạy, hãy kiểm tra các kịch bản với processing lặp lại, không có tiến độ, thời gian chờ, 429, lỗi 5xx, JSON không hợp lệ, webhook muộn, webhook trùng lặp, partial, canceled và trạng thái không xác định. Chế độ thử nghiệm hữu ích cho cấu trúc tích hợp, nhưng nhược điểm là nó có thể không lặp lại hàng đợi và độ trễ thực tế của API vận hành.