وب هوک یک مفهوم مهم در تکنولوژی اطلاعات و برنامه‌نویسی است که برای ارتباط میان سرویس‌ها و اپلیکیشن‌ها به کار می‌رود. در واقع، وب هوک به سیستمی اشاره دارد که به اپلیکیشن‌ها اجازه می‌دهد تا در زمان وقوع یک event یا رویداد در سرویس دیگری، به‌روزرسانی‌ها و اطلاعات جدید را دریافت کنند.
شما فروشندگان دیجی کالا این امکان را دارید پنل خود شخصی سازی کنید. توکن اختصاصی به شما امکان اتصال امن و پایدار به API دیجی‌کالا را می‌دهد. با آن، دسترسی به داده‌ها و عملیات مدیریت فروش راحت‌تر، سریع‌تر و بدون نیاز به ورود مکرر به پنل فروشندگی می‌شود. همچنین امنیت اطلاعات شما حفظ شده و فرآیندها را می‌توانید به‌صورت خودکار مدیریت کنید.
برای انجام این کار نیاز به دانش برنامه‌نویسی دارید و یا می‌توانید از برنامه‌نویس‌ها (دولوپرها) استفاده نمایید.
نحوه استفاده از توکن اختصاصی
از طریق پنل فروشندگی و منو “سرویس هاب” وارد صفحه سرویس هاب شوید .
بخش “توکن اختصاصی” را انتخاب نمایید.
ابتدا توکن دریافتی را رمزگشایی کنید؛ آن را از حالت Base64 خارج کرده و سپس با استفاده از Private Key خود رمزگشایی نهایی را انجام دهید. مقدار به‌دست‌آمده را از طریق سرور خود به /open-api/v1/auth/token ارسال کنید تا Access Token و Refresh Token دریافت شود.
اعتبار توکن‌ها:
Access Token: یک ساعت
Refresh Token: شش ماه
مستندات فنی وب‌هوک‌های سرویس‌هاب دیجی‌کالا
شما موافقت می‌کنید که از API فقط برای اهداف مرتبط با مدیریت فروشگاه خود، مانند دریافت سفارش‌ها، به‌روزرسانی موجودی، و قیمت‌گذاری استفاده کنید. هرگونه سوء استفاده یا فعالیت غیرمجاز و نامتعارف منجر به مسدود شدن دسترسی خواهد شد.
این توکن صرفا برای استفاده صاحب پنل ایجاد شده است و به هیچ وجه نباید مورد استفاده شخص ثالث قرار گیرد.
توکن‌ها تا زمانی که تمدید شوند معتبر هستند. به‌صورت پیش‌فرض، هر ماه به‌طور خودکار تا ۶ ماه تمدید می‌شوند، مگر اینکه آن را غیرفعال کنید. پس از ۶ ماه، برای ادامه استفاده باید توکن را مجدداً فعال کنید.
ا فعال بودن توکن هزینه به صورت خودکار بر روی فاکتور بعدی لحاظ می‌شود. این هزینه برای یک ماه کامل محاسبه می‌گردد. با غیرفعال کردن توکن، هزینه‌ها از ماه آتی کسر نمی‌گردد.
ساختار کلی:
به طور کلی، به ازای هر کلاینت می‌توان تنها یک Endpoint برای ارسال Webhook تعیین کرد و وظیفه‌ی کنترل ترافیک و Load Balancing بر عهده‌ی کلاینت می‌باشد.
هر وب‌هوک یک event_type منحصر به فرد دارد که بیانگر نوع تغییر رخ داده در سیستم است. همچنین، مقادیر ارسالی در مشخصه‌ی data با توجه به event_type کاملا متفاوت است.
دریافت هر یک از event_type ها مشروط بر این است که کلاینت دسترسی scope مربوط به آن را از فروشنده اخذ کرده باشد؛ لذا دریافت نکردن هر یک از رویدادها به معنای این است که scope مربوطه در حوزه‌ی دسترسی کلاینت نیست.
در حال حاضر، event_type های زیر وجود دارند و در هنگام رخداد از طریق ارسال Webhook به اطلاع کلاینت‌ها می‌رسد. scope (های) مورد نیاز برای دریافت هر یک از رویدادها در زیر آن‌ها نوشته شده است:
- product_variant_status_change
- variant
- order_shipment_digikala
- order
- order_shipment_seller
- order
- seller_package_status_change_order_fulfilment
- shipment
- package
- seller_package_status_change_consignment
- shipment
- package
- commission_change
- variant
- product
نکته: در صورتی که بیش از یک scope برای یک event_type نوشته شده، داشتن هر یک از این scopeها برای دریافت آن رویداد کافی است.
ساختار کلی درخواست ارسالی به شکل زیر است:
{
“event_type”: “”,
“data”: {}
}
ما تضمین می‌کنیم که حداقل یک‌بار (At Least Once) تمام این رویدادها را از طریق وب‌هوک به اطلاع کلاینت برسانیم.
نکته: تا اطلاع ثانوی، استفاده از این وب‌هوک‌ها رایگان می‌باشد. در صورت هرگونه تغییر در اسرع وقت اطلاع‌رسانی خواهد شد.
در ادامه‌ی این سند، به بررسی هر یک از event_type های موجود و جزئیات آن‌ها می‌پردازیم.
فعال / غیر فعال شدن تنوع:
این وب‌هوک در هنگام تغییر وضعیت یک تنوع اجرا می‌شود. با توجه به فیلد active می‌توان وضعیت جدید تنوع را متوجه شد.
نکته: تنها در حالتی که active = false باشد، مقدار deactivation_reason حاوی مقدار خواهد بود.
نمونه‌ی درخواست فعال شدن تنوع:
{
“event_type”: “product_variant_status_change”,
“data”: {
“product_variant_id”: 55811027,
“product_variant_title”: “کفش سنگنوردی مردانه مانگو مدل سلام | ۲۶ | گارانتی ۱۲ ماهه چرم آلدورا”,
“product_id”: 14329516,
“active”: true,
“deactivation_reason”: null,
“seller_id”: 91055
}
}
نمونه‌ی درخواست غیرفعال شدن تنوع:
{
“event_type”: “product_variant_status_change”,
“data”: {
“product_variant_id”: 55811027,
“product_variant_title”: “کفش سنگنوردی مردانه مانگو مدل سلام | ۲۶ | گارانتی ۱۲ ماهه چرم آلدورا”,
“product_id”: 14329516,
“active”: false,
“deactivation_reason”: “poor_performance”,
“seller_id”: 91055
}
}
ثبت سفارش ارسال توسط دیجی‌کالا:
هنگامی که یک سفارش با روش ارسال دیجی‌کالا ثبت شود، این وب‌هوک اجرا می‌شود.
{
“event_type”: “order_shipment_digikala”,
“data”: {
“order_shipment_id”: 224475413,
“shipping_type”: “digikala”,
“product_variant_ids”: [
۳۳۶۱۲۷۴۵,
۲۲۰۵۰۴۷۰,
۳۷۳۳۲۲۳۵
],
“quantities_per_variant”: {
“۲۲۰۵۰۴۷۰”: {
“count”: 1
},
“۳۳۶۱۲۷۴۵”: {
“count”: 1
},
“۳۷۳۳۲۲۳۵”: {
“count”: 1
}
}
}
}
ثبت سفارش ارسال توسط فروشنده:
هنگامی که یک سفارش با روش ارسال توسط فروشنده ثبت شود، این وب‌هوک اجرا می‌شود.
{
“event_type”: “order_shipment_seller”,
“data”: {
“order_shipment_id”: 224475413,
“shipping_type”: “seller”,
“product_variant_ids”: [
۳۳۶۱۲۷۴۵,
۲۲۰۵۰۴۷۰,
۳۷۳۳۲۲۳۵
],
“quantities_per_variant”: {
“۲۲۰۵۰۴۷۰”: {
“count”: 1
},
“۳۳۶۱۲۷۴۵”: {
“count”: 1
},
“۳۷۳۳۲۲۳۵”: {
“count”: 1
}
}
}
}
ایجاد / تغییر وضعیت محموله از نوع تامین سفارش:
هنگامی که یک محموله برای تامین سفارش ایجاد شود، این وب‌هوک اجرا می‌شود.
{ |
ایجاد / تغییر وضعیت محموله از نوع انبارش:
هنگامی که یک محموله برای انبارش ایجاد شود، این وب‌هوک اجرا می‌شود.
{
“event_type”: “seller_package_status_change_consignment”,
“data”: {
“seller_package_id”: 142235303,
“seller_package_status”: “new”,
“seller_package_type”: “consignment”,
“seller_package_items”: {
“۴۰۸۲۲۷۵۰”: {
“product_variant_id”: 40822750,
“status”: “new”,
“real_count”: 3,
“expected_count”: 3,
“tags”: [
“sensitive_item”
],
“created_at”: “2024-12-16 15:58:09”
},
“۴۲۰۰۶۶۶۲”: {
“product_variant_id”: 42006662,
“status”: “new”,
“real_count”: 1,
“expected_count”: 1,
“tags”: [
“sensitive_item”
],
“created_at”: “2024-12-16 15:58:09”
},
“۴۲۰۰۶۷۹۳”: {
“product_variant_id”: 42006793,
“status”: “new”,
“real_count”: 6,
“expected_count”: 6,
“tags”: [
“sensitive_item”
],
“created_at”: “2024-12-16 15:58:09”
}
}
}
}
تغییر کمیسیون گروه کالایی:
در هنگام تغییر کمیسیون برای گروه‌های کالایی، این وب‌هوک اجرا می‌شود.
نکته: هر یک از مقادیر main_category_id یا brand_id ممکن است که null باشند، که در این‌صورت این کمیسیون برای آن موارد لحاظ نمی‌شوند.
{
“event_type”: “commission_change”,
“data”: {
“main_category_id”: 8749,
“category_id”: 9378,
“brand_id”: null,
“standard_commission”: 0.001
}
}
