رفع خطاهای REST API ووکامرس؛ از 401 و 403 تا قطع اتصال
وقتی نرم‌افزار انبار یا حسابداری دیگر سفارش‌ها را از ووکامرس دریافت نمی‌کند، ساختن کلید تازه همیشه پاسخ مسئله نیست. ابتدا باید مشخص شود درخواست به چه نشانی رسیده، چه پاسخی گرفته و در کدام مرحله متوقف شده است. این راهنما برای اتصال سرور به سرور با REST API است و مسیر تشخیص را با یک درخواست فقط‌خواندنی شروع می‌کند.
قبل از تغییر، شواهد یک درخواست ناموفق را ثبت کنید
زمان و منطقه زمانی، روش درخواست مثل GET، دامنه و مسیر بدون اطلاعات محرمانه، کد HTTP، نوع محتوای پاسخ و متن خطای پاک‌سازی‌شده را نگه دارید. نسخه ووکامرس و آخرین تغییر در دامنه، میزبان، افزونه امنیتی یا کاربر اتصال هم به تشخیص کمک می‌کند. Consumer Secret، هدر Authorization و اطلاعات شخصی سفارش نباید در گزارش عمومی یا پیام پشتیبانی قرار بگیرند.
اگر اتصال با اعلان فروشگاه شروع می‌شود، راهنمای عیب‌یابی وبهوک را هم بررسی کنید. کلید REST API و secret وبهوک کاربردهای متفاوت دارند؛ درست‌بودن یکی سلامت دیگری را ثابت نمی‌کند.
۱. نشانی نهایی و نوع API را مشخص کنید
در مستندات REST API ووکامرس مسیرهای مدیریتی فعلی زیر /wp-json/wc/v3/ معرفی می‌شوند؛ برای نمونه، فهرست سفارش‌ها از مسیر /wp-json/wc/v3/orders قابل درخواست است. دامنه نهایی HTTPS، پیشوند نصب وردپرس و مسیر مورد استفاده اتصال را با هم تطبیق دهید. این مسیر با Store API مربوط به تجربه خرید یکسان نیست.
بازکردن صفحه اصلی سایت یا ورود موفق به پیشخوان، سلامت این مسیر را نشان نمی‌دهد. اگر درخواست به صفحه ورود، دامنه دیگری یا HTML یک چالش امنیتی هدایت شود، ابتدا همان مسیر را اصلاح کنید. انتقال خودکار اطلاعات احراز هویت به دامنه دیگر راه‌حل مناسبی نیست؛ نشانی درست باید در تنظیمات اتصال ثبت شود.
برای مسیر استاندارد API، راهنمای مدیریت REST API تنظیم پیوندهای یکتا روی گزینه‌ای غیر از Plain را لازم می‌داند. اگر مسیر 404 می‌دهد، این تنظیم و قواعد بازنویسی میزبان را هم بررسی کنید.
۲. یک آزمون فقط‌خواندنی و محدود اجرا کنید
از همان سرورِ اتصال، یک GET به مسیر سفارش‌ها با per_page=1 و کلید مجاز اجرا کنید. این آزمون را با ابزار سروری یا کلاینت API انجام دهید؛ کلید محرمانه را داخل جاوااسکریپت عمومی سایت قرار ندهید. پاسخ سفارش ممکن است داده شخصی داشته باشد؛ خروجی را در محیط خصوصی بررسی و برای اشتراک‌گذاری پاک‌سازی کنید.
پاسخ موفق نشان می‌دهد همان درخواست، با همان کاربر و مجوز، قابل اجراست. موفقیت خواندن سفارش اثبات نمی‌کند اتصال اجازه تغییر قیمت یا ساخت سند دارد. پاسخ خالی هم باید با داده و فیلترهای آزمون تطبیق داده شود؛ در محیط آزمایشی یک سفارش شناخته‌شده انتخاب کنید.
۳. کد پاسخ را همراه با بدنه خطا بخوانید
| مشاهده | فرضیه قابل بررسی | گام بعدی |
|---|---|---|
| 401 همراه خطای JSON | مشکل احراز هویت یا مجوز مرتبط با کلید و کاربر | کلید، کاربر متصل، سطح دسترسی و رسیدن هدر را بررسی کنید |
| 403 یا صفحه HTML منع دسترسی | محدودیت دسترسی در برنامه، افزونه امنیتی یا لایه جلوی سرور | بدنه پاسخ و لاگ همان زمان را برای یافتن تولیدکننده خطا تطبیق دهید |
| 404 یا rest_no_route | دامنه، مسیر، روش درخواست یا ثبت مسیر درست نیست | نشانی و روش را با مستندات همان endpoint مقایسه کنید |
| 429 | محدودیت نرخ در یکی از لایه‌های مسیر | سیاست همان سرویس و Retry-After در صورت وجود را بررسی کنید |
| 5xx یا timeout | خطای برنامه، پراکسی یا تأخیر پردازش | لاگ سرور و زمان پاسخ را بررسی کنید؛ قبل از تکرار نوشتن، نتیجه قبلی را بیابید |
این جدول مسیر تشخیص است، نه حکم قطعی درباره علت. برای مثال همه پاسخ‌های 403 از فایروال نیستند و هر timeout به معنی انجام‌نشدن عملیات نیست. در هر مرحله فقط یک متغیر را تغییر دهید تا نتیجه قابل مقایسه بماند.
۴. کلید، کاربر و هدر Authorization را جدا کنترل کنید
طبق راهنمای رسمی احراز هویت، در HTTPS می‌توان Consumer Key را به عنوان نام کاربری و Consumer Secret را به عنوان رمز در HTTP Basic Auth فرستاد. کلید باید متعلق به همان فروشگاه باشد. کلید لغوشده یا رشته‌ای که ناقص کپی شده است قابل استفاده نخواهد بود.
در مدیریت کلیدها، کاربر متصل و دسترسی Read، Write یا Read/Write را متناسب با عملیات بازبینی کنید. مجوز کلید جایگزین قابلیت‌های کاربر نمی‌شود. اگر فقط خواندن لازم است، برای رفع خطا دسترسی نوشتن اضافه نکنید. تغییر نقش یا حذف کاربر اتصال می‌تواند در بررسی دسترسی اثرگذار باشد.
اگر ابزار محلی کار می‌کند اما سرور اتصال خطا می‌گیرد، درخواست‌های دو محیط را از نظر نشانی نهایی، روش احراز هویت و تنظیمات پراکسی مقایسه کنید. وجود هدر Authorization را در مسیر بررسی کنید، بدون ثبت مقدار آن. عبور هدر از وب‌سرور یا پراکسی باید با تنظیمات همان زیرساخت کنترل شود؛ کپی‌کردن یک دستور عمومی برای همه میزبان‌ها قابل اتکا نیست.
کلید را برای دورزدن مشکل در URL عمومی نگذارید؛ نشانی‌ها ممکن است در تاریخچه و لاگ‌ها ذخیره شوند. اگر کلید افشا شده، آن را لغو و کلید جایگزین را در محل خصوصی اتصال ثبت کنید. خاموش‌کردن دائمی کنترل امنیتی هم جای اصلاح قاعده مشخص مسیر API را نمی‌گیرد.
۵. پس از رفع خطا، اتصال را با کنترل تکرار برگردانید
فرض کنید یک اتصال حسابداری فرضی دو ساعت خطای دسترسی داشته است. رفع 401 فقط درخواست‌های بعدی را ممکن می‌کند؛ هنوز باید سفارش‌های بازه قطع‌شده را پیدا کنید. بازه زمانی و وضعیت‌های لازم، صفحه‌بندی پاسخ و شناسه آخرین رکورد پردازش‌شده را مطابق قرارداد اتصال بررسی کنید. دریافت تنها صفحه اول فهرست، بازیابی کامل نیست.
برای هر سفارش، شناسه ثبت مقصد را تطبیق دهید. اگر درخواست نوشتن timeout شده است، پیش از تکرار بررسی کنید آیا اثر قبلی ایجاد شده یا نه. پیشنهاد طراحی این است که اتصال نگاشت شناسه فروشگاه و مقصد و کنترل یکتایی داشته باشد؛ REST API به‌تنهایی تضمین عمومیِ جلوگیری از عملیات تجاری تکراری برای هر سامانه مقصد نمی‌دهد. جزئیات مسیر سند در راهنمای اتصال ووکامرس به حسابداری آمده است.
چه زمانی اصلاح اتصال به توسعه نیاز دارد؟
اگر مشکل به نشانی نادرست، کلید لغوشده یا یک قاعده روشن پراکسی محدود است، اصلاح تنظیمات و آزمون دوباره ممکن است کافی باشد. وقتی اتصال خطاها را ثبت نمی‌کند، صفحه‌بندی ندارد، بعد از قطعی رکوردها را جا می‌اندازد یا با تکرار درخواست سند دوم می‌سازد، منطق خود اتصال هم به بازبینی نیاز دارد.
برای درخواست بررسی، زمان آخرین موفقیت، یک نمونه خطای پاک‌سازی‌شده، مسیرهای مورد استفاده، عملیات مورد انتظار و روش فعلی بازیابی را آماده کنید. در خدمت اتوماسیون و اتصال فروشگاه می‌توان دامنه اصلاح و معیار تحویل را پس از بررسی همین شواهد مشخص کرد.
چک‌لیست پذیرش اصلاح
- درخواست فقط‌خواندنی از سرور واقعی اتصال با مجوز حداقلی پاسخ درست می‌گیرد.
- عملیات نوشتنِ مورد نیاز در محیط آزمایشی، روی داده مشخص و با کنترل نتیجه آزموده شده است.
- توقف موقت و شروع دوباره باعث جاافتادن رکورد یا ثبت اثر تکراری نمی‌شود.
- لاگ زمان، مسیر، کد خطا و شناسه پیگیری را بدون کلید و اطلاعات شخصی غیرضروری نگه می‌دارد.
- روش تعویض و لغو کلید و مسئول نگهداری اتصال مستند شده است.
این معیارها پیشنهاد آزمون‌اند و مثال حسابداری بالا فرضی است. برای انتخاب سازوکار اتصال از ابتدا، مقایسه وبهوک و API دوره‌ای را بخوانید.