دليل التكامل مع Hepsiburada 2026: REST API وHepsiJet & إدارة البائعين المركزية

1. بنية API الخاصة بـ Hepsiburada 2026

REST على mpop.hepsiburada.com

واجهة برمجة تطبيقات البائع لدى Hepsiburada هي خدمة REST/JSON خالصة تُستضاف تحت المضيف المظلة mpop.hepsiburada.com (mpop = «Merchant Platform Open API»). لا يوجد متغيّر GraphQL أو gRPC. تجري كل حركة المرور المُصادَق عليها عبر HTTPS، مرتبطة بـ Merchant ID يُصدر أثناء الإعداد في HMS. تنقسم واجهة API إلى نطاقات فرعية منطقية بدلاً من جذر أحادي واحد:

• listing-external.hepsiburada.com — CRUD للقوائم (السعر، المخزون، حالة القائمة)
• mpop.hepsiburada.com/product/api/products — إنشاء المنتجات وسمات الفئة
• oms-external.hepsiburada.com — إدارة الطلبات (الطلبات، الطرود، الشحنات)
• returns-external.hepsiburada.com — المرتجعات والاستردادات
• integration.hepsiburada.com/finance — رفع الفواتير والتسوية المالية

يشترك كل نطاق فرعي في مخطط مصادقة HTTP Basic نفسه لكنه يعرض حدود معدّل واتفاقيات ترقيم صفحات خاصة به. يُخفي موصّل HB في Zunapro هذا التشعّب خلف واجهة موحّدة منمّطة.

المصادقة: HTTP Basic عبر HTTPS

على عكس واجهة Trendyol الأكثر تساهلًا قليلًا أو تدفق OAuth الخاص بـ SP-API لدى Amazon، تستخدم Hepsiburada مخطط مصادقة HTTP Basic بسيطًا عن قصد: تحمل ترويسة Authorization القيمة Basic base64(username:password)، حيث يكون username هو مفتاح API الخاص بك وpassword هو السر المقترن. يجب أن يحمل كل طلب أيضًا ترويسة User-Agent تتضمن معرّف التاجر الخاص بك. تُعد قيم User-Agent المفقودة أو المشوّهة السبب الأكثر شيوعًا لخطأ 401 Unauthorized في الإنتاج.

GET /listings/merchantid/{MERCHANT_ID}/sku/{MERCHANTSKU}
Host: listing-external.hepsiburada.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
User-Agent: {MERCHANT_ID} - SelfIntegration
Accept: application/json

HMS — لوحة Hepsiburada Marketplace Service

لوحة HMS على merchant.hepsiburada.com هي وحدة تحكم الويب التشغيلية المقترنة بواجهة برمجة التطبيقات. لكل إمكانية في API مكافئ في HMS — تعديلات القوائم، قبول الطلبات، إصدار الاسترداد، التسوية المالية — وHMS هي المكان الوحيد الذي تُنشئ فيه مفاتيح API، وتُهيئ فيه عناوين استلام HepsiJet، وتُدير فيه أذونات المستخدمين. جلبت إعادة تصميم HMS بين 2024–2026 تنقّلًا موحّدًا على اليسار، وتقارير تسوية في الوقت الفعلي، ولوحة معلومات «API Health» جديدة تُظهر معدّلات 4xx/5xx لكل نقطة نهاية، وهو أمر لا يقدّر بثمن عند تصحيح أخطاء التكامل.

حدود المعدّل والتكرار الآمن (Idempotency)

تطبّق Hepsiburada حدود معدّل سخية لكن مفروضة — عادةً ~30 طلبًا/ثانية لكل تاجر على تحديثات القوائم وأقل (~10/ثانية) على نقاط نهاية الطلبات. تُقيّد عمليات الاستيراد المجمّع للمنتجات على نحو منفصل وتُرجع 202 Accepted مع trackingId؛ ثم تستطلع /import/{trackingId} للتحقق من الاكتمال. تدعم واجهة الطلبات التكرار الآمن عبر معرّفات الطرود والطلبات التي تبقى ثابتة عبر عمليات القراءة.

2. الاتصال عبر REST API — خطوة بخطوة

المتطلبات المسبقة: حساب HMS & ETBİS

قبل أي استدعاء لواجهة برمجة التطبيقات، يجب على شركة مسجّلة في تركيا ولديها vergi numarası (رقم ضريبي)، وتسجيل ETBİS (Elektronik Ticaret Bilgi Sistemi — سجل شركات التجارة الإلكترونية التابع لوزارة التجارة)، وحساب IBAN تركي (TR…) أن تُكمل الإعداد عبر HMS. عادةً ما تُنجز مراجعة KYC خلال 1–3 أيام عمل للكيانات المسجّلة في ETBİS؛ أما البائعون غير المسجّلين في ETBİS فيُوجَّهون إلى طابور مراجعة يدوية قد يستغرق 1–2 أسبوع.

