تخطَّ إلى المحتوى
مطوّرو دكانالتوثيق
Englishتسجيل الدخول

ابنِ تطبيقاً خلال 15 دقيقة

من تسجيل التطبيق إلى أول Webhook موقّع على متجر تجريبي.

آخر تحديث 2 أيلول 2026قراءة 2 د
في هذه الصفحة

هذه الصفحة لمن يبني تطبيقاً يتكامل مع متاجر دكان. في نهايتها يكون لديك تطبيق مسجّل، ورمز وصول لمتجر تجريبي، واستدعاء ناجح لواجهة المنصّة، واشتراك Webhook استقبل أول حدث.

١. سجّل وأنشئ تطبيقك#

  1. سجّل الدخول إلى بوابة المطوّرين وفعّل حساب المطوّر لمؤسستك. يتطلب ذلك مالك المؤسسة وبريداً إلكترونياً موثقاً.
  2. من لوحة التحكم أنشئ تطبيقاً: اسم، ورابط إعادة توجيه دقيق واحد على الأقل (HTTPS فقط؛ يُسمح بـ localhost للتطوير)، والنطاقات التي يحتاجها التطبيق فعلاً، ومواضيع Webhooks التي سيشترك فيها.
  3. انسخ المفتاح السري للعميل فور ظهوره؛ لن يظهر مرة أخرى. لتدويره لاحقاً راجع دورة حياة التطبيق.

ملاحظة

اطلب أقل النطاقات الممكنة. يرى التاجر كل نطاق بجملة عربية واضحة في شاشة الموافقة، وتُقتطع النطاقات الفعلية دائماً على صلاحيات العضو المانح الحالية. الجدول الكامل في مرجع النطاقات.

٢. جهّز متجراً تجريبياً#

من صفحة «المتاجر التجريبية» أنشئ متجراً تجريبياً. يصلك ببيانات جاهزة: منتجات بمتغيرات، وطلبات بكل حالات دورة الحياة، ومدفوعات عند الاستلام مسجّلة في دفتر المدفوعات، وخصومات بكل الأنواع، وطلب بالدولار مع لقطة سعر الصرف. التفاصيل والحدود في المتاجر التجريبية.

٣. احصل على رمز وصول#

دكان تستخدم OAuth 2.1 مع PKCE، وتطبيقك عميل سرّي: يرسل المفتاح السري وكود التحقق code_verifier معاً. وجّه التاجر إلى رابط الموافقة:

HTTP
GET https://dukkan.one/apps/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://app.example.com/callback
  &scope=orders:read%20orders:write
  &state=RANDOM_STATE
  &code_challenge=S256_CHALLENGE
  &code_challenge_method=S256

بعد الموافقة يصلك code على رابط إعادة التوجيه مع state نفسه. بدّله برمز وصول:

Shell
curl -X POST https://dukkan.one/apps/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=PKCE_VERIFIER

الاستجابة:

token-response.jsonJSON
{
  "access_token": "dk_app_at_REDACTED_EXAMPLE_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dk_app_rt_REDACTED_EXAMPLE_TOKEN",
  "scope": "orders:read orders:write",
  "install_id": "8b2c1d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
  "store_id": "3065a1f2-0c4d-4e8b-b7a9-5d2f8c1e9a44",
  "store_slug": "sham-perfumes"
}
  • رمز الوصول dk_app_at_… صالح لساعة واحدة (expires_in: 3600).
  • رمز التحديث dk_app_rt_… يتدوّر مع كل استخدام، وإعادة استخدام رمز قديم تلغي كامل السلسلة.
  • كل رمز مربوط بمتجر واحد فقط؛ تثبيتان في متجرين يعنيان رمزين منفصلين.

التفاصيل الكاملة — منح التحديث، وشاشة الموافقة، وجدول الأخطاء — في التفويض.

٤. أول استدعاء#

Shell
curl "https://dukkan.one/platform-api/v1/orders?limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

