ConnectWiz + API و webhook
یکپارچهسازی فعالهمان API که میفروشیم، همان API است که خودمان به کار میبریم
کل پلتفرم در یک قرارداد OpenAPI تعریف شده که پنل و اپلیکیشن موبایل خودمان از آن تولید میشوند — بدون نقطهٔ پایانی پنهان، بدون فاصله گرفتن مستندات از واقعیت. روی همین: کلیدهای Commerce API با دامنهٔ مشخص، تریگرهای webhook امنشده، و اتوماسیونهایی در Flows که سامانههای شما را صدا میزنند.
توسعهدهندگان
دقیقاً چه کار میکند
یک قرارداد مرجع
یک سند OpenAPI 3 کل پلتفرم را تعریف میکند؛ کلاینتهای TypeScript خودمان از همان تولید میشوند — مستندات نمیتواند از واقعیت فاصله بگیرد، چون واقعیت از روی مستندات ساخته شده.
کلیدهای Commerce API
کلیدهایی که هر مستأجر خودش صادر میکند، با دامنهٔ صریح — خواندن کاتالوگ، خواندن سفارش، نوشتن سفارش — فروشگاه یا اپلیکیشن خودتان را روی همان موتور سفارش راه میاندازند، و قیمت همیشه در سمت سرور محاسبه میشود.
webhook ورودی، امنشده
هر تریگر webhook در Flows نشانی و کلید مخفی خودش را دارد، با راستیآزمایی HMAC روی بدنهٔ خام و محافظت در برابر بازپخش. محتوای رویداد میتواند نام یک نفر را ببرد؛ اما هرگز نمیتواند درون flow را هدایت کند.
خروجی از مسیر Flows
گام REST دقیقاً در همان لحظههایی که روی بوم میکشید سامانههای شما را صدا میزند — سفارش ثبت شد، رضایت گرفته شد، نوبت رزرو شد.
جزئیات فنی
مواضع طراحی API، نوشتهشده
قیمت هرگز از سمت کلاینت نمیآید
درخواست سفارش فقط میگوید چه چیزی و چند تا — نام و قیمت همان لحظه از کاتالوگ و در سمت سرور خوانده میشود و بهصورت یک عکس لحظهای روی قلم سفارش مینشیند. درخواست دستکاریشده نمیتواند تخفیف از خودش بسازد.
قابلیتها پیش از فراخوانی
هر سطح یکپارچهسازی یک قرارداد قابلیت منتشر میکند — میتواند با شمارهٔ تلفن تطبیق دهد؟ سفارش مهمان را فهرست کند؟ سفارش بسازد؟ — و فراخوانی چیزی که صریحاً «نه» اعلام شده بلافاصله خطا میدهد، نه اینکه جایی در عمق شکست بخورد.
خطاهایی که معنا دارند
لایهٔ انتقال «عدم مجوز» را از «سرویس از کار افتاده» تشخیص میدهد — پس «فروشگاه در دسترس نیست» هیچوقت به شکل «این مشتری هرگز چیزی نخریده» نمایش داده نمیشود. خطای نامدار همان تفاوت یک API با یک بازی حدس است.
webhook مقاوم در برابر بازپخش
هر رویداد ورودی پیش از پردازش یک کلید یکتا در دفتر ثبت idempotency برمیدارد — تحویل تکراری یا بازپخششده در لایهٔ پایگاه داده میمیرد، نه داخل اتوماسیون شما.
کلیدها هششده، رمزها با دامنهٔ مشخص
کلیدهای API بهصورت هش ذخیره میشوند و دم در فقط هش و دامنهها قابل تشخیصاند — یک ردیف درزکردهٔ پایگاه داده نام هیچ فضای کاری را لو نمیدهد و چیزی فراتر از دامنههای خودش باز نمیکند.
پیشنویس و تأیید، هر دو صریحاند
ساخت سفارش یک پارامتر تأیید صریح میگیرد — پیشفرض API عمومی «تأییدشده» است و اتوماسیونهای داخل پنل میتوانند پیشنویس بسازند — پس «این واقعی است؟» یک فیلد است، نه یک عرف.
راهاندازی
چگونه متصل میشود
صدور کلید
در پنل یک کلید Commerce API با دامنهٔ مشخص بسازید؛ به همان سادگی هم باطلش کنید.
سیمکشی webhook
یک flow با تریگر webhook بسازید؛ درخواستها را با کلید مخفیاش امضا کنید.
فراخوانی به بیرون
هر جا سامانههای شما باید خبردار شوند، گام REST اضافه کنید.
کنار هم بهتر
با چه چیزهایی ترکیب میشود
Flows
تریگرهای webhook شروعکنندهٔ Flows؛ گامهای REST دقیقاً در همان لحظههایی که روی بوم میکشید سامانههای شما را صدا میزنند — اتوماسیون ورودی و خروجی یک بوم مشترک دارند.
Commerce
همین کاتالوگ و موتور سفارش پشت API همانی است که فروشگاه چت و هوش مصنوعی هم به کار میبرند — یک حقیقت سفارش، چهار در.
فروشگاه خودتان
تیمها همین امروز فروشگاههای headless را روی Commerce API میگردانند — همان مسیری که صفحهٔ Shopify تا وقتی کانکتور بومی ساخته شود بیتعارف پیشنهادش میکند.
امنیت و تضمینها
تضمینهای کسلکننده
HMAC روی بدنهٔ خام
راستیآزمایی webhook بدنهٔ خام درخواست را با کلید مخفی مخصوص همان تریگر امضا میکند و در زمان ثابت مقایسه میکند — تجزیه فقط بعد از اثبات انجام میشود.
محتوای رویداد داده است، نه فرمان
محتوای یک webhook میتواند به یک نفر ارجاع دهد؛ اما هرگز نمیتواند درون یک flow را هدایت کند، پرامپتها را بازنویسی کند یا ابزاری را فراخواند. مرز میان داده و دستور، معماری است نه رفتاری.
محدودیت نرخ روی هر در
نقطههای پایانی عمومی زیر همان محدودسازی نرخ استاندارد کار میکنند و سقف خواندن در سمت سرور محدود میشود — کلاینت بدرفتار خودش را کند میکند، نه پلتفرم را.
جزئیات ریز، بیتعارف
مرزها، نوشتهشده
هنوز خبری از جریان انبوه نیست
فید عمومی webhook که بشود در همه چیز مشترکش شد ساخته نشده — رویدادهای خروجی امروز از راه گامهای Flows بیرون میروند. اینجا نوشتهایم تا هیچ تماس فروشی لازم نباشد چیز دیگری را القا کند.
خواندن محدود، از روی طراحی
هر خواندن حداکثر 100 ردیف با مکاننما برمیگرداند — این API برای یکپارچهسازی عملیاتی ساخته شده، نه خروجی انبوه. نیاز انبوه موضوع یک گفتوگوست، نه یک راه فرار.
پرسشهای متداول API و webhook
پاسخهای بیواسطه
اطلاعات بیشتر در صفحهٔ پرسشهای متداول، یا مستقیم از ما بپرسید.
اتصال صادقانه از اتصال پرسروصدا بهتر است.
هر یکپارچهسازی در این صفحه با کاری که واقعاً انجام میدهد توصیف شده است: جهت همگامسازی، مالکیت داده و محدودیتها.