إعداد واجهة برمجة التطبيقات خطوة بخطوة

1. أنشئ حساب HMS على merchant.hepsiburada.com باستخدام vergi numarası وIBAN الخاصين بك. ارفع شهادة ETBİS، ونموذج التوقيع، ووثيقة السلطة الضريبية.
2. أنشئ بيانات اعتماد API ضمن Hesabım → Entegrasyon Bilgileri → API Anahtarı. يُرجع النظام اسم مستخدم وكلمة مرور ومعرّف التاجر الثابت الخاص بك. خزّن الأسرار في خزنة (vault) — لن تعرض Hepsiburada كلمة المرور مرة أخرى.
3. أدرج عناوين IP الصادرة في القائمة البيضاء إذا كانت منصة التكامل لديك تتطلب ذلك. تنشر Zunapro نطاق IP صادر ثابتًا حتى يتمكن البائعون من تثبيته على قائمة السماح في HMS.
4. اختبر بقراءة قائمة — استدعِ GET /listings/merchantid/{MERCHANT_ID} وتأكد من 200 OK مع مخزونك الحالي.
5. اشترك في webhooks لأحداث الطلبات: POST /webhook-subscriptions مع عنوان رد الاتصال (callback URL) وأنواع الأحداث (order.created، order.cancelled، return.created).
6. ادفع منتجك الأول باستخدام POST /product/api/products/import — تُرجع Hepsiburada رقم trackingId؛ استطلعه حتى يصبح status:DONE.
7. انطلق مباشرةً — بدّل التكامل إلى «Aktif» في HMS بمجرد اجتياز اختبارات التحقق.

الترويسات والمزالق الشائعة

الانحدار الأكثر تكرارًا في التكامل هو ترويسة User-Agent مفقودة أو مشوّهة. تتطلب Hepsiburada بصرامة التنسيق {MERCHANT_ID} - {AppName}؛ ويُرجع User-Agent الافتراضي مثل axios/1.6 أو okhttp/4 خطأ 401 Unauthorized دون نص وصفي. اضبط User-Agent دائمًا صراحةً وسجّله في وسيط الطلبات (middleware) لديك.

3. مزامنة المنتجات — شجرة الفئات، السمات، المتغيّرات

شجرة الفئات

يُنظَّم كتالوج Hepsiburada على شكل شجرة فئات صارمة من ثلاثة إلى خمسة مستويات تُعرض عبر GET /product/api/categories/get-all-categories. يجب أن يُطابق كل منتج معرّف فئة على مستوى الورقة؛ وتُرفض العُقد الوسيطة بخطأ VALIDATION_ERROR. دمج إصلاح الفئات لعام 2024 عدة عُقد قديمة (تم دمج «Bluetooth Kulaklık» و«Kablosuz Kulaklık» المدرجين منفصلين في «Kablosuz Kulaklık & Bluetooth»)، لذا يحتاج أي تكامل أقدم من ذلك إلى تحديث لمطابقة الفئات.

السمات الإلزامية تحجب الاعتماد

تعرض كل فئة قائمة بالسمات الإلزامية والاختيارية عبر GET /product/api/categories/{categoryId}/attributes. على عكس Trendyol، تتعامل Hepsiburada مع السمات الإلزامية المفقودة بوصفها حجبًا صارمًا للقائمة — يدخل المنتج في حالة WAITING_FOR_APPROVAL ولا يصل أبدًا إلى «Active» حتى تُملأ كل سمة مطلوبة بقيمة بحث صالحة. المخالفات الشائعة:

• العلامة التجارية — يجب أن تطابق سجل علامات Hepsiburada بالضبط؛ «Apple» و«APPLE» معرّفان مختلفان
• اللون، المقاس، السعة — تُسحب من مفردات مضبوطة، وليس نصًا حرًا
• مدة الضمان — مطلوبة للإلكترونيات، مُعبّر عنها بالأشهر كقيمة enum
• بلد المنشأ (Menşei) — مطلوب لمستحضرات التجميل والأغذية والمكمّلات

المتغيّرات: فصل listing & product

تستخدم Hepsiburada فصلًا أكثر صرامة بين product مقابل listing من معظم المنافسين. يمكن أن يحتوي product واحد (HB-SKU، معرّف داخلي) على قوائم كثيرة (merchantSku) — واحدة لكل بائع، بسعرها ومخزونها وحالتها (جديد/مُجدَّد) وضمانها الخاص. بالنسبة لمنتجات المتغيّرات (مثل تيشيرت بمقاسات S/M/L × أحمر/أزرق/أسود)، يكون كل تركيب عُقدة product منفصلة، تُجمَّع اختياريًا تحت varyantGroupID بحيث تعرض صفحة المنتج عيّنات اللون والمقاس.

