اتصال‌ها و API
در پنل:حساباتصال‌ها و API
پنل را به سایت وردپرسی یا هر نرم‌افزار دیگرتان وصل کنید: با کلید API محصول، موجودی، سفارش و نوبت را همگام کنید و با وبهوک خروجی، هر سفارش، مخاطب، رسید یا نوبت تازه همان لحظه به سایتتان خبر داده شود.
- کلید API برای سایت یا نرم‌افزار شما.
- آدرس وبهوک برای خبر گرفتن از سفارشها.
قدم‌به‌قدم
کلید API بسازید
در کارت «کلید API» روی «ساخت کلید API» بزنید. کلید فقط همین یک بار نشان داده میشود؛ همان لحظه کپی‌اش کنید و جای امنی، مثل تنظیمات سایتتان، نگه دارید. کلید برای وقتی است که سایت شما از دایرکت‌فا چیزی بخواند یا تغییر دهد، مثل موجودی و قیمت؛ برای فقط خبر گرفتن با وبهوک لازم نیست. زیر کارت «آخرین استفاده» می‌گوید کلید آخرین بار کی به کار رفته است.
آدرس وبهوک را اضافه کنید
در کارت «وبهوک خروجی (خبررسانی لحظه‌ای)» روی «افزودن آدرس وبهوک» بزنید. در «آدرس دریافت‌کننده (https)» آدرسی از سایت خودتان بنویسید که از اینترنت باز میشود؛ آدرسی که به شبکهٔ داخلی اشاره کند پذیرفته نمی‌شود. رویدادهایی را که می‌خواهید تیک بزنید و «ذخیره آدرس» را بزنید. هر پیج تا ۳ آدرس دارد و هر آدرس رویدادها و «کلید امضا» خودش را.
مثالآدرس دریافت‌کننده برای سایت وردپرسی، بعد از گذاشتن کد آماده: https://example.com/wp-json/directfa/v1/hook
رویدادها را انتخاب کنید
ده رویداد دارید: «مخاطب جدید»، «شمارهٔ جدید مخاطب»، «سفارش جدید»، «به‌روزرسانی سفارش»، «رسید پرداخت جدید»، «نوبت جدید»، «نوبت تغییر کرد»، «نوبت لغو شد»، «پست منتشر شد» و «انتشار پست ناموفق بود». «سفارش جدید» برای سفارش‌های گفتگو، دستیار، فروشگاه اینترنتی و بیعانهٔ نوبت می‌رود و «به‌روزرسانی سفارش» برای تغییر وضعیت، پرداخت یا کد رهگیری. تیک‌ها را هر وقت خواستید روی خود آدرس عوض کنید؛ دست‌کم یکی باید بماند.
مثالبرای اینکه هر سفارش دایرکت در حسابداری سایت ثبت شود، فقط «سفارش جدید» و «به‌روزرسانی سفارش» را تیک بزنید.
امضا را چک کنید
کنار هر آدرس «کلید امضا» آمده است. با دکمهٔ چشم کنارش آن را ببینید و با «کپی» بردارید. سایت شما امضای هر پیام را با این کلید چک می‌کند تا مطمئن شود پیام واقعاً از دایرکت‌فاست و کسی آن را جعل نکرده. این کلید را هم مثل رمز نگه دارید.
ارسال آزمایشی بزنید
«ارسال تست» را بزنید؛ یک پیام آزمایشی به آدرس می‌رود و نتیجه همان‌جا نوشته میشود: «رسید» همراه کد پاسخ سایت، یا «نرسید» همراه دلیلش. سایت شما باید با کد ۲۰۰ تا ۲۹۹ جواب بدهد تا ارسال «رسید» حساب شود. اگر نرسید، آدرس، باز بودن سایت و کد گذاشته‌شده را بررسی کنید و دوباره امتحان کنید.
کد آماده را بردارید
«راهنمای اتصال + نمونه کد وردپرس» را باز کنید. آنجا به ترتیب این‌ها را دارید: کد دریافت وبهوک برای functions.php وردپرس که امضا را چک می‌کند، کد انتقال کاتالوگ ووکامرس برای سایتی که «اتصال به سایت» رویش کار نکرد، دستورهای همگام‌سازی موجودی، سفارشها و ارسال پیام، ردیابی فروش سایت، همگام‌سازی نوبت‌دهی و زمان‌بندی پست از سیستم خودتان. کد را کپی کنید و آدرس و کلید خودتان را جایش بگذارید.
فروش سایت را به سناریو وصل کنید
اگر در گفتگو مشتری را با دکمهٔ لینک‌دار به سایتتان می‌فرستید، در «سازنده گفتگو» روی آن دکمه «شمارش کلیک و ردیابی فروش سایت» را روشن کنید. خریدار با یک نشانهٔ کلیک به سایت می‌رسد و سایت شما بعد از پرداخت، با کد آمادهٔ بخش پنجم راهنما، خرید را با همان نشانه به دایرکت‌فا خبر میدهد. این خرید در «سفارشها» با نشان «سایت» می‌آید و به پست، قانون و سناریویی که خریدار را فرستاد نسبت داده میشود؛ پرداخت و ارسالش همان‌جا در سایت است.
تحویل‌ها را پیگیری کنید
در «گزارش تحویل‌ها (۳۰ مورد آخر)» وضعیت هر ارسال را با «رسید»، «در صف» یا «ناموفق» ببینید. روی هر ردیف بزنید تا «بدنهٔ ارسال‌شده» و «پاسخ سایت شما» را ببینید و ارسال ناموفق را با «تلاش دوباره» دوباره بفرستید. با «به‌روزرسانی گزارش» فهرست تازه میشود. اگر چند تحویل پشت سر هم شکست بخورد، کنار آدرس «خودکار غیرفعال شد» می‌آید؛ مشکل سایت را رفع کنید و تیک «فعال» را دوباره بزنید.
مثال کامل
مثال: هر سفارش دایرکت در سایت وردپرسی فروشگاه ثبت شود
یک فروشگاه لوازم دیجیتال سایت ووکامرس دارد و می‌خواهد سفارش‌های دایرکت هم در سایت دیده شوند و موجودی دو طرف یکی بماند. ۱) در «راهنمای اتصال + نمونه کد وردپرس»، کد بخش اول را در functions.php پوستهٔ فرزند سایت می‌گذارد. ۲) در «افزودن آدرس وبهوک»، آدرسی را که راهنما بعد از ذخیرهٔ کد نشان میدهد می‌نویسد، «سفارش جدید» و «به‌روزرسانی سفارش» را تیک می‌زند و «ذخیره آدرس» را می‌زند. ۳) «کلید امضا» را کپی و در کد جای گذاشته‌شده می‌گذارد. ۴) «ارسال تست» را می‌زند و «رسید (کد ۲۰۰)» را می‌بیند. ۵) «ساخت کلید API» را می‌زند و کلید را در بخش همگام‌سازی موجودی کد می‌گذارد تا هر فروش سایت از موجودی دایرکت‌فا هم کم شود. از این به بعد، وقتی مشتری در دایرکت هدفون سفارش میدهد، همان لحظه پیام امضاشده‌ای به سایت می‌رسد و کد، سفارش را ثبت یا به مدیر ایمیل می‌کند. اگر سایت چند ساعتی از دسترس خارج شود، دایرکت‌فا پیام را تا ۵ بار با فاصله دوباره می‌فرستد.
در این بخش چه کارهایی میشود کرد
- کلید API برای خواندن و تغییر محصول، موجودی و قیمت (روی تنوع‌ها هم)، خواندن سفارشها و تغییر وضعیتشان، خواندن مخاطب‌ها، فرستادن پیام دایرکت در پنجرهٔ ۲۴ ساعته و ثبت، جابه‌جایی و لغو نوبت.
- تا ۳ آدرس وبهوک برای هر پیج، هر کدام با رویدادها، کلید امضا، تیک «فعال» و «ارسال تست» خودش.
- ارسال دوبارهٔ خودکار: اگر سایت شما جواب ندهد، هر رویداد تا ۵ بار فرستاده میشود؛ بعد از ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه و ۲ ساعت.
- ثبت فروش سایت روی همان پست، قانون و سناریویی که خریدار را فرستاد، با «شمارش کلیک و ردیابی فروش سایت» روی دکمهٔ لینک‌دار سازندهٔ گفتگو.
- همگام‌سازی دوطرفهٔ نوبت‌دهی با سایت نوبت‌دهی خودتان، بدون نوبت تکراری.
- کد انتقال کاتالوگ ووکامرس با تنوع‌ها و عکس‌ها و بدون ساختن محصول تکراری، برای سایتی که «اتصال به سایت» رویش کار نمی‌کند.
- زمان‌بندی پست، ریلز و استوری از سیستم خودتان با همان بررسی‌های فرم انتشار پست، وقتی انتشار زمان‌بندی‌شده در پلن شما باشد.
- مستند کامل برای برنامه‌نویس‌ها در نشانی /api/v1/openapi.json، قابل باز کردن در Postman یا Swagger.
نکته‌ها و اشکال‌های رایج (۶)
- کلید API مثل رمز عبور است؛ اگر لو رفت، «ساخت کلید جدید (کلید قبلی باطل میشود)» یا «باطل کردن کلید» را بزنید. باطل کردن کلید و حذف آدرس حتی بعد از پایان پلن هم ممکن است.
- اگر کنار آدرس «خودکار غیرفعال شد» آمد، ارسال به آن متوقف شده؛ اول با «ارسال تست» مطمئن شوید سایت جواب میدهد و بعد تیک «فعال» را بزنید.
- سقف مصرف API ۱۲۰ درخواست در دقیقه و برای پیام‌ها ۲۰ پیام در دقیقه است. پیام فقط به کسی می‌رود که در ۲۴ ساعت گذشته به پیج پیام داده باشد.
- برای آوردن محصولات ووکامرس، ساده‌ترین راه «اتصال به سایت» در «محصولات و قیمت‌ها» است. در کد انتقال، واحد پول سایت (تومان، ریال، هزار تومان یا هزار ریال) خودکار خوانده و به تومان تبدیل میشود.
- خرید سایتی که با API ثبت می‌کنید شمارهٔ سفارش سایت را دارد؛ اگر دوباره با همان شماره بفرستید، سفارش تکراری ساخته نمی‌شود و برای این خریدها وب‌هوکی به سایت برنمی‌گردد.
- کد وردپرس را ترجیحاً در functions.php پوستهٔ فرزند بگذارید تا با به‌روزرسانی پوسته پاک نشود.
پرسش‌های این بخش
برای وصل کردن سایت وردپرسی باید برنامه‌نویس باشم؟
نه لزوماً. در «راهنمای اتصال + نمونه کد وردپرس» کد آماده هست؛ آن را در functions.php پوستهٔ سایت بگذارید و کلید امضا یا کلید API خودتان را جایش بنویسید. برای کارهای پیچیده‌تر، مثل ثبت خودکار سفارش در ووکامرس، کمک یک برنامه‌نویس بهتر است.
سایتم وردپرسی نیست؛ باز هم میشود وصل کرد؟
بله. API و وبهوک به زبان یا سیستم خاصی وابسته نیستند و مستند کامل در نشانی /api/v1/openapi.json است. کد آمادهٔ داخل پنل فقط برای وردپرس و ووکامرس است.
اگر سایتم مدتی از دسترس خارج شود، رویدادها از دست می‌روند؟
هر رویداد تا ۵ بار با فاصله، تا حدود دو ساعت و نیم بعد، دوباره فرستاده میشود. اگر باز هم نرسید، آن را از «گزارش تحویل‌ها (۳۰ مورد آخر)» با «تلاش دوباره» دستی بفرستید.
برای گزارش مالی هم به API نیاز دارم؟
نه. در «سفارشها» بخش «حسابداری فروشگاه» فروش وصولشده را در هر بازه نشان میدهد و «خروجی CSV» میدهد.