راهنمای یکپارچه‌سازی وب‌سرویس همکاران

مستندات تعاملی API برای ثبت‌نام خودکار کلاینت‌ها، مدیریت اتصالات و ارسال کدهای تایید OTP.

۱. امنیت و نحوه احراز هویت همکار

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

🔑 اطلاعات هدرها:

X-Partner-API-Key: partner_key_Qwwjj793mmcD
Partner ID (شناسه همکار): designcore

۲. ثبت‌نام کلاینت/فروشگاه جدید

برای ایجاد فروشگاه جدید تحت زیرمجموعه خود از این متد استفاده کنید. در صورت فعال بودن هوش مصنوعی، سرویس هوش مصنوعی (RAG) به طور خودکار در Apigo ایجاد و متصل می‌گردد.

POST /api/otp/partner/clients
پارامترهای ورودی (JSON Body):
نام نوع الزامی
client_id string بله
channel string خیر
telegram_bot_token string خیر
bale_bot_token string خیر
telegram_enabled boolean خیر
relogin_link string خیر
ai_enabled boolean خیر

شناسه کلاینت باید یکتا و شامل حروف، اعداد، آندرلاین یا خط تیره باشد.

curl -X POST http://91.107.184.23/api/otp/partner/clients \ -H "Content-Type: application/json" \ -H "X-Partner-API-Key: partner_key_Qwwjj793mmcD" \ -d '{ "client_id": "designcoreshopwp", "channel": "telegram", "telegram_bot_token": "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ", "telegram_enabled": false, "relogin_link": "https://my-partner.com/relogin", "ai_enabled": true }'

۳. دریافت وضعیت اتصال واتساپ و QR کد

برای دریافت اتصال زنده واتساپ کلاینت و بازیابی QR کد تصویر جهت اسکن کاربر استفاده می‌شود. در صورتی که کلاینت متصل نباشد، QR جدید بلافاصله تولید شده و به صورت Base64 فرستاده می‌شود.

GET /api/otp/clients/{client_id}/status
پارامترهای مسیر (Path Params):
client_id شناسه یکتای کلاینت
هدرها (Headers):
X-Client-API-Key کلید کلاینت یا کلید همکار
curl http://91.107.184.23/api/otp/clients/designcoreshopwp/status \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۴. قطع اتصال واتساپ کلاینت

خروج کامل از حساب کاربری واتساپ کلاینت و حذف کامل نشست‌ها و کش فایل‌های Baileys روی دیسک.

POST /api/otp/clients/{client_id}/disconnect

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

curl -X POST http://91.107.184.23/api/otp/clients/designcoreshopwp/disconnect \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۵. درخواست کد OTP (مستقیم)

ایجاد کد ۵ رقمی احراز هویت برای مشتری کلاینت و برگرداندن پاسخ به همراه لینک سریع باز کردن واتساپ.

POST /api/otp/request
پارامترهای ورودی (JSON Body):
client_id شناسه کلاینت هدف
phone شماره همراه خریدار (مثلا 989012345678)
curl -X POST http://91.107.184.23/api/otp/request \ -H "Content-Type: application/json" \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD" \ -d '{"client_id": "designcoreshopwp", "phone": "+989012345678"}'

۶. تایید نهایی کد OTP

بررسی مطابقت کد وارد شده توسط کاربر با مقدار ثبت شده در ردیس و صادر کردن توکن دسترسی JWT در صورت موفقیت.

POST /api/otp/verify
پارامترهای ورودی (JSON Body):
client_id شناسه کلاینت هدف
phone شماره همراه خریدار
code کد ۵ رقمی تایید
curl -X POST http://91.107.184.23/api/otp/verify \ -H "Content-Type: application/json" \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD" \ -d '{"client_id": "designcoreshopwp", "phone": "+989012345678", "code": "43930"}'

۷. شروع ورود بدون پسورد (Initiate Login)

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

POST /api/otp/login/initiate

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

curl -X POST http://91.107.184.23/api/otp/login/initiate \ -H "Content-Type: application/json" \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD" \ -d '{"client_id": "designcoreshopwp"}'

۸. بررسی وضعیت نشست (Poll Status)

چک کردن مداوم وضعیت کد نشست صادر شده جهت متوجه شدن تایید نهایی کاربر در گوشی همراهش.

GET /api/otp/login/status/{client_id}/{session_code}

در صورت تایید نهایی از سمت گوشی خریدار، پاسخ این متد وضعیت `verified` به همراه شماره موبایل خریدار و توکن دسترسی خواهد بود.

curl http://91.107.184.23/api/otp/login/status/designcoreshopwp/41258 \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۹. دریافت و به‌روزرسانی تنظیمات پیام‌رسان کلاینت

برای خواندن یا ویرایش تنظیمات پیام‌رسان‌ها (کانال فعال، توکن‌های ربات تلگرام/بله)، تنظیم هشدارهای تلگرام و مدیریت ارتباط کلاینت‌ها استفاده می‌شود.

GET /api/otp/clients/{client_id}/settings

جهت ویرایش کافی است از متد `POST` به همین آدرس استفاده کرده و بدنه جدید (تمام فیلدهای تنظیمات) را ارسال کنید.