الاستيراد المجمّع عبر trackingId

تستخدم عمليات دفع الكتالوج في الإنتاج POST /product/api/products/import بمصفوفة تضم حتى 100 منتج لكل طلب. تُرجع واجهة API رقم trackingId؛ ويجب على المُكامِلين استطلاع GET /product/api/products/import/{trackingId} حتى تصبح الحالة DONE ثم المرور على النتائج صفًا صفًا بحثًا عن أخطاء التحقق. تُجمّع Zunapro عمليات الاستيراد في دفعات من 100 صف، وتعيد محاولة الإخفاقات الطفيفة، وتُظهر تقارير أخطاء على مستوى الصف داخل لوحة البائع.

POST /product/api/products/import
Host: mpop.hepsiburada.com
Authorization: Basic ...
User-Agent: {MERCHANT_ID} - Zunapro

{
  "merchant": "{MERCHANT_ID}",
  "items": [{
    "merchantSku": "ZP-TSHIRT-RED-M",
    "categoryId": 18021982,
    "productName": "Premium Pamuklu T-Shirt — Kırmızı M",
    "brand": "Zuna",
    "attributes": [
      {"name":"Renk","value":"Kırmızı"},
      {"name":"Beden","value":"M"}
    ],
    "price": 249.90,
    "availableStock": 87,
    "varyantGroupID": "ZP-TSHIRT-2026"
  }]
}

4. إدارة الطلبات — Webhooks، تدفق الحالة، الملصقات

دورة حياة الطلب

يمر طلب Hepsiburada عبر آلة حالات ثابتة يجب على كل تكامل تنفيذها. الحالات مهمة — تُطلق الانتقالات المبكّرة نقاط جزائية ضد درجة البائع الخاصة بك:

• Open — تم استلام الطلب، في انتظار القبول (اتفاقية مستوى خدمة 24 ساعة في معظم الفئات، 48 ساعة للأثاث)
• InProgress / Picking — أقرّ البائع، جارٍ الانتقاء والتغليف
• Packaged — تم إنشاء الطرد عبر API، في انتظار التسليم إلى الناقل
• Shipped — مسح الناقل الطرد؛ رقم التتبع نشط
• Delivered — أكّدت الميل الأخير التسليم
• Cancelled / Returned — بوابة إرجاع بدأها العميل أو التاجر

Webhook مقابل الاستطلاع (polling)

تدعم Hepsiburada كلًا من webhooks (المفضّلة) والاستطلاع. تُهيَّأ webhooks لكل Merchant ID في HMS أو عبر POST /webhook-subscriptions؛ تدفع المنصة أحداث JSON إلى نقطة نهاية HTTPS الخاصة بك بتوقيعات HMAC في ترويسة X-HB-Signature. يعود الاستطلاع إلى GET /orders?status=Open&offset=0&limit=100 على مهمة cron كل 30–60 ثانية. تعتمد Zunapro webhooks افتراضيًا مع مُسوٍّ استطلاع كل 5 دقائق يلتقط أي أحداث فائتة — نمط الحزام والحمّالة الذي يُبقي اكتمال الطلبات فوق 99.99%.

ملصقات الشحن: التوليد التلقائي لـ HepsiJet

عندما تضع علامة على طلب بأنه Packaged مع اختيار HepsiJet، تولّد واجهة API تلقائيًا ملصق شحن PDF قابلًا للطباعة وتُرجع عنوان URL للتنزيل بالإضافة إلى رقم تتبع. لا يوجد طلب ملصق منفصل — يأتي الملصق مضمّنًا في استجابة إنشاء الطرد:

POST /packages
Host: oms-external.hepsiburada.com

{
  "orderId": "HB-72184",
  "lineItems": [{"id": "HB-72184-1", "qty": 1}],
  "cargoCompany": "HepsiJet"
}

→ 201 Created
{
  "packageId": "PKG-998812",
  "trackingNumber": "HJ73219840TR",
  "labelUrl": "https://mpop.hepsiburada.com/labels/PKG-998812.pdf",
  "status": "Packaged"
}

بوابة المرتجعات