تعيد القوائم { "data": [...], "next_cursor": "..." }؛ اطلب طلباً واحداً بمعرّفه لترى الجسم الكامل:

Shell
curl "https://dukkan.one/platform-api/v1/orders/ORDER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
order.jsonJSON
{
  "data": {
    "id": "6f1d2c3b-4a59-4e8f-9b70-2d1c3e4f5a6b",
    "order_number": "1042",
    "status": "placed",
    "payment_status": "unpaid",
    "source": "storefront",
    "line_pricing": "gross",
    "subtotal": {
      "amount_minor": 250000,
      "currency": "SYP",
      "decimals": 0
    },
    "discount": {
      "amount_minor": 0,
      "currency": "SYP",
      "decimals": 0
    },
    "shipping": {
      "amount_minor": 25000,
      "currency": "SYP",
      "decimals": 0
    },
    "tax": {
      "amount_minor": 0,
      "currency": "SYP",
      "decimals": 0
    },
    "total": {
      "amount_minor": 275000,
      "currency": "SYP",
      "decimals": 0
    },
    "paid": {
      "amount_minor": 0,
      "currency": "SYP",
      "decimals": 0
    },
    "refunded": {
      "amount_minor": 0,
      "currency": "SYP",
      "decimals": 0
    },
    "exchange_rate": null,
    "created_at": "2026-08-18T16:00:00.123Z",
    "updated_at": "2026-08-18T16:00:00.123Z",
    "items": [
      {
        "id": "a1b2c3d4-0001-4e8f-9b70-2d1c3e4f5a6b",
        "variant_id": "c0ffee00-0001-4e8f-9b70-2d1c3e4f5a6b",
        "name": "عطر العود الملكي — 50 مل",
        "quantity": 1,
        "unit_price": {
          "amount_minor": 250000,
          "currency": "SYP",
          "decimals": 0
        },
        "total": {
          "amount_minor": 250000,
          "currency": "SYP",
          "decimals": 0
        }
      }
    ],
    "fulfillments": [],
    "refunds": []
  }
}

لاحظ أن كل مبلغ يحمل decimals الخاص به، وأن الطلب بالليرة السورية بلا خانات عشرية (decimals: 0). تحمل كل استجابة الترويستين X-Request-Id وX-Dukkan-Api-Version، وتتطلب كل عملية كتابة ترويسة Idempotency-Key. الأعراف كلها في مرجع الواجهة البرمجية.

٥. اشترك في Webhooks#

سجّل نقطة استقبال واحدة لهذا التثبيت (HTTPS علني فقط). طلب PUT يستبدل قائمة المواضيع كاملة:

Shell
curl -X PUT https://dukkan.one/platform-api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_url":"https://app.example.com/hooks/dukkan","topics":["order.created","order.status_changed","order.paid"]}'
webhook-subscription-response.jsonJSON
{
  "data": {
    "id": "5ub5c41b-0001-4e8f-9b70-2d1c3e4f5a6b",
    "endpoint_url": "https://app.example.com/hooks/dukkan",
    "topics": [
      "order.created",
      "order.status_changed",
      "order.paid"
    ],
    "status": "active",
    "activated_at": "2026-08-18T15:58:00.000Z",
    "secret": "dk_whsec_REDACTED_SHOWN_ONCE"
  }
}

يظهر مفتاح التوقيع secret مرة واحدة فقط — عند الإنشاء أو عند rotate_secret: true — واحفظه فوراً.

٦. استقبل أول حدث#

أنشئ طلباً في متجرك التجريبي من واجهته (https://dukkan.one/stores/YOUR_SANDBOX_SLUG) بالدفع عند الاستلام، وراقب وصول order.created إلى نقطة الاستقبال. تحقّق من التوقيع قبل أي معالجة؛ أمثلة التحقق بلغات عدة في Webhooks.

الخطوة التالية#