لماذا لا تجد توكن Admin API في Shopify؟ وكيف تطلبه

العميل بعتلك يقول «ابعتلي الـ Admin API token عشان أربط أداة الشحن»، وأنت فتحت لوحة Shopify ومش لاقي حاجة تنسخها. اطمّن، مفيش مشكلة في صلاحياتك: ده السلوك الطبيعي دلوقتي. المقال ده لأصحاب متاجر Shopify والمستقلين اللي بيبنوها في مصر والخليج، والكلام فيه عام لأن التغيير نفسه واحد في كل الأسواق.

بصراحة: هذا المقال قراءة في توثيق Shopify الرسمي وفي شرح منشور مبني عليه، ولم نطبّق الخطوات على متجر حي. أسماء الأزرار والمسارات منقولة كما يذكرها التوثيق بتاريخ أكتوبر 2026، وقد تتغير.

ما الذي تغيّر في يناير 2026؟

منذ 1 يناير 2026 لم يعد ممكنًا إنشاء تطبيق مخصص (Custom App) قديم من لوحة الإدارة. أي تطبيق مخصص جديد يُنشأ الآن من Dev Dashboard (لوحة المطورين الجديدة في Shopify).

الفرق العملي واحد: تطبيقات Dev Dashboard لا تعرض رمز الوصول (Access Token) في لوحة الإدارة إطلاقًا. يقول التوثيق الرسمي صراحة إنك «لن ترى رمزًا في لوحة Shopify»، بل يطلبه الكود بنفسه عند الحاجة.

أما التطبيقات المخصصة التي أُنشئت قبل هذا التاريخ فما زالت تعمل حتى أكتوبر 2026، وتظهر تحت اسم Legacy custom apps.

ماذا يعني ذلك لك؟

• صاحب متجر: لن تستطيع إرسال «التوكن» لأداة أو مطوّر كما كنت تفعل. ستنشئ التطبيق وتعطي المطوّر معرّفًا وسرًّا، وهو يتولى الباقي.
• مستقل أو وكالة: طلب الرمز صار جزءًا من الكود، لا خطوة في دليل التسليم. ومدة صلاحيته 24 ساعة، فالتكامل الذي يعمل طوال الوقت يجب أن يجدد الرمز تلقائيًا.
• أداة خارجية تطلب منك نسخ رمز: Shopify تقول إن هذه الأدوات تعتمد على طريقة المصادقة القديمة، ونصيحتها أن تراسل مزوّد الأداة ليحدّث تكامله إلى OAuth.

ثلاث قيم مختلفة: لا تخلط بينها

يعطيك تطبيق Dev Dashboard ثلاث سلاسل نصية، واحدة فقط منها هي الرمز الذي يدخل في طلبات الـ API. معظم أخطاء الربط تبدأ من الخلط بينها.

تنبيه: إذا أرسلت client_id أو client_secret مباشرة إلى GraphQL Admin API ستحصل على الخطأ «Invalid API key or access token». يجب استبدالهما برمز أولًا.

الخطوات من البداية للنهاية

الخطوات الأربع الأولى يقوم بها صاحب المتجر أو موظف لديه الصلاحية المناسبة، والأخيرتان على المطوّر.

1. أنشئ التطبيق

اتبع المسار Settings ثم Apps ثم Develop apps، واختر Build apps in Dev Dashboard ثم Create app.

2. أصدر نسخة من التطبيق

حدّد App URL وإصدار Webhooks API ونطاقات الصلاحية (Access Scopes) التي يحتاجها التطبيق، ثم اضغط Release. لا يمكن تثبيت التطبيق قبل أن تكون له نسخة واحدة على الأقل.

3. ثبّت التطبيق على المتجر

التثبيت يتم على متجر داخل المؤسسة (Organization) نفسها، وسنعود لهذا الشرط بعد قليل لأنه أكثر ما يُوقع الوكالات.

4. انسخ Client ID وClient secret

تجدهما في إعدادات التطبيق داخل Dev Dashboard. احفظهما في ملف .env خارج نظام التحكم بالإصدارات، ولا تضعهما في كود الواجهة أبدًا.

5. اطلب رمز الوصول

يوضح توثيق منح بيانات اعتماد العميل (Client Credentials Grant) أن الطلب يكون POST إلى نقطة الرمز في متجرك بترميز application/x-www-form-urlencoded، مع ثلاثة حقول: grant_type وclient_id وclient_secret. هذا مثال بصيغة curl مبني على الحقول التي يذكرها التوثيق:

curl -X POST "https://your-store.myshopify.com/admin/oauth/access_token" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  --data-urlencode "grant_type=client_credentials" 
  --data-urlencode "client_id=$SHOPIFY_CLIENT_ID" 
  --data-urlencode "client_secret=$SHOPIFY_CLIENT_SECRET"

والرد كما يعرضه التوثيق:

{
  "access_token": "f85632530bf277ec9ac6f649fc327f17",
  "scope": "read_products",
  "expires_in": 86399
}

قيمة expires_in هي 86399 ثانية، أي 24 ساعة تقريبًا. والحقل scope يعيد فقط الصلاحيات التي اخترتها في نسخة التطبيق؛ طلب الرمز نفسه لا يطلب صلاحيات.