تبدأ المرتجعات من العميل عبر بوابة الإرجاع القياسية لدى Hepsiburada (Iade Talepleri) وتظهر للبائعين عبر GET /returns?status=Open. أمام البائعين 3 أيام عمل للموافقة على الإرجاع أو الاعتراض عليه؛ وتبدأ الموافقة التلقائية بعد ذلك. تُطلق المرتجعات المعتمدة استردادًا عبر مسار الدفع لدى Hepsiburada (الذي سيراه البائع في التسوية المالية التالية)، وينبغي إعادة قيد المخزون عبر PUT /listings/{merchantSku}/stock.

5. مزامنة المخزون & السعر — الوقت الفعلي، Buy Box، أداة إعادة التسعير

نقطة نهاية المخزون

يُحدَّث المخزون عبر واجهة القوائم بحمولة مدركة للفروقات (delta):

PUT /listings/merchantid/{MERCHANT_ID}/sku/{MERCHANTSKU}
{
  "availableStock": 42,
  "price": 299.90
}

تقبل نقطة النهاية السعر والمخزون في الاستدعاء نفسه، لكن قد تستغرق ذاكرة التخزين المؤقت الداخلية لدى Hepsiburada 30–90 ثانية للانتشار إلى واجهة المتجر. تستخدم التحديثات المجمّعة POST /listings/import بنمط trackingId نفسه المستخدم في استيراد المنتجات.

الوقت الفعلي مقابل مزامنة cron

يستخدم البائعون على مستوى الإنتاج مزامنة مدفوعة بالأحداث (كل تغيير في المخزون في نظام ERP الخاص بك يُطلق طلب PUT إلى Hepsiburada خلال ثوانٍ) بدلاً من cron كل 15 دقيقة. خطر المزامنة بـ cron فقط هو البيع الزائد خلال فترات الذروة (Ramazan kampanyası، Black Friday، Efsane Cuma). يُطلق النموذج الهجين لدى Zunapro طلبات PUT فورية ومُسوّيًا كل 15 دقيقة تحسّبًا للأحداث المفقودة — النمط نفسه الموثّق في بنية المزامنة التلقائية للسعر & المخزون master→local→targets.

الفوز بـ Buy Box

يُمنح Buy Box لدى Hepsiburada (عرض «Sepete Ekle» الافتراضي على صفحة منتج مشتركة) عبر صيغة مرجّحة تجمع:

• السعر — تنافسي ضمن 1–2% من أدنى عرض صالح
• سلامة المخزون — العمق والحداثة وعدم وجود نفاد حديث
• وعد التسليم — يفوز HepsiJet عند تساوي كل شيء آخر
• تقييم البائع — حد أدنى 9.0+ عبر مؤشرات أداء التسليم والخدمة
• معدل عيوب الطلبات — تُعاقب الإلغاءات والشحنات المتأخرة والمرتجعات

عادةً ما ترفع أداة إعادة تسعير مضبوطة جيدًا تعيد تقييم أسعار المنافسين كل 5–10 دقائق حصة Buy Box بنسبة 15–30% على وحدات SKU المتنازع عليها.

6. HepsiJet — شبكة التوصيل المملوكة

الميل الأخير المتكامل رأسيًا لدى Hepsiburada

HepsiJet هي شبكة توصيل الميل الأخير المملوكة لـ Hepsiburada، أُطلقت عام 2017 لكسر الاعتماد على Yurtiçi وAras Kargo على وحدات SKU الحساسة للوقت. وبحلول 2026 تُشغّل HepsiJet 1500+ نقطة استلام عبر 81 محافظة، وتُنفّذ التوصيل في نفس اليوم في إسطنبول وأنقرة وإزمير، وتستخدم أسطولها الخاص المؤلف من أكثر من 2500 مركبة إضافة إلى شبكة من فروع الامتياز (shubeleri).

معيار الباركود وتنسيق الملصق

يحمل كل ملصق شحن من HepsiJet باركود Code-128 يشفّر رقم تتبع من 12 حرفًا مسبوقًا بـ HJ (على سبيل المثال HJ73219840TR). يستخدم ملصق PDF المُولَّد من API تخطيط A6 المناسب للطابعات الحرارية؛ ويمكن طباعة الملصقات مباشرةً عبر طابور ZPL المدمج.

نفس اليوم & Yarın Kapında

تقدّم HepsiJet مستويي تسليم متميّزين مرئيين على صفحة المنتج:

• «Yarın Kapında» — التوصيل في اليوم التالي في 81 محافظة عندما يُشحن الطلب قبل الساعة 14:00 بالتوقيت المحلي
• «Bugün Kapında» — التوصيل في نفس اليوم في إسطنبول وأنقرة وإزمير وبورصة وأضنة للطلبات المقدَّمة قبل الساعة 11:00

