کاتالوگ و جفت کردن کد کالا
مخاطب: برنامه‌نویس سایت فروشگاهی یا نرم‌افزار انبارداری که می‌خواهد فهرست کالاهای پنل دیجی‌کالا را بخواند و هر کالای سایت خود را به تنوع درست در دیجی‌کالا وصل کند.
📖 مقدمه
Section titled “📖 مقدمه”در دیجی‌کالا هر کالا یک کد DKP دارد و هر رنگ، اندازه یا گارانتی آن یک تنوع با کد DKPC است. سایت شما کالاها را با کد خودش می‌شناسد. سلر ۳۶۰ این دو را به هم وصل می‌کند: کد کالای سایت شما (sku) را یک بار به تنوع جفت می‌کنید و از آن پس همه‌ی پاسخ‌ها و پیام‌های وب‌هوک آن تنوع، کد شما را هم دارند. دیگر لازم نیست جدول تبدیل کد را خودتان نگه دارید.
با مسیرهای این صفحه می‌توانید:
| کار | مسیر | در دسترس |
|---|---|---|
| فهرست تنوع‌ها | GET /v1/variants |
فعال |
| خواندن یک تنوع | GET /v1/variants/{variant_id} |
فعال |
| پنهان کردن یا نمایش تنوع در فهرست پنل | PATCH /v1/variants/{variant_id} |
فعال |
| جفت کردن کد کالای سایت با تنوع | PUT /v1/variants/{variant_id}/sku |
فعال |
| برداشتن کد کالای سایت از تنوع | DELETE /v1/variants/{variant_id}/sku |
فعال |
| فعال یا غیرفعال کردن تنوع در دیجی‌کالا | PUT /v1/variants/{variant_id}/activation |
فعال |
| کالاها با تنوع‌های آن‌ها | GET /v1/products |
فعال |
| یک کالا با تنوع‌های آن | GET /v1/products/{product_id} |
فعال |
| جست‌وجوی دسته‌های دیجی‌کالا | GET /v1/catalog/categories |
فعال |
| جست‌وجوی برندهای دیجی‌کالا | GET /v1/catalog/brands |
فعال |
و با رویداد وب‌هوک variant.status_changed از فعال یا غیرفعال شدن و تغییر وضعیت تایید هر تنوع خبردار شوید.
موجودی هر تنوع در صفحه‌ی موجودی و ساخت تنوع و کالای تازه در صفحه‌ی ساخت تنوع و کالای تازه آمده است.
⚙️ پیش‌نیازها
Section titled “⚙️ پیش‌نیازها”دسترسی (Scope)
Section titled “دسترسی (Scope)”| دسترسی | برچسب در پنل | برای |
|---|---|---|
catalog:read |
«خواندن کاتالوگ کالا» | همه‌ی مسیرهای خواندن این صفحه، از جمله جست‌وجوی دسته و برند |
catalog:write |
«تغییر کاتالوگ و جفت کردن کد کالا» | پنهان کردن، جفت کردن و برداشتن کد، و فعال یا غیرفعال کردن تنوع |
نرم‌افزاری که فقط فهرست کالا را می‌خواند، به catalog:write نیاز ندارد. نحوه‌ی ساخت کلید در ورود و دسترسی‌ها آمده است.
فعال بودن ماژول
Section titled “فعال بودن ماژول”ماژول «API و وب‌هوک» باید برای پنل فعال باشد؛ در غیر این صورت پاسخ 403 با خطای module_inactive برمی‌گردد. برای پنلی که اشتراک آن به پایان رسیده است، فعال یا غیرفعال کردن تنوع در دیجی‌کالا با خطای subscription_inactive رد می‌شود؛ جفت کردن کد و پنهان کردن تنوع که فقط در سلر ۳۶۰ ثبت می‌شوند، همچنان ممکن‌اند. جست‌وجوی دسته و برند، مانند صفحه‌ی آن در پنل، بخش «درج کالا و تنوع» را هم لازم دارد و بدون آن با خطای module_inactive رد می‌شود.
آدرس پایه
Section titled “آدرس پایه”https://api.seller360.ir🧮 مدل تنوع و کالا
Section titled “🧮 مدل تنوع و کالا”شناسه‌ها
Section titled “شناسه‌ها”| شناسه | در دیجی‌کالا | در API | توضیح |
|---|---|---|---|
| کد تنوع | «کد DKPC» | variant_id |
شناسه‌ی اصلی همه‌ی مسیرهای API؛ عدد بدون پیشوند (مثلا 84780448). |
| کد کالا | «کد DKP» | product_id |
کالایی که تنوع‌ها زیر آن هستند (مثلا 22961150). |
| کد فروشنده | «کد فروشنده» | supplier_code |
کدی که خودتان در پنل دیجی‌کالا برای تنوع ثبت کرده‌اید. چند تنوع می‌توانند یک کد فروشنده داشته باشند. |
| کد کالای سایت | — | sku |
کد کالا در سایت یا نرم‌افزار شما؛ فقط در سلر ۳۶۰ ثبت می‌شود و دیجی‌کالا آن را نمی‌بیند. |
فیلدهای تنوع (Variant)
Section titled “فیلدهای تنوع (Variant)”| فیلد | برچسب در پنل | معنی |
|---|---|---|
variant_id |
«کد DKPC» | کد تنوع در دیجی‌کالا. |
product_id |
«کد DKP» | کد کالایی که تنوع زیر آن است. |
supplier_code |
«کد فروشنده» | کد فروشنده‌ی تنوع در دیجی‌کالا؛ اگر ثبت نشده باشد null. |
sku |
— | کد کالای سایت شما، اگر جفت شده باشد. |
title |
«عنوان» | عنوان کامل تنوع: نام کالا، رنگ یا اندازه، و گارانتی. |
is_active |
«فعال» / «غیرفعال» | فعال بودن فروش تنوع در دیجی‌کالا. |
moderation_status |
«وضعیت تایید» | وضعیت تایید محتوای دیجی‌کالا، به نام خود دیجی‌کالا (مثلا approved). |
image_url |
— | نشانی عکس تنوع. |
product_url |
— | نشانی صفحه‌ی کالا در دیجی‌کالا. |
category_id |
— | شناسه‌ی دسته‌ی کمیسیون دیجی‌کالا. |
category_title |
«دسته» | نام دسته. |
brand_title |
«برند» | نام برند. |
hidden |
«پنهان» | تنوع در فهرست اصلی محصولات پنل سلر ۳۶۰ پنهان شده است؛ اثری در دیجی‌کالا ندارد. |
synced_at |
— | زمان آخرین همگام‌سازی این تنوع از دیجی‌کالا. |
فیلدهای کالا (CatalogProduct)
Section titled “فیلدهای کالا (CatalogProduct)”مسیر GET /v1/products همان تنوع‌ها را بر اساس کد DKP گروه‌بندی می‌کند:
| فیلد | معنی |
|---|---|
product_id |
کد DKP. |
title |
نام کالا (بخش اول عنوان تنوع‌ها). |
category_title، brand_title |
دسته و برند. |
image_url، product_url |
عکس و صفحه‌ی کالا. |
supplier_codes |
کدهای فروشنده‌ی تنوع‌های این کالا. |
variants |
تنوع‌ها: variant_id، title (فقط بخش رنگ یا اندازه، مثلا «سفید»)، supplier_code، sku، is_active و warranty. |
synced_at |
قدیمی‌ترین زمان همگام‌سازی تنوع‌های این کالا. |
🔢 تازگی
Section titled “🔢 تازگی”- همگام‌سازی کاتالوگ: فهرست تنوع‌ها و کالاها هر شب ساعت ۰۲:۱۰ به وقت تهران، پیش از هر اجرای تقسیم موجودی، و هر بار که در پنل «همگام‌سازی» را بزنید، از دیجی‌کالا خوانده می‌شود. زمان آخرین خواندن هر تنوع در
synced_atاست. - جست‌وجوی دسته و برند: هر درخواست همان لحظه از دیجی‌کالا پرسیده می‌شود و نسخه‌ی ذخیره‌شده ندارد.
- جفت کردن کد و پنهان کردن: فوری‌اند و در همان پاسخ دیده می‌شوند.
⚠️ هشدارها
Section titled “⚠️ هشدارها”📡 مسیرها
Section titled “📡 مسیرها”GET /v1/variants — فهرست تنوع‌ها فعال
Section titled “GET /v1/variants — فهرست تنوع‌ها ”همه‌ی تنوع‌های پنل، صفحه‌به‌صفحه و به ترتیب variant_id. برای همگام‌سازی اولیه‌ی کاتالوگ سایت شما مناسب است.
GET /v1/variants?page=1&size=100&active=1 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...پارامترها
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
page |
عدد | خیر | شماره‌ی صفحه؛ پیش‌فرض ۱. |
size |
عدد | خیر | تعداد در هر صفحه؛ پیش‌فرض ۵۰، بیشینه ۵۰۰. |
active |
0 یا 1 |
خیر | فقط تنوع‌های فعال (1) یا غیرفعال (0). |
sku |
متن | خیر | تنوعی که با این کد کالای سایت شما جفت شده است. |
supplier_code |
متن | خیر | فقط تنوع‌های این کد فروشنده. |
product_id |
عدد | خیر | فقط تنوع‌های این کالا (کد DKP). |
hidden |
0 یا 1 |
خیر | فقط تنوع‌های پنهان‌شده (1) یا پنهان‌نشده (0). |
پاسخ نمونه
{ "status": "ok", "data": [ { "variant_id": 84780448, "product_id": 22961150, "supplier_code": "5144", "sku": "NK-1024-G", "title": "محافظ ولتاژ پارت الکتریک مدل PE5144 | سفید | گارانتی ۱۸ ماهه پارت الکتریک", "is_active": true, "moderation_status": "approved", "image_url": "https://dkstatic.digikala.com/digikala-products/a1b2c3.jpg", "product_url": "https://www.digikala.com/product/dkp-22961150/", "category_id": 8925, "category_title": "محافظ ولتاژ", "brand_title": "پارت الکتریک", "hidden": false, "synced_at": "2026-11-13T02:14:07+03:30" } ], "pager": { "page": 1, "item_per_page": 100, "total_pages": 7, "total_rows": 606 }}GET /v1/variants/{variant_id} — یک تنوع فعال
Section titled “GET /v1/variants/{variant_id} — یک تنوع ”همان ساختار، برای یک تنوع. اگر تنوع در این پنل نباشد، کد 404 و خطای variant_not_found برمی‌گردد.
PATCH /v1/variants/{variant_id} — پنهان کردن یا نمایش فعال
Section titled “PATCH /v1/variants/{variant_id} — پنهان کردن یا نمایش ”فقط برچسب محلی «پنهان» را تغییر می‌دهد (هشدار ۳).
PATCH /v1/variants/84780448 HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: hide-84780448-1405-08-23Content-Type: application/json
{ "hidden": true }| فیلد بدنه | نوع | اجباری | توضیح |
|---|---|---|---|
hidden |
true یا false |
بله | true برای پنهان کردن، false برای نمایش دوباره. |
پاسخ موفق: کد 200 با ساختار کامل تنوع.
PUT /v1/variants/{variant_id}/sku — جفت کردن کد کالای سایت فعال
Section titled “PUT /v1/variants/{variant_id}/sku — جفت کردن کد کالای سایت ”کد کالای سایت شما را روی تنوع می‌گذارد. اگر تنوع قبلا کد دیگری داشته باشد، کد تازه جای آن را می‌گیرد. فقط در سلر ۳۶۰ ثبت می‌شود.
PUT /v1/variants/84780448/sku HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: sku-84780448-NK-1024-GContent-Type: application/json
{ "sku": "NK-1024-G" }| فیلد بدنه | نوع | اجباری | توضیح |
|---|---|---|---|
sku |
متن | بله | ۱ تا ۱۰۰ نویسه؛ در این پنل یکتا. |
پاسخ نمونه (کد 200)
{ "status": "ok", "data": { "variant_id": 84780448, "product_id": 22961150, "supplier_code": "5144", "sku": "NK-1024-G", "title": "محافظ ولتاژ پارت الکتریک مدل PE5144 | سفید | گارانتی ۱۸ ماهه پارت الکتریک", "is_active": true, "hidden": false }}خطاهای این مسیر
| کد HTTP | خطا | معنی | تکرار بی‌خطر است؟ |
|---|---|---|---|
400 |
invalid_parameter |
sku خالی یا بلندتر از ۱۰۰ نویسه است. |
خیر؛ بدنه را اصلاح کنید. |
404 |
variant_not_found |
این تنوع در این پنل نیست. | خیر. |
409 |
sku_taken |
این کد پیش‌تر به تنوع دیگری از این پنل جفت شده است. | خیر؛ ابتدا کد را از تنوع قبلی بردارید. |
409 |
idempotency_mismatch |
این کلید یکتا قبلا با بدنه‌ی دیگری استفاده شده است. | خیر؛ کلید تازه بسازید. |
409 |
idempotency_in_progress |
درخواستی با همین کلید در حال انجام است. | بله، چند ثانیه بعد. |
DELETE /v1/variants/{variant_id}/sku — برداشتن کد کالای سایت فعال
Section titled “DELETE /v1/variants/{variant_id}/sku — برداشتن کد کالای سایت ”کد سایت را از تنوع برمی‌دارد و فقط در سلر ۳۶۰ ثبت می‌شود. پاسخ موفق: کد 200 با تنوع و sku: null. اگر پاسخ را دریافت نکردید، همان درخواست را با همان Idempotency-Key تکرار کنید.
PUT /v1/variants/{variant_id}/activation — فعال یا غیرفعال کردن در دیجی‌کالا فعال
Section titled “PUT /v1/variants/{variant_id}/activation — فعال یا غیرفعال کردن در دیجی‌کالا ”وضعیت فروش تنوع را در دیجی‌کالا تغییر می‌دهد و پس از ثبت قطعی در دیجی‌کالا پاسخ می‌دهد.
PUT /v1/variants/84780448/activation HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...Idempotency-Key: deactivate-84780448-1405-08-23Content-Type: application/json
{ "is_active": false }| فیلد بدنه | نوع | اجباری | توضیح |
|---|---|---|---|
is_active |
true یا false |
بله | false فروش تنوع را در دیجی‌کالا متوقف می‌کند. |
خطاهای این مسیر
| کد HTTP | خطا | معنی | تکرار بی‌خطر است؟ |
|---|---|---|---|
403 |
subscription_inactive |
اشتراک پنل فعال نیست؛ تغییر در دیجی‌کالا ممکن نیست. | خیر. |
404 |
variant_not_found |
این تنوع در این پنل نیست. | خیر. |
422 |
price_out_of_band |
برای فعال کردن، قیمت فعلی تنوع بیرون از بازه‌ی مجاز دیجی‌کالاست و دیجی‌کالا فعال شدن آن را نمی‌پذیرد؛ هیچ تغییری فرستاده نشد. | پس از تغییر قیمت. |
502 |
digikala_outcome_unknown |
پاسخ دیجی‌کالا نرسید و وضعیت تازه‌ی تنوع روشن نیست. | خیر؛ ابتدا تنوع را بخوانید. |
502 |
digikala_refused |
دیجی‌کالا تغییر را نپذیرفت؛ هیچ تغییری ثبت نشد. | پس از بررسی علت در detail. |
503 |
digikala_rate_limited |
سقف نوشتن دیجی‌کالا برای این پنل پر است. | بله، پس از Retry-After. |
503 |
digikala_unavailable |
دیجی‌کالا در دسترس نیست. | بله، پس از Retry-After؛ با همان Idempotency-Key. |
GET /v1/products — کالاها با تنوع‌های آن‌ها فعال
Section titled “GET /v1/products — کالاها با تنوع‌های آن‌ها ”تنوع‌های پنل، گروه‌بندی‌شده بر اساس کد DKP و به ترتیب شناسه‌ی کالا. برای ساخت صفحه‌ی کالا با چند رنگ در سایت شما مناسب است.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
page، size |
عدد | خیر | صفحه‌بندی. |
supplier_code |
متن | خیر | فقط کالاهایی که دست‌کم یک تنوع با این کد فروشنده دارند. |
پاسخ نمونه
{ "status": "ok", "data": [ { "product_id": 22961150, "title": "محافظ ولتاژ پارت الکتریک مدل PE5144", "category_title": "محافظ ولتاژ", "brand_title": "پارت الکتریک", "image_url": "https://dkstatic.digikala.com/digikala-products/a1b2c3.jpg", "product_url": "https://www.digikala.com/product/dkp-22961150/", "supplier_codes": ["5144"], "variants": [ { "variant_id": 84780448, "title": "سفید", "supplier_code": "5144", "sku": "NK-1024-G", "is_active": true, "warranty": "گارانتی ۱۸ ماهه پارت الکتریک" }, { "variant_id": 84780452, "title": "مشکی", "supplier_code": "5144", "sku": null, "is_active": true, "warranty": "گارانتی ۱۸ ماهه پارت الکتریک" } ], "synced_at": "2026-11-13T02:14:07+03:30" } ], "pager": { "page": 1, "item_per_page": 50, "total_pages": 5, "total_rows": 231 }}GET /v1/products/{product_id} — یک کالا فعال
Section titled “GET /v1/products/{product_id} — یک کالا ”همان ساختار، برای یک کالا. اگر کالا در این پنل نباشد، کد 404 و خطای not_found برمی‌گردد.
GET /v1/catalog/categories — جست‌وجوی دسته فعال
Section titled “GET /v1/catalog/categories — جست‌وجوی دسته ”همان لحظه از دیجی‌کالا جست‌وجو می‌کند. برای ساخت کالای تازه شناسه‌ی یک دسته‌ی برگ لازم است.
GET /v1/catalog/categories?q=محافظ%20ولتاژ HTTP/1.1Host: api.seller360.irAuthorization: Bearer s360_live_...| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
q |
متن | بله | بخشی از نام دسته؛ ۲ تا ۱۰۰ نویسه. |
{ "status": "ok", "data": [ { "id": 8925, "title": "محافظ ولتاژ", "leaf": true }, { "id": 8920, "title": "محافظ و چندراهی برق", "leaf": false } ]}اگر دیجی‌کالا پاسخ ندهد، کد 503 با خطای digikala_unavailable یا digikala_rate_limited و سرآیند Retry-After برمی‌گردد.
GET /v1/catalog/brands — جست‌وجوی برند فعال
Section titled “GET /v1/catalog/brands — جست‌وجوی برند ”همان لحظه از دیجی‌کالا جست‌وجو می‌کند. متن لاتین با نام انگلیسی و متن فارسی با نام فارسی برند مقایسه می‌شود.
| پارامتر | نوع | اجباری | توضیح |
|---|---|---|---|
q |
متن | بله | بخشی از نام برند، فارسی یا انگلیسی؛ ۲ تا ۱۰۰ نویسه. |
{ "status": "ok", "data": [ { "id": 61944, "title": "پارت الکتریک", "logo_url": "https://dkstatic.digikala.com/brands/61944.png" } ]}🔔 رویدادهای وب‌هوک
Section titled “🔔 رویدادهای وب‌هوک”| رویداد | چه وقت |
|---|---|
variant.status_changed |
تنوعی فعال یا غیرفعال شد یا وضعیت تایید محتوای آن تغییر کرد؛ پس از همگام‌سازی کاتالوگ. |
نمونه‌ی پیام variant.status_changed
{ "id": "evt_01J0A7QK", "type": "variant.status_changed", "created_at": "2026-11-13T02:14:09+03:30", "panel_id": 1, "livemode": true, "data": { "variant": { "variant_id": 84780452, "product_id": 22961150, "supplier_code": "5144", "sku": null, "title": "محافظ ولتاژ پارت الکتریک مدل PE5144 | مشکی | گارانتی ۱۸ ماهه پارت الکتریک", "is_active": false, "moderation_status": "approved", "hidden": false }, "previous": { "is_active": true, "moderation_status": "approved" } }}پیام‌ها ممکن است تکراری یا جابه‌جا برسند؛ با id رویداد تکراری‌ها را کنار بگذارید (تکرار و ترتیب). پیش از استفاده از هر پیام، امضای آن را بررسی کنید.
💻 نمونه‌کد: جفت کردن کد کالای سایت
Section titled “💻 نمونه‌کد: جفت کردن کد کالای سایت”- فهرست تنوع‌ها را با
GET /v1/variantsبخوانید. - برای هر کالای سایت، تنوع درست را (مثلا با
supplier_codeو عنوان) پیدا کنید. - کد سایت را با
PUT /v1/variants/{variant_id}/skuجفت کنید. - از این پس برای یافتن تنوع،
GET /v1/variants?sku=...را بخوانید.
curl -X PUT https://api.seller360.ir/v1/variants/84780448/sku \ -H "Authorization: Bearer $S360_API_KEY" \ -H "Idempotency-Key: sku-84780448-NK-1024-G" \ -H "Content-Type: application/json" \ -d '{"sku": "NK-1024-G"}'$ch = curl_init("https://api.seller360.ir/v1/variants/84780448/sku");curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("S360_API_KEY"), "Idempotency-Key: sku-84780448-NK-1024-G", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode(["sku" => "NK-1024-G"]), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 20,]);$res = json_decode(curl_exec($ch), true);if (($res["error"]["code"] ?? null) === "sku_taken") { // این کد روی تنوع دیگری است؛ ابتدا آن را بردارید}import os, requests
res = requests.put( "https://api.seller360.ir/v1/variants/84780448/sku", headers={ "Authorization": f"Bearer {os.environ['S360_API_KEY']}", "Idempotency-Key": "sku-84780448-NK-1024-G", }, json={"sku": "NK-1024-G"}, timeout=20,).json()if res["status"] == "error" and res["error"]["code"] == "sku_taken": ... # این کد روی تنوع دیگری است؛ ابتدا آن را برداریدconst res = await fetch('https://api.seller360.ir/v1/variants/84780448/sku', { method: 'PUT', headers: { Authorization: `Bearer ${process.env.S360_API_KEY}`, 'Idempotency-Key': 'sku-84780448-NK-1024-G', 'Content-Type': 'application/json', }, body: JSON.stringify({ sku: 'NK-1024-G' }),})const body = await res.json()if (body.error?.code === 'sku_taken') { // این کد روی تنوع دیگری است؛ ابتدا آن را بردارید}using var http = new HttpClient();var req = new HttpRequestMessage(HttpMethod.Put, "https://api.seller360.ir/v1/variants/84780448/sku");req.Headers.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("S360_API_KEY")}");req.Headers.Add("Idempotency-Key", "sku-84780448-NK-1024-G");req.Content = JsonContent.Create(new { sku = "NK-1024-G" });var res = await http.SendAsync(req);var body = await res.Content.ReadFromJsonAsync<JsonElement>();