curl http://91.107.184.23/api/otp/clients/designcoreshopwp/settings \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۱۰. دریافت کد جفت‌سازی ربات تلگرام

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

POST /api/otp/clients/{client_id}/telegram/pair-code

کد تولید شده دارای انقضای ۱۰ دقیقه‌ای است.

curl -X POST http://91.107.184.23/api/otp/clients/designcoreshopwp/telegram/pair-code \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۱۱. قطع اتصال ربات تلگرام کلاینت

قطع ارتباط و عدم ارسال هشدارهای خروج و لغو دریافت پیام‌ها بر روی چت تلگرام کلاینت.

POST /api/otp/clients/{client_id}/telegram/disconnect

این متد متغیرهای تلگرام کلاینت را در فایل تنظیماتش صفر می‌کند.

curl -X POST http://91.107.184.23/api/otp/clients/designcoreshopwp/telegram/disconnect \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۱۲. ارسال پیام متنی دلخواه (خارج از OTP)

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

POST /api/otp/partner/send-message
پارامترهای ورودی (JSON Body):
client_id شناسه کلاینت هدف
phone شماره مقصد (بدون +)
message متن پیام ارسالی سفارشی
channel (اختیاری) کانال مقصد ارسال: `whatsapp` یا `telegram` یا `bale` (در صورت عدم ارسال، سیستم به طور خودکار به ربات فعال کاربر متصل و پیام را هوشمند مسیریابی می‌کند).
curl -X POST http://91.107.184.23/api/otp/partner/send-message \ -H "Content-Type: application/json" \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD" \ -d '{ "client_id": "designcoreshopwp", "phone": "989012345678", "message": "سلام! سفارش شما با موفقیت ثبت شد و کد رهگیری پست به زودی ارسال می‌شود.", "channel": "telegram" }'

۱۳. دریافت لیست درخواست‌های پشتیبانی فعال

بازیابی لیست شماره تلفن‌های مشتریانی که درخواست اتصال به پشتیبانی زنده داشته‌اند و هوش مصنوعی برای آن‌ها خاموش شده است.

GET /api/otp/clients/{client_id}/support-requests

این اندپوینت آرایه‌ای از مشتریان در حال انتظار به همراه زمان باقی‌مانده انقضای درخواست (TTL به ثانیه) را برمی‌گرداند.

curl http://91.107.184.23/api/otp/clients/designcoreshopwp/support-requests \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۱۴. خاتمه پشتیبانی و فعال‌سازی مجدد هوش مصنوعی

اعلام اتمام فرآیند چت انسانی و خارج کردن شماره کاربر از لیست پشتیبانی برای فعال‌سازی مجدد ربات هوش مصنوعی.

POST /api/otp/clients/{client_id}/support-requests/{phone}/resolve

این اندپوینت کلید وضعیت پشتیبانی کاربر را از ردیس حذف کرده و درخواست unpin به واتساپ می‌فرستد.

curl -X POST http://91.107.184.23/api/otp/clients/designcoreshopwp/support-requests/989012345678/resolve \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD"

۱۵. تنظیم متن پیام‌های هوش مصنوعی

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

PATCH /api/otp/clients/{client_id}/ai-message-config

فقط فیلدهایی که می‌خواهید تغییر کنند را ارسال کنید. هر دو فیلد اختیاری هستند.

فیلدنوعتوضیح
ai_suffix_text string متنی که در انتهای هر پاسخ هوش مصنوعی اضافه می‌شود. اگر خالی باشد، متن پیش‌فرض سیستم استفاده می‌شود.
ai_support_keyword string کلمه‌ای که مشتری باید بفرستد تا درخواست پشتیبانی انسانی ثبت شود (پیش‌فرض: پشتیبانی).
curl -X PATCH http://91.107.184.23/api/otp/clients/designcoreshopwp/ai-message-config \ -H "X-Client-API-Key: partner_key_Qwwjj793mmcD" \ -H "Content-Type: application/json" \ -d '{ "ai_suffix_text": "\ud83e\udd16 \u0627\u06af\u0631 \u0633\u0648\u0627\u0644\u06cc \u062f\u0627\u0631\u06cc\u062f \u06a9\u0644\u0645\u0647 *\u06a9\u0645\u06a9* \u0631\u0627 \u0628\u0641\u0631\u0633\u062a\u06cc\u062f.", "ai_support_keyword": "\u06a9\u0645\u06a9" }'
{ "ok": true, "message": "\u062a\u0646\u0638\u06cc\u0645\u0627\u062a \u067e\u06cc\u0627\u0645 \u0647\u0648\u0634 \u0645\u0635\u0646\u0648\u0639\u06cc \u0628\u0627 \u0645\u0648\u0641\u0642\u06cc\u062a \u0628\u0647\u200c\u0631\u0648\u0632 \u0634\u062f.", "updated": { "ai_suffix_text": "\ud83e\udd16 \u0627\u06af\u0631 \u0633\u0648\u0627\u0644\u06cc \u062f\u0627\u0631\u06cc\u062f \u06a9\u0644\u0645\u0647 *\u06a9\u0645\u06a9* \u0631\u0627 \u0628\u0641\u0631\u0633\u062a\u06cc\u062f.", "ai_support_keyword": "\u06a9\u0645\u06a9" } }