ترفع الشارتان معدل التحويل بشكل ملموس — تشير بيانات Hepsiburada الخاصة إلى ارتفاع في التحويل بنسبة 15–25% على القوائم التي تحمل الشارتين، وهو ما يعادل تقريبًا تأثير «Hızlı Teslimat» لدى Trendyol.

الاستلام مقابل Şubeye Bırak

يختار البائعون بين استلام HepsiJet (يجمع الناقل من المستودع، يُحتسب لكل طرد) وŞubeye Bırak (يُسلّم البائع الطرود في أقرب فرع HepsiJet، أرخص لكل طرد لكن أثقل تشغيليًا). تدعم واجهة التكامل كليهما — تتضمن استجابة الطرد حقل pickupAddressId الذي يحدد التوجيه.

7. HepsiLojistik — نموذج FBA

ما هي HepsiLojistik

HepsiLojistik هي خدمة الوفاء عبر السوق (fulfillment-by-marketplace) لدى Hepsiburada — النظير التركي لـ Amazon FBA وTrendyol TFC وAllegro One Fulfillment. يشحن البائعون المخزون بالجملة إلى مراكز الوفاء لدى Hepsiburada؛ وتتولى Hepsiburada التخزين والانتقاء والتغليف وتسليم الميل الأخير (عبر HepsiJet) والمرتجعات. تحمل طلبات HepsiLojistik شارة «Hepsiburada Garanti» المميّزة وتتأهل لأعلى ترجيح للظهور في صيغة Buy Box.

شبكة مراكز الوفاء

• Gebze (Kocaeli) — مركز الوفاء الرئيسي، ~150,000 م²، يخدم إسطنبول + مرمرة
• Çorlu (Tekirdağ) — أُضيف عام 2023، مُركّز على غرب تركيا + البلقان العابر للحدود
• Kemalpaşa (Izmir) — تغطية بحر إيجه، افتُتح عام 2024 لجنوب غرب تركيا
• Ankara (Polatlı) — مركز وسط الأناضول، مُحسَّن للتسليم في منطقة العاصمة

هيكل الرسوم

تُنشر تسعيرة HepsiLojistik كرسم وفاء لكل وحدة بالإضافة إلى تخزين شهري:

• رسم الوفاء لكل وحدة — عادةً ₺25–₺75 حسب نطاق الوزن والفئة
• التخزين الشهري — يُحتسب لكل م³ شهريًا، مُدرّج حسب السرعة (تدفع وحدات SKU طويلة الذيل أكثر)
• الشحن الوارد — يدفع البائع الشحن الوارد إلى مركز الوفاء
• معالجة المرتجعات — مشمولة في رسم الوفاء للمرتجعات المطابقة للسياسة

التقديم & الإعداد

HepsiLojistik ليست مفتوحة افتراضيًا. يتقدّم البائعون عبر HMS → Lojistik Hizmetleri → HepsiLojistik Başvuru، مع تقديم سجل مبيعات 6 أشهر وقائمة SKU مستهدفة. تُعطي Hepsiburada الأولوية للبائعين الذين يتجاوزون ~500 طلب شهريًا بأنماط طلب قابلة للتنبؤ؛ أما البائعون ذوو الحجم الأقل فيبقون عادةً على نموذج استلام HepsiJet المستقل.

8. تكامل الفاتورة الإلكترونية (e-Fatura) — GİB & ERP

الفاتورة الإلكترونية GİB إلزامية

تفرض GİB في تركيا (Gelir İdaresi Başkanlığı — إدارة الإيرادات) استخدام e-Fatura (فواتير XML منظّمة تُقدَّم إلى بوابة GİB) على جميع الشركات التي تتجاوز حد الدوران السنوي (حاليًا ~₺3 مليون، مُخفَّض لبائعي التجارة الإلكترونية بموجب تعديلات 2026). وأقل من الحد، تنطبق e-Arşiv Fatura — إلكترونية بالمثل، وأخف قليلًا في التوقيع. طلبات السوق غير معفاة: يتطلب كل طلب سوق B2C وB2B فاتورة إلكترونية تُصدر خلال 7 أيام من حدث الإرسال.

نقطة نهاية فواتير Hepsiburada

تعرض Hepsiburada نقطة نهاية مالية لرفع الفواتير — يدفع البائعون (أو مُكامِلو e-Fatura لديهم) معرّف GİB UUID والتصيير PDF للفاتورة الصادرة، الذي يظهر بعد ذلك للعميل عبر رابط «Faturayı İndir» القياسي على صفحة الطلب:

POST /finance/invoices
Host: integration.hepsiburada.com

{
  "orderId": "HB-72184",
  "invoiceNumber": "ZUN2026000087421",
  "invoiceUuid": "f8e7d6c5-1234-5678-9abc-def012345678",
  "invoiceDate": "2026-06-09",
  "pdfBase64": "JVBERi0xLjQKJ..."
}

مزوّدو ERP & e-Fatura المتوافقون

يُصدر معظم البائعين الأتراك الفاتورة الأساسية عبر نظام ERP / e-Fatura entegratör لديهم وينقلون النتيجة إلى Hepsiburada. توفّر Zunapro موصّلات أصلية لـ:

• Logo Tiger 3 / Logo Wings — أكثر أنظمة ERP انتشارًا في تركيا
• Mikro Yazılım — قوي في تجزئة الشركات الصغيرة والمتوسطة
• Netsis (شريك SAP) — للبائعين المؤسسيين
• Foriba، Uyumsoft، Digital Planet، izibiz — مُكامِلو GİB e-Fatura المتخصصون

طبقة KVKK

تخضع البيانات الشخصية للعملاء (PII) المتدفقة عبر مسار الفواتير لـ KVKK في تركيا (Kişisel Verilerin Korunması Kanunu — قانون حماية البيانات الشخصية)، وهو اللائحة المحلية المكافئة لـ GDPR التي تُنفّذها KVKK Kurumu (هيئة حماية البيانات). يُعد البائعون متحكّمين مشتركين في PII الخاصة بجانب الطلب ويجب أن يسجّلوا أنشطة المعالجة على VERBİS حيثما ينطبق ذلك.

9. الأخطاء الشائعة وحلولها

أبرز أخطاء الإنتاج

HTTP / الرمز	العرَض	السبب الجذري	الحل
401 Unauthorized	رُفضت جميع الطلبات	ترويسة User-Agent مفقودة أو مشوّهة	اضبط User-Agent: {MERCHANT_ID} - {AppName} صراحةً
403 Forbidden	نقطة نهاية محدّدة محجوبة	يفتقر مفتاح API إلى النطاق؛ التاجر غير معتمد للوحدة	أعد إصدار المفتاح في HMS بنطاقات كاملة، وتواصل مع دعم التجار
VALIDATION_ERROR	المنتج عالق في WAITING_FOR_APPROVAL	سمة فئة إلزامية مفقودة أو قيمة بحث غير صالحة	اجلب /categories/{id}/attributes، واملأ الحقول المطلوبة بقيم enum صالحة
BRAND_NOT_FOUND	رُفض استيراد المنتج	سلسلة العلامة التجارية لا تطابق سجل علامات HB بالضبط	استعلم عن /brands?name=...، استخدم المعرّف المُرجَع، واطلب إنشاء علامة إن كانت مفقودة
429 Too Many Requests	تم تقييد حركة الدفعات المفاجئة	تجاوزت ~30 طلب/ثانية على القوائم أو ~10/ثانية على الطلبات	نفّذ تراجعًا أُسيًا مع دعم ترويسة Retry-After
STOCK_UPDATE_DELAY	يعرض المتجر مخزونًا قديمًا لمدة 30–90 ثانية	تأخر انتشار ذاكرة التخزين المؤقت، وليس خطأً	قلّل المخزون استباقيًا عند خطر البيع الزائد؛ وسوِّ بعد التأخير
HEPSIJET_PICKUP_FAIL	أُنشئ الطرد لكن لم يتم استلام من الناقل	pickupAddressId خاطئ أو عنوان خارج تغطية HepsiJet	تحقق من عنوان الاستلام في HMS، وارجع إلى Yurtiçi/Aras للرموز البريدية المستثناة
INVOICE_UPLOAD_REJECTED	رفع e-Fatura يُرجع 400	تنسيق UUID غير صالح أو تلف base64 لملف PDF	تحقق من تنسيق UUID v4، وأعد ترميز PDF، وأعد المحاولة برقم فاتورة متكرر آمن

سير عمل التشخيص

عندما يبدأ تكامل Hepsiburada في التصرف بشكل غريب، فإن ترتيب التشخيص الذي تتبعه Zunapro هو:

1. تحقق من لوحة HMS → API Health لمعدلات الأخطاء على مستوى نقطة النهاية
2. تحقق من User-Agent وبيانات اعتماد Basic-auth باختبار curl سريع
3. افحص ترويسة X-Request-Id من استجابة فاشلة — يطلبها دعم التجار لدى Hepsiburada لتتبّع تذكرة
4. قارن مع سجل تغييرات developers.hepsiburada.com بحثًا عن تغييرات المخطط الأخيرة

10. عمولة Hepsiburada 2026 — من 8% إلى 22%

جدول عمولات Hepsiburada لعام 2026 مُدرَّج حسب الفئة، يُنشر ربع سنويًا في HMS ضمن Hesabım → Komisyon Oranları ومقسَّم إلى ثلاثة نطاقات عريضة بالإضافة إلى بضع فئات شاذة (الذهب، السيارات، الأجهزة المنزلية الكبيرة).

مقارنة العمولات 2026 — Hepsiburada مقابل Trendyol مقابل Amazon TR

السوق	الفئة المنخفضة	الفئة المتوسطة	الفئة المرتفعة	الاشتراك / أخرى
Hepsiburada	8% – 12%	12% – 17%	15% – 22%	حساب مجاني · HepsiAd اختياري · رسوم HepsiLojistik عند الاستخدام
Trendyol	9% – 13%	13% – 18%	16% – 24%	حساب مجاني · رسوم TFC عند الاستخدام · Trendyol Ads اختياري
Amazon TR	5% – 12%	12% – 17%	15% – 22%	Professional Seller ~₺99 / شهريًا · رسوم FBA عند الاستخدام
n11	6% – 10%	10% – 15%	13% – 18%	حساب مجاني · مستوى اشتراك n11 Pro اختياري
Çiçeksepeti	10% – 14%	14% – 18%	16% – 22%	حساب مجاني · تخصص في الزهور/الهدايا في نفس اليوم

قراءة الجدول: Hepsiburada على قدم المساواة تقريبًا مع Amazon TR وأرخص قليلًا من Trendyol عبر جميع النطاقات. عامل التمييز ليس العمولة بل اللوجستيات — يمنح الميل الأخير المملوك لـ HepsiJet شركة Hepsiburada ميزة هيكلية في وعود التسليم في المدن الكبرى، بينما تعوّض قاعدة مستخدمي Trendyol الأكبر رسومها الأعلى قليلًا.

الإطار القانوني التركي 2026 — ضريبة القيمة المضافة، e-Fatura، KVKK، ETBİS

معدلات ضريبة القيمة المضافة (KDV) 2026

تستخدم ضريبة القيمة المضافة في تركيا — KDV (Katma Değer Vergisi) — ثلاثة معدلات قانونية في 2026:

• معدل قياسي 20% — معظم السلع الاستهلاكية، الإلكترونيات، الأزياء، المنزل & المعيشة
• معدل مخفّض 10% — البقالة الأساسية، المنسوجات لبعض الفئات، الكتب، الضيافة
• معدل فائق التخفيض 1% — الأغذية الأساسية (الخبز، الحليب، البيض)، المدخلات الزراعية، بعض الطبية

يسجّل بائعو السوق للحصول على KDV عبر Vergi Dairesi (مكتب الضرائب) الإقليمي؛ ويمكن للبائعين العابرين للحدود استخدام نظام ضريبة القيمة المضافة الخاص الموسَّع مؤخرًا في تركيا للتجارة الإلكترونية بعد عام 2024.

e-Fatura & e-Arşiv — تفويض GİB

• e-Fatura — فواتير XML منظّمة تُقدَّم إلى GİB، إلزامية فوق حد الدوران السنوي ولجميع بائعي التجارة الإلكترونية بموجب تعديلات 2026
• e-Arşiv Fatura — إلكترونية بالمثل لكن أخف؛ لـ B2C دون حد e-Fatura
• نافذة إصدار 7 أيام — يتطلب كل طلب سوق فاتورة إلكترونية خلال 7 أيام من الإرسال
• e-İrsaliye، e-Müstahsil، e-Smm — مستندات مرافقة لتدفقات اللوجستيات والزراعة والعمل الحر

KVKK — المكافئ التركي لـ GDPR

ينظّم KVKK (Kişisel Verilerin Korunması Kanunu)، النافذ منذ 2016 والمُشدَّد عام 2024 بمواءمة مع GDPR، معالجة البيانات الشخصية. يُعد بائعو السوق متحكّمين مشتركين في PII الخاصة بجانب الطلب (الاسم، العنوان، الهاتف، IBAN حيثما كان ذا صلة) ويجب عليهم:

• التسجيل في VERBİS (Veri Sorumluları Sicil Bilgi Sistemi) إذا تجاوزوا الحدود
• الاحتفاظ بسياسة خصوصية مكتوبة (Aydınlatma Metni) متاحة للعملاء
• احترام حقوق أصحاب البيانات (الوصول، التصحيح، الحذف) خلال 30 يومًا
• الإبلاغ عن الاختراقات إلى KVKK Kurumu خلال 72 ساعة

ETBİS — سجل شركات التجارة الإلكترونية

ETBİS (Elektronik Ticaret Bilgi Sistemi)، الذي تديره وزارة التجارة (Ticaret Bakanlığı)، هو السجل الإلزامي لكل شركة تجارة إلكترونية تعمل في تركيا. التسجيل مجاني وعبر الإنترنت؛ ويجب عرض رقم ETBİS في ملفات بائعي السوق وفي تذييلات المتاجر الخاصة. يتحقق فحص KYC لدى Hepsiburada من ETBİS تلقائيًا أثناء الإعداد.

اللوجستيات & الشحن — HepsiJet أولًا، Yurtiçi/Aras احتياطيًا

الافتراضي: HepsiJet

HepsiJet هو الناقل الافتراضي لطلبات Hepsiburada والوحيد الذي يُطلق تلقائيًا شارتي «Yarın Kapında» / «Bugün Kapında». بالنسبة لمعظم البائعين في المدن الكبرى، يُعد توجيه 80–100% من الحجم عبر HepsiJet هو الخيار الصحيح.

ناقلو الطرف الثالث المتكاملون

تتكامل Hepsiburada أيضًا مع الناقلين الوطنيين الراسخين في تركيا، حيث تُولّد ملصقات الشحن عبر نقطة نهاية إنشاء الطرد نفسها بمجرد تغيير قيمة cargoCompany:

• Yurtiçi Kargo — أكثف تغطية ريفية، قوي في الرموز البريدية لشرق الأناضول التي يستثنيها HepsiJet
• Aras Kargo — اتفاقيات مستوى خدمة B2B تنافسية، شائع للأثاث والسلع الضخمة
• DHL Kargo — نوافذ مرنة في نفس اليوم على ممرات مختارة
• PTT Kargo — المشغّل البريدي الحكومي، وصول ريفي، اتفاقيات مستوى خدمة أبطأ
• UPS Türkiye / DHL — خطوط دولية عابرة للحدود

منطق التوجيه في Zunapro

يقيّم موجّه اللوجستيات لدى Zunapro كل طلب مقابل مصفوفة قابلة للتهيئة — الوزن، الرمز البريدي للوجهة، القيمة المعلَنة، فئة SKU — ويختار HepsiJet افتراضيًا، مع الرجوع إلى Yurtiçi للرموز البريدية المستثناة وAras للطرود التي تتجاوز 30 كجم. يُدفع الناقل المختار عبر نقطة نهاية الطرد نفسها لدى Hepsiburada، بحيث يرى العميل تجربة تتبع واحدة.

كيف تبدأ البيع على Hepsiburada — 2026 خطوة بخطوة

الإطلاق في 5 خطوات

1. سجّل في ETBİS & HMS — افتح سجل ETBİS الخاص بك عبر etbis.ticaret.gov.tr، ثم أكمل الإعداد على merchant.hepsiburada.com بـ vergi numarası وIBAN ونموذج التوقيع. يُنجز KYC خلال 1–3 أيام عمل.
2. أنشئ بيانات اعتماد API — Hesabım → Entegrasyon Bilgileri → API Anahtarı. خزّن اسم المستخدم/كلمة المرور في خزنتك؛ ودوّن Merchant ID لترويسات User-Agent.
3. اربط e-Fatura — اختر مُكامِل GİB الخاص بك (Logo، Mikro، Foriba، izibiz) وتأكد من أن نقطة نهاية رفع الفواتير لدى Hepsiburada قابلة للوصول. اختبر بطلب B2C واحد.
4. اختر حزمة اللوجستيات لديك — استلام HepsiJet مقابل Şubeye Bırak، بالإضافة إلى احتياطي Yurtiçi/Aras للرموز البريدية المستثناة. جهّز الملصقات ومواد التغليف مسبقًا.
5. اتصل عبر Zunapro (10 دقائق) — الصق بيانات اعتماد API في بطاقة Hepsiburada، وطابق كتالوجك الرئيسي، وفعّل ملصقات HepsiJet التلقائية وe-Fatura، وبدّل المفتاح مباشرةً.

تدفق الاتصال في Zunapro

1. سجّل الدخول إلى Zunapro وافتح وحدة تركيا
2. انقر «ربط Hepsiburada» — الصق اسم مستخدم API وكلمة المرور وMerchant ID
3. مطابقة الفئات التلقائية — يقترح تعلّم الآلة (ML) في Zunapro مطابقات فئة-الورقة لكل SKU رئيسي؛ أكّدها ببضع نقرات
4. فعّل ملصقات HepsiJet التلقائية + e-Fatura — مفتاح واحد لكل منهما
5. انطلق مباشرةً — تكتمل أول مزامنة قوائم لكتالوج من 1000 SKU في نحو 10 دقائق؛ وتُسجَّل webhooks تلقائيًا

الأسئلة الشائعة حول التكامل مع Hepsiburada 2026