6. استخدم الرمز وجدّده

أرسل الرمز في الترويسة X-Shopify-Access-Token مع كل طلب إلى Admin API. خزّنه مؤقتًا واطلب رمزًا جديدًا قبل انتهاء الـ 24 ساعة، بدل طلب رمز مع كل استدعاء.

ملاحظة: إضافة صلاحية جديدة لاحقًا تعني إصدار نسخة جديدة من التطبيق. وتنبّه Shopify إلى أن التحديث لا يُطبَّق تلقائيًا على المتاجر المثبّت عليها التطبيق، بل يجب الموافقة على الصلاحيات الجديدة يدويًا من لوحة الإدارة.

الشرط الذي يُوقع الوكالات: المؤسسة الواحدة

تعمل هذه الطريقة فقط عندما يكون التطبيق والمتجر في المؤسسة نفسها داخل Shopify. لا يمكن لتطبيق Dev Dashboard مخصص الوصول إلى متجر خارج مؤسستك، ومنه متجر العميل.

وحساب المتعاون (Collaborator) لا يحل المشكلة، لأن المتعاونين لا يملكون صلاحيات على مستوى المؤسسة ولا يستطيعون دخول Dev Dashboard. الحل العملي: شخص من داخل مؤسسة العميل ينشئ التطبيق ويثبّته، ثم يعطيك المعرّف والسر.

إذا كنت تبني أداة واحدة لعدة عملاء، فهذا مسار مختلف: يذكر التوثيق التوزيع المخصص (Custom distribution) مع طريقة منح أخرى، وهو قرار تصميم منفصل عن هذا المقال.

أخطاء شائعة وما تعنيه

الصلاحيات المطلوبة: صاحب المتجر يملك تلقائيًا صلاحية إنشاء التطبيقات المخصصة وإدارتها. أما الموظف فيحتاج صلاحية App development ثم Develop.

عندك تطبيق مخصص قديم؟ لا تحذفه

إذا أُنشئ تطبيقك قبل 1 يناير 2026 فرمزه يظهر بعد التثبيت من Settings ثم Apps ثم Legacy custom apps، لكن مرة واحدة فقط. احفظه فورًا في مدير كلمات مرور أو خزنة أسرار.

لا يمكن تدوير مفتاح أو سر هذه التطبيقات القديمة. للحصول على رمز جديد عليك إلغاء تثبيت التطبيق وإعادة تثبيته، وهذا يلغي تسجيل الويب هوك (Webhook) وخدمات الشحن وتكاملات المخزون، فتعيد تسجيلها كلها بالرمز الجديد.

تحذير: لا تحذف التطبيق القديم نفسه. لن تستطيع إنشاء تطبيق مخصص قديم بديل له، وأي تطبيق جديد سيكون من Dev Dashboard بقواعده الجديدة.

القرار: ماذا تفعل الآن؟

• عندك تطبيق قديم يعمل: اتركه، واحفظ رمزه في مكان آمن، وخطّط للانتقال إلى Dev Dashboard في وقت هادئ لا في منتصف موسم تخفيضات.
• تبني تكاملًا جديدًا لمتجرك: أنشئه من Dev Dashboard، واكتب تجديد الرمز في الكود من اليوم الأول.
• تبني لعميل: اطلب من العميل أن ينشئ التطبيق من حسابه، أو ادرس التوزيع المخصص إذا كانت الأداة لعدة متاجر.

الأسئلة الشائعة

س: أين أجد Admin API access token في Shopify؟
ج: في التطبيقات المخصصة الجديدة لن تجده في لوحة الإدارة؛ يُطلب برمجيًا باستخدام Client ID وClient secret. في التطبيقات القديمة يظهر مرة واحدة تحت Legacy custom apps.

س: هل يمكن إنشاء تطبيق مخصص قديم بعد يناير 2026؟
ج: لا. التطبيقات المخصصة الجديدة تُنشأ من Dev Dashboard فقط، والقديمة الموجودة تستمر في العمل.

س: كم تبلغ صلاحية التوكن الجديد؟
ج: 24 ساعة. لذلك يجب أن يطلب التكامل رمزًا جديدًا قبل انتهاء الصلاحية.

س: هل أستطيع ربط تطبيق من حسابي بمتجر العميل؟
ج: ليس بهذه الطريقة. منح بيانات اعتماد العميل يعمل فقط داخل المؤسسة نفسها، ومتجر العميل يحتاج توزيعًا مخصصًا وطريقة منح مختلفة.

س: ما الفرق بين API key وClient ID؟
ج: هما الاسم نفسه لقيمة واحدة؛ بعض الأدوات والتوثيقات القديمة تسمي Client ID «API key» وClient secret «API secret».

الخلاصة

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

مراجع إضافية: Client credentials grant — Shopify.dev، Get API access tokens for Dev Dashboard apps — Shopify.dev

مرجع المقال (بالإنجليزية): Shopify custom apps in 2026: why there is no Admin API token to copy, and how to request one
المقال ده مش ترجمة حرفية: متكيّف للقارئ العربي ومضاف عليه سياق ووردبريس وElementor وJetEngine.