پردازش وضعیت «در حال انجام» هنگام بررسی سفارش از طریق API

processing در پاسخ API به چه معناست

وضعیت processing، in_progress یا هر حالت معادل دیگر یعنی تأمین‌کننده سفارش را در دست اجرا گرفته اما نتیجه نهایی را ثبت نکرده است. برای خدمات تبلیغاتی این می‌تواند بررسی لینک، انتظار در صف، شروع اجرای وظیفه یا تحویل تدریجی حجم سفارش‌شده باشد.

Processing نه انجام موفق را تأیید می‌کند و نه به معنای خطاست. پس از آن سفارش می‌تواند به completed، partial، canceled یا failed برود. تا زمانی که تأمین‌کننده وضعیت میانی برمی‌گرداند، درخواست تکراری برای همان لینک و همان حجم ایجاد نکنید.

HTTP 200 با وضعیت processing یعنی پاسخ موفق API، نه تکمیل موفق سفارش. این رویدادها را باید جداگانه ذخیره و پردازش کنید.

چه داده‌هایی برای بررسی سفارش لازم است

برای polling به شناسه خارجی سفارش نیاز دارید که تأمین‌کننده هنگام ایجاد برگردانده است. آن را همراه با شناسه داخلی، حجم اولیه، پارامترهای سرویس، لینک، زمان ایجاد و پاسخ اولیه API ذخیره کنید. جستجوی سفارش بر اساس نام کانال، لینک یا حجم قابل اعتماد نیست: این مقادیر ممکن است در چند درخواست یکسان باشند.

اگر پس از ایجاد، تایم‌اوت دریافت شد، درخواست را به‌صورت خودکار دوباره ارسال نکنید. ممکن است تأمین‌کننده درخواست را پذیرفته باشد و پاسخ در مسیر از بین رفته باشد. ابتدا از متد جستجوی سفارش استفاده کنید، اگر در مستندات وجود دارد، یا مورد را برای بررسی ارسال کنید.

عیب ذخیره‌سازی فقط وضعیت فعلی این است که در صورت اختلاف نمی‌توان بازسازی کرد که سفارش چه زمانی به processing رفته، آیا پیشرفتی داشته و چه پاسخ‌هایی پیش‌تر آمده است.

نمونه درخواست وضعیت با curl

آدرس دقیق، روش احراز هویت و نام فیلدها را از مستندات تأمین‌کننده بگیرید. در ادامه یک الگو نشان داده شده است: مقادیر داخل علامت‌های کوچک‌تر و بزرگ‌تر را باید با داده‌های API مشخص جایگزین کنید.

درخواست GET برای یک سفارش

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

-H "Authorization: Bearer " \

-H "Accept: application/json"

نمونه پاسخ:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

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

}

فیلدهای completed_quantity و remains فقط به‌عنوان نمونه ساختار آورده شده‌اند. تأمین‌کننده ممکن است از progress، start_count، balance یا نام‌های دیگر استفاده کند. عیب رویکرد GET این است که بخشی از APIها بررسی وضعیت را فقط از طریق POST می‌پذیرند.

نمونه درخواست POST و بررسی دسته‌ای

درخواست POST وضعیت یک سفارش

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

-H "Authorization: Bearer " \

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

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

کلید API را در رشته URL قرار ندهید. آدرس‌های درخواست در لاگ‌های پروکسی، سیستم‌های تحلیلی، تاریخچه مرورگر و لاگ‌های فنی ثبت می‌شوند. عیب POST این است که بررسی دستی آن از طریق نوار آدرس دشوارتر است، اما این دلیلی برای انتقال رمز به URL نیست.

درخواست دسته‌ای سفارش‌های فعال

اگر API از بررسی دسته‌ای پشتیبانی می‌کند، چند شناسه را در یک درخواست بفرستید:

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

-H "Authorization: Bearer " \

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

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

پاسخ را بر اساس شناسه خارجی با سفارش داخلی تطبیق دهید، نه بر اساس موقعیت عنصر در آرایه. عیب بررسی دسته‌ای: تأمین‌کننده ممکن است همه سفارش‌ها را برنگرداند، اندازه فهرست را محدود کند یا خطا را فقط برای یک شناسه اعلام کند.

چگونه polling را برای processing زمان‌بندی کنیم

پس از اولین پاسخ processing، بررسی بعدی را در صف قرار دهید. فاصله را بر اساس مستندات API، محدودیت‌های نرخ و ماهیت سرویس انتخاب کنید. برای وظایفی که وضعیتشان سریع تغییر می‌کند، بررسی مکررتر در ابتدا مجاز است. برای تبلیغات تدریجی، درخواست‌های کوتاه و مداوم معمولاً اطلاعات جدیدی نمی‌دهند.

یک الگوی عملی این است که پس از پاسخ‌های یکسان processing، فاصله را افزایش دهید. اولین بررسی پس از تأخیر شروع انجام می‌شود، سپس فاصله تا حداکثر تعیین‌شده رشد می‌کند. اگر API پیشرفت یا زمان به‌روزرسانی جدید برمی‌گرداند، شمارش را می‌توان از همان تغییر آغاز کرد.

• پس از ایجاد سفارش، وضعیت را بلافاصله چندین بار پشت سر هم بررسی نکنید: ممکن است سرویس برای قرار گرفتن در صف به زمان نیاز داشته باشد.
• در صورت تکرار processing، فاصله بین درخواست‌ها را افزایش دهید، نه اینکه نرخ ثابتی نگه دارید.
• انحراف تصادفی کوچکی به زمان اجرای وظایف اضافه کنید تا سفارش‌ها هم‌زمان API را فراخوانی نکنند.
• اگر تأمین‌کننده Retry-After یا توصیه مشابهی ارائه می‌دهد، آن را در اولویت قرار دهید.
• برای سفارش‌های دارای وب‌هوک، polling کنترلی را حفظ کنید: ممکن است اعلان نرسد.

عیب polling کم‌تکرار این است که رابط کاربری ممکن است پس از تکمیل واقعی، وضعیت قدیمی را نشان دهد. عیب polling بیش از حد مکرر، خطر برخورد با محدودیت‌های API، دریافت 429 و ایجاد بار اضافی است.

چه زمان‌هایی را برای کنترل processing ذخیره کنیم

برای تشخیص اجرای عادی از معلق شدن، یک وضعیت فعلی کافی نیست. برای هر سفارش فعال، زمان ایجاد، اولین دریافت processing، آخرین پاسخ موفق API، آخرین تغییر وضعیت خارجی و آخرین تغییر پیشرفت را ذخیره کنید.

همچنین ذخیره حجم اولیه، حجم تأییدشده انجام‌شده، باقی‌مانده و وضعیت اصلی تأمین‌کننده مفید است. اگر API پیشرفت را برنمی‌گرداند، این دلیلی برای معلق دانستن سفارش نیست: بر زمان آخرین پاسخ و دوره پردازش مورد انتظار تکیه کنید، اگر در شرایط سرویس ذکر شده باشد.

حداکثر زمان انتظار را نمی‌توان برای همه سرویس‌ها با یک عدد تعیین کرد. از مهلتی استفاده کنید که تأمین‌کننده برای سرویس مشخص اعلام می‌کند، با حاشیه داخلی برای صف و به‌روزرسانی داده‌ها. اگر مهلتی ذکر نشده، قاعده‌ای جداگانه برای هر دسته سرویس تعیین کنید و آن را بر اساس تاریخچه پردازش واقعی بازبینی کنید.

اگر processing تغییر نمی‌کند چه کنیم

processing طولانی اثبات خطا نیست. ابتدا بررسی کنید آیا پاسخ‌های موفق API آمده‌اند، آیا completed_quantity یا remains تغییر کرده‌اند، آیا وب‌هوکی بوده و آیا قواعد سرویس تغییر کرده‌اند. نبود رشد قابل مشاهده می‌تواند به تأخیر آمار پلتفرم مربوط باشد یا به این که تأمین‌کننده پیشرفت را فقط در پایان به‌روزرسانی می‌کند.

وقتی مهلت انتظار داخلی گذشت، سفارش را به‌صورت خودکار لغو نکنید. یک بررسی خارج از نوبت وضعیت انجام دهید، در صورت وجود متد اختصاصی داده‌ها را درخواست کنید و تاریخچه اعلان‌ها را بررسی کنید. اگر تأمین‌کننده هنوز processing را تأیید می‌کند، سفارش را به وضعیت داخلی «نیاز به بررسی» ببرید، اما وضعیت خارجی را بدون جایگزینی حفظ کنید.

• زمان آخرین پاسخ تأییدشده و کل پاسخ API را ثبت کنید.
• بررسی کنید آیا پیشرفت از زمان polling قبلی تغییر کرده است.
• پس از رسیدن به آستانه داخلی، نرخ درخواست‌های خودکار را کاهش دهید.
• شناسه خارجی، لینک، پارامترهای سرویس، تاریخچه وضعیت‌ها و خطاهای فنی را به پشتیبانی ارسال کنید.
• تا پاسخ تأمین‌کننده یا وضعیت نهایی صریح، باقی‌مانده را دوباره اجرا نکنید.

عیب بررسی دستی این است که سفارش به توجه پشتیبانی نیاز دارد. اما لغو خودکار یا تکرار خطرناک‌تر است: ممکن است اجرا نزد تأمین‌کننده ادامه داشته باشد.

چگونه خطای درخواست را از وضعیت سفارش جدا کنیم

خطای شبکه، تایم‌اوت، HTTP 429 و پاسخ 5xx وضعیت خود سفارش را اعلام نمی‌کنند. آن‌ها فقط یعنی وضعیت معتبر جدیدی به دست نیامده است. در چنین شرایطی آخرین وضعیت تأییدشده را نگه دارید، خطای فنی را ثبت کنید و بررسی جدید را زمان‌بندی کنید.

در 429، اگر هدر ارسال شده، Retry-After را در نظر بگیرید. در خطاهای موقت شبکه و 5xx، فاصله بین تلاش‌ها را افزایش دهید. در خطای احراز هویت، امضا یا دسترسی، تلاش‌های مکرر انجام ندهید: باید کلید، مدت اعتبار توکن، محدودیت‌های IP و تنظیمات دسترسی را بررسی کنید.

اگر API کد HTTP 200 برگرداند اما JSON قابل تجزیه نباشد یا order_id و status در پاسخ نباشد، بدنه پاسخ را کامل ذخیره کنید و بررسی را نامعتبر علامت بزنید. نبود وضعیت را با completed، canceled یا processing جایگزین نکنید.

چه زمانی درخواست‌های خودکار تکراری را متوقف کنیم

Polling نباید بی‌پایان باشد. تعداد تلاش‌های فنی برای خطاهای موقت را محدود کنید و مهلت کلی ماندن سفارش در processing را جداگانه کنترل کنید. پس از اتمام سقف تلاش‌ها، وظیفه بررسی را به صف رسیدگی منتقل کنید، نه اینکه هر دقیقه بدون نتیجه درخواست جدید بسازید.

تکرار درخواست وضعیت معمولاً بی‌خطر است، اگر متد فقط داده‌ها را می‌خواند. متدهای ایجاد، لغو، شارژ، راه‌اندازی مجدد و بازگشت را نمی‌توان پس از تایم‌اوت به‌صورت مکانیکی تکرار کرد. بدون کلید idempotent یا تأیید صریح تأمین‌کننده، چنین تکراری می‌تواند سفارش را دو بار تغییر دهد.

عیب محدود کردن تلاش‌ها این است که بخشی از به‌روزرسانی‌ها به وظیفه دستی تبدیل می‌شود. تلاش‌های بی‌پایان بدتر است: خطا را پنهان می‌کنند، محدودیت‌ها را مصرف می‌کنند و بررسی لاگ‌ها را دشوار می‌سازند.

چگونه وضعیت نهایی را پس از processing بپذیریم

اجازه ندهید به دلیل پاسخ دیرهنگام polling یا وب‌هوک قدیمی، گذار معکوس از completed به processing رخ دهد. در هر به‌روزرسانی، زمان رویداد از تأمین‌کننده، شماره نسخه در صورت وجود و وضعیت داخلی فعلی را مقایسه کنید.

• new و pending می‌توانند به processing، canceled یا failed بروند.
• processing می‌تواند به completed، partial، canceled یا failed برود.
• partial را نباید به‌صورت خودکار completed در نظر گرفت.
• completed، canceled و failed معمولاً نهایی در نظر گرفته می‌شوند و بازگشت خودکار به عقب را مسدود می‌کنند.
• وضعیت ناشناخته یا گذار نامجاز نیاز به بررسی جداگانه دارد.

جدول سخت‌گیرانه گذارها هم عیبی دارد: تأمین‌کننده ممکن است وضعیت جدید معتبری اضافه کند. بنابراین وضعیت اصلی را ذخیره کنید و آن را با طبقه‌بندی داخلی بازنویسی نکنید.

چگونه partial و باقی‌مانده سفارش را پردازش کنیم

Partial یعنی فقط بخشی از حجم اولیه تأیید شده است. در پاسخ API ممکن است مقدار واقعاً انجام‌شده، باقی‌مانده، دلیل و داده‌های جبران باشد. این مقادیر را جداگانه ذخیره کنید: حجم اولیه سفارش را نمی‌توان با مقدار انجام‌شده جایگزین کرد.

نمونه پاسخ نهایی می‌تواند این‌گونه باشد:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

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

}

ابتدا مشخص کنید API دقیقاً چه چیزی را تأیید می‌کند: بازگشت قبلاً انجام شده، بازگشت فقط برنامه‌ریزی شده، باقی‌مانده لغو شده یا نیاز به تماس با پشتیبانی است. اگر فیلدی درباره بازگشت وجود ندارد، باقی‌مانده را به‌صورت خودکار جبران‌شده در نظر نگیرید.

بخش انجام‌نشده را بدون تصمیم جداگانه دوباره راه‌اندازی نکنید. ممکن است تأمین‌کننده هنوز در حال محاسبه باشد، آمار پلتفرم با تأخیر به‌روزرسانی شود و درخواست تکراری تبلیغات مضاعف ایجاد کند. عیب انتظار برای تأیید این است که باقی‌مانده فوراً بسته نمی‌شود، اما سفارش اضافی ایجاد نمی‌شود.

وب‌هوک‌ها جایگزین بررسی کنترلی نمی‌شوند

وب‌هوک امکان می‌دهد کارت سفارش بلافاصله پس از رویداد به‌روزرسانی شود، بدون انتظار برای polling بعدی. در پردازشگر، سفارش را بر اساس شناسه خارجی پیدا کنید، امضا یا رمز را بررسی کنید، شناسه رویداد را ذخیره کنید و گذار را فقط پس از بررسی مجاز بودن اعمال کنید.

تحویل مجدد وب‌هوک باید بی‌خطر باشد: یک رویداد یکسان را نباید تغییر جدید در نظر گرفت. رویدادها همچنین ممکن است خارج از ترتیب برسند، بنابراین سفارش نهایی را فقط بر اساس processing دیرهنگام به عقب برنگردانید.

polling کنترلی حتی با وب‌هوک‌های پایدار لازم است. عیب وب‌هوک‌ها پیکربندی پیچیده‌تر است: نیاز به پردازشگر در دسترس، محافظت در برابر درخواست‌های جعلی، حذف تکراری و لاگ رویدادها.

در processing و معلق شدن چه چیزی به مشتری نشان دهیم

در رابط کاربری نیازی به نمایش کل JSON فنی نیست. برای processing، وضعیت «سفارش در حال اجرا» کافی است. اگر API پیشرفت معتبری ارسال کرده، حجم تأییدشده را جدا از حجم اولیه نشان دهید و آن را نتیجه نهایی جلوه ندهید.

برای سفارشی که از مهلت کنترل داخلی گذشته، از وضعیت قابل فهمی مانند «در حال بررسی اجرا» استفاده کنید. تا زمانی که پاسخ تأمین‌کننده تأیید نکرده، درباره لغو، بازگشت یا تکمیل کامل اطلاع ندهید.

اعلان‌ها هنگام پذیرش سفارش، تکمیل نهایی، partial، لغو، خطا و نیاز به بررسی مفید هستند. پیام پس از هر polling سر و صدا ایجاد می‌کند و به مشتری کمک نمی‌کند وضعیت واقعی درخواست را بفهمد.

چه رکوردهایی در لاگ پردازش لازم است

تاریخچه پاسخ‌ها به بررسی processing معلق، وب‌هوک گم‌شده، اختلاف بر سر اجرای جزئی و ناهماهنگی بین رابط کاربری و API کمک می‌کند. برای هر فراخوانی، شناسه خارجی، منبع به‌روزرسانی، زمان درخواست و پاسخ، کد HTTP، وضعیت اصلی، وضعیت نرمال‌شده، پیشرفت، باقی‌مانده و متن خطای فنی را ذخیره کنید.

کلیدهای API، توکن‌ها، امضاها و سایر رمزها را در لاگ‌های عادی ثبت نکنید. دسترسی به پاسخ‌های خام را محدود کنید: ممکن است حاوی داده‌هایی باشند که نباید در رابط پشتیبانی باشد.

پیش از راه‌اندازی، سناریوهای processing تکرارشونده، نبود پیشرفت، تایم‌اوت، 429، خطای 5xx، JSON نامعتبر، وب‌هوک دیرهنگام، وب‌هوک تکراری، partial، canceled و وضعیت ناشناخته را بررسی کنید. حالت آزمایشی برای ساختار یکپارچه‌سازی مفید است، اما عیب آن این است که ممکن است صف‌ها و تأخیرهای واقعی API عملیاتی را بازتولید نکند.