إنشاء مفتاح API وإدارته

Published: ١٦ يوليو ٢٠٢٦ · Last updated: ٢٨ أغسطس ٢٠٢٦ · By Marcus Biel

تمنح صفحة مفتاح API نظامًا خارجيًا وصولًا موثّقًا إلى نقاط نهاية Maildroppa API المدعومة في حسابك. يمكنك إنشاء مفتاح API واحد، ونسخ قيمته السرية الكاملة، وإعادة ضبطه بأمان عبر تدويره، أو حذفه عند عدم الحاجة إليه. ويمكن استخدام مفتاح الحساب نفسه في عمليات التكامل من جانب الخادم وفي مشغلات طلبات API في Maildroppa Automations.

يمثّل مفتاح API حسابك في Maildroppa. تعامل معه كما تتعامل مع كلمة مرور: إذ يمكن لأي شخص يحصل على المفتاح استدعاء نقاط نهاية API المتاحة له إلى أن تقوم بتدويره أو حذفه.

الغرض من مفتاح API

استخدم مفتاح API عندما يحتاج برنامج خارج Maildroppa إلى العمل مع Maildroppa من دون تسجيل دخول تفاعلي للمستخدم.

تشمل الأمثلة المعتادة ما يلي:

• مزامنة المشتركين مع CRM أو متجر أو نظام عضوية أو قاعدة بيانات داخلية.
• إنشاء المشتركين أو تحديثهم من تطبيق يعمل من جانب الخادم.
• قراءة العلامات والحقول وقيم الحقول والشرائح أو إدارتها عبر نقاط النهاية المدعومة.
• إرسال أحداث مخصّصة إلى مشغل طلب API في Automation.
• إرسال رسائل بريد إلكتروني معاملاتية عبر API.
• إدارة اشتراكات webhook المستندة إلى API.

مفتاح API مخصّص للاتصال من خادم إلى خادم. ولا يُخصّص للشفرة التي تعمل في متصفح الزائر أو على موقع عام أو في تطبيق جوّال أو في نموذج تسجيل مضمّن.

تحمل الصفحة حاليًا علامة “beta”. استخدم وثائق OpenAPI المرتبطة باعتبارها المصدر لنقاط النهاية وأجسام الطلبات والمعلمات ومخططات الاستجابة التي يدعمها API حاليًا.

فتح صفحة مفتاح API

افتح “Settings”، ثم وسّع “Developers”، وحدد “API key”.

يمكنك أيضًا فتح الصفحة مباشرةً على:

https://app.maildroppa.com/settings/developers/api-key

تتضمن الصفحة:

• لوحة مفتاح API تحمل شارة beta.
• رابط “View OpenAPI docs”.
• حالة فارغة وزر “Create API key” عند عدم وجود مفتاح.
• تمثيلًا مقنّعًا للمفتاح الحالي عند وجوده.
• زر “Copy” ينسخ المفتاح الكامل.
• إجراءَي “Rotate API key” و“Delete API key” لاستبدال المفتاح الحالي أو إزالته.

تسمح Maildroppa بمفتاح API واحد لكل حساب. ولا تنشئ الصفحة مفاتيح منفصلة للتطبيقات أو البيئات أو أعضاء الفريق الفرديين.

إنشاء مفتاح API

عندما تعرض الصفحة “No API key yet”، انقر على “Create API key”.

تنشئ Maildroppa المفتاح فورًا. ولا يظهر مربع حوار للتأكيد عند هذا الإنشاء الأول. أثناء تنفيذ الطلب، يتغير الزر إلى “Creating API key”، وتعطّل الصفحة مؤقتًا إجراءات المفاتيح الأخرى.

بعد إنشاء المفتاح:

• تختفي الحالة الفارغة.
• يظهر مفتاح مقنّع.
• تصبح إجراءات “Copy” و“Rotate API key” و“Delete API key” متاحة.
• تعرض Maildroppa رسالة نجاح “API key updated”.

إذا كان هناك مفتاح آخر موجود بالفعل للحساب، فلن تنشئ Maildroppa مفتاحًا ثانيًا. استخدم المفتاح الحالي أو دوّره.

فهم المفتاح المقنّع

لا تعرض الصفحة السر الكامل كنص عادي. بل تعرض الأحرف الخمسة الأولى متبوعة بخمس علامات نجمية، مثل:

a1b2c*****

هذا قناع مرئي فقط. ولا تمثّل علامات النجمة الطول الحقيقي للمفتاح، كما لا يمكن استخدام القيمة المقنّعة في طلب API.

انقر على “Copy” لكتابة المفتاح الحالي الكامل في الحافظة. بعد نجاح النسخ، يتغير الزر لفترة وجيزة إلى “Copied!”.

يبقى المفتاح مقنّعًا عند عودتك إلى الصفحة، لكن يستمر زر “Copy” في نسخ القيمة الحالية الكاملة. لذلك لا تحتاج إلى تدوير مفتاح صالح لمجرد أنك لم تحفظه أثناء إنشائه.

تخزين المفتاح بأمان

انقل المفتاح المنسوخ مباشرةً إلى مخزن الأسرار الذي يستخدمه التكامل.

تشمل المواقع المناسبة ما يلي:

• مدير أسرار مُدار.
• إعدادات بيئة محمية للخادم.
• سر نشر مشفّر.
• مدير كلمات مرور يُستخدم للاسترداد التشغيلي.

لا تخزّن المفتاح في:

• JavaScript من جانب المتصفح أو أي حزمة frontend أخرى قابلة للتنزيل.
• ملف شفرة مصدر عام أو خاص تم إيداعه في مستودع.
• عنوان URL أو معلمة استعلام.
• وثائق عامة أو لقطات شاشة أو رسائل دعم أو متتبعات مشكلات.
• سجلات تطبيقات مشتركة أو أحداث تحليلات أو تقارير أخطاء.
• جدول بيانات غير مشفّر أو محادثة عادية مع الفريق.

لا تضف المفتاح إلى مثال curl سيُنسخ إلى وثائق أو إلى سجل أوامر shell تتم مشاركته مع أشخاص آخرين. وفضّل استخدام متغير بيئة مثل MAILDROPPA_API_KEY.

استخدام مفتاح API

أرسل المفتاح الكامل في ترويسة طلب HTTP المسماة X-API-Key:

X-API-Key: your-complete-api-key

لا ترسله باعتباره رمز Bearer. تتوقع Maildroppa ترويسة X-API-Key، وليس Authorization: Bearer ....

تتوفر API الخاصة بالإنتاج ووثائق OpenAPI التفاعلية على:

https://api.maildroppa.com

انقر على “View OpenAPI docs” في صفحة مفتاح API لفتح الوثائق في علامة تبويب جديدة في المتصفح. حدد نقطة نهاية هناك لمراجعة طريقتها ومسارها ومعلماتها وجسم الطلب ونوع الاستجابة ورموز الحالة المحتملة.

مثال على طلب

يسترجع المثال التالي الصفحة الأولى من المشتركين. ويقرأ المفتاح من متغير بيئة بدلًا من وضع السر مباشرةً في الأمر:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

اضبط المتغير في البيئة الآمنة التي يعمل فيها التكامل. تعتمد الطريقة والمسار ومعلمات الاستعلام والجسم الدقيقة على نقطة النهاية. انسخ هذه التفاصيل من وثائق OpenAPI بدلًا من تخمينها من الإجراءات المتاحة في تطبيق Maildroppa.

الطلبات ذات الأجسام بتنسيق JSON

بالنسبة إلى طلب يرسل JSON، أضف أيضًا:

Content-Type: application/json

على سبيل المثال، تكون البنية الأساسية كما يلي:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

إن /example-endpoint وجسمه مجرد عناصر نائبة. استبدلهما بنقطة نهاية موثّقة ومخطط طلبها الموثّق.

ما الذي يمكن للمفتاح الوصول إليه

يعمل المفتاح فقط مع نقاط النهاية التي تدعم المصادقة باستخدام مفتاح API. ولا تصبح الصفحة أو الطلب المستخدم داخليًا بواسطة تطبيق Maildroppa جزءًا من API العامة للعملاء تلقائيًا.

تعرض وثائق OpenAPI واجهة API المدعومة للعملاء. وإذا لم يكن المسار موثّقًا للاستخدام مع مفتاح API، فلا تفترض أن المفتاح يمكنه الوصول إليه.

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

حدود المعدل

يوثّق عقد OpenAPI الحالي حدود مفاتيح API التالية:

• API العملاء الافتراضية: 300 طلب في الدقيقة و2,000 طلب في الساعة.
• Events API على /events: 100 طلب في الثانية مع سعة اندفاعية تبلغ 500 طلب.

تُطبَّق هذه الحدود على حساب Maildroppa، وليس بشكل مستقل على كل برنامج نصي يشارك مفتاحه. لذلك قد تستهلك عدة تكاملات الحصة نفسها.

عندما تعيد Maildroppa الاستجابة 429 Too Many Requests، أوقف إرسال الطلبات الجديدة والتزم بترويسة الاستجابة Retry-After عند وجودها. استخدم قائمة انتظار وتراجعًا مضبوطًا بدلًا من بدء عمليات إعادة محاولة متوازية كثيرة.

قد تتغير سياسات حدود المعدل أثناء وجود API في مرحلة beta. راجع المعلومات في أعلى وثائق OpenAPI قبل تصميم تكاملات ذات حجم طلبات كبير.

استخدام المفتاح لطلبات Automation API

يمكن أن تبدأ Automation عندما يرسل نظامك حدثًا مخصّصًا إلى Events API في Maildroppa.

عند إعداد مشغل “API request”، تستخدم Maildroppa مفتاح API نفسه للحساب المُدار في هذه الصفحة. ويمكن لإعداد المشغل إنشاء المفتاح عند عدم وجوده ونسخ طلب curl مُجهّز يحتوي على المفتاح الكامل.

ويترتب على ذلك أثران مهمان:

• يؤثر تدوير مفتاح الحساب أو حذفه أيضًا في الأنظمة التي ترسل أحداثًا مخصّصة إلى Automations.
• يحتوي مثال طلب Automation المنسوخ على السر في الحافظة، رغم أن المفتاح مقنّع على الشاشة.

قبل تدوير المفتاح أو حذفه، أدرج كل مشغل طلب API وكل مرسل أحداث خارجي في جرد تكاملاتك.

إعادة ضبط مفتاح API أو استبداله

استخدم “Rotate API key” عندما تحتاج إلى إعادة ضبط بيانات الاعتماد الحالية أو استبدالها. تنشئ Maildroppa مفتاحًا جديدًا وتبطل المفتاح السابق كجزء من الإجراء نفسه.

استخدم التدوير عندما:

• يُحتمل أن يكون المفتاح قد انكشف.
• لم يعد شخص أو موفّر يعرف المفتاح بحاجة إلى الوصول.
• تتطلب سياسة الأمان لديك استبدال بيانات الاعتماد دوريًا.
• تريد استبدال مفتاح مخزّن في موقع قديم أو غير آمن.

انقر على “Rotate API key” أسفل المفتاح المقنّع. تفتح Maildroppa مربع حوار تحذيريًا يوضح أن المفتاح الحالي لن يعود قابلًا للاستخدام.

انقر على “Rotate API key” في مربع الحوار للمتابعة، أو انقر على “Cancel” للاحتفاظ بالمفتاح الحالي.

لا توجد فترة سماح عند التدوير

بعد تأكيد التدوير، يتوقف المفتاح القديم عن العمل فورًا. ولا تُبقي Maildroppa المفتاحين القديم والجديد صالحين في الوقت نفسه.

وبما أن الحساب لا يملك سوى مفتاح واحد، يؤثر التدوير في كل خادم ومهمة مجدولة وتكامل وبرنامج نصي ومرسل أحداث Automation يستخدمه.

استخدم التسلسل التالي للتدوير المخطط له:

1. أدرج كل تكامل يستخدم المفتاح الحالي.
2. جهّز الوصول إلى إعدادات الأسرار وعملية النشر الخاصة بكل تكامل.
3. اختر فترة صيانة قصيرة إذا كان الوصول المتواصل إلى API مهمًا.
4. انقر على “Rotate API key”، ثم أكّد التحذير بالنقر على “Rotate API key” في مربع الحوار.
5. انقر على “Copy” لنسخ المفتاح الجديد الكامل.
6. استبدل السر في كل تكامل فورًا.
7. أعد تشغيل الخدمات التي تحمّل الأسرار عند بدء التشغيل فقط أو أعد نشرها.
8. أرسل طلبًا موثّقًا غير مؤثر للتحقق من كل تكامل.
9. تحقّق من وجود استجابات 401 Unauthorized من خدمة منسية لا تزال تستخدم المفتاح القديم.

إذا كان يُعتقد أن المفتاح الحالي قد اختُرق، فقم بتدويره فورًا وتقبّل الانقطاع القصير اللازم لتحديث الأنظمة الشرعية.

حذف مفتاح API

احذف المفتاح عندما يجب ألا يعود الحساب يقبل الطلبات المصادَق عليها باستخدام مفتاح API.

انقر على “Delete API key” أسفل المفتاح المقنّع. تفتح Maildroppa مربع حوار تحذيريًا يوضح أن المفتاح سيُزال نهائيًا من الحساب.

انقر على “Delete API key” في مربع الحوار لحذفه، أو انقر على “Cancel” للاحتفاظ به.

بعد الحذف:

• يتوقف المفتاح الحالي عن العمل فورًا.
• تعود الصفحة إلى حالة “No API key yet”.
• لا تعود تكاملات الخادم التي تستخدم المفتاح المحذوف قادرة على المصادقة.
• لا يعود مرسلو طلبات Automation API الذين يستخدمون ذلك المفتاح قادرين على تسليم الأحداث.

لا يؤدي حذف المفتاح إلى حذف المشتركين أو الحملات أو العلامات أو الحقول أو الشرائح أو Automations أو بيانات الحساب الأخرى. بل يزيل بيانات الاعتماد المستخدمة للوصول إلى نقاط نهاية API المدعومة.

يمكنك النقر على “Create API key” لاحقًا لإنشاء بيانات اعتماد جديدة. ولا تُستعاد القيمة المحذوفة. يجب تحديث كل تكامل قبل أن يتمكن من استخدام المفتاح الجديد.

إعادة الضبط أم الحذف: أيهما تختار؟

اختر “Rotate API key” عندما يجب أن يستمر الوصول إلى API باستخدام بيانات اعتماد جديدة.

اختر الحذف عندما يجب إيقاف الوصول إلى API بالكامل، على الأقل في الوقت الحالي.

يبطل كلا الإجراءين المفتاح الحالي فورًا. ينشئ التدوير البديل كجزء من الإجراء نفسه؛ أما الحذف فيترك الحساب من دون مفتاح.

توصيات الأمان

أبقِ استدعاءات API على خادمك

لا يستطيع المتصفح أو التطبيق الجوّال الاحتفاظ بسر مضمّن بشكل موثوق. إذ يمكن للمستخدم فحص التطبيق أو ترويسات الطلب أو خرائط المصدر أو حركة مرور الشبكة واستخراج المفتاح.

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

استخدم أقل قدر ممكن من التعرض

امنح المفتاح للأنظمة التي تحتاج إليه فقط. لا توزّعه على كل مطوّر ولا تلصقه في ملفات إعداد محلية متعددة.

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

احجب ترويسات الطلبات

اضبط عملاء HTTP والوكلاء العكسيين وأدوات المراقبة ومُبلّغي الأخطاء لحجب X-API-Key. قد يعمل الطلب بشكل صحيح، ومع ذلك يسرّب بيانات اعتماده عبر تسجيلات التصحيح.

أبقِ البيئات المنفصلة منفصلة

لا تعِد استخدام مفتاح الإنتاج في التطوير المحلي أو نماذج الشفرة أو لقطات الشاشة أو تجهيزات الاختبار. خزّن الأسرار الخاصة بكل بيئة في مخازن أسرار خاصة بتلك البيئة.

يشير رابط “View OpenAPI docs” تلقائيًا مستخدمي الإنتاج إلى وثائق API الخاصة بالإنتاج. تحقّق دائمًا من اسم المضيف قبل إرسال مفتاح حقيقي.

دوّر المفتاح بعد أي اشتباه في انكشافه

لا يثبت حذف رسالة أو إيداع في مستودع أو سطر سجل أو لقطة شاشة أن أحدًا لم ينسخ المفتاح. إذا انكشفت القيمة الكاملة، فقم بتدويرها.

معالجة أخطاء API

استخدم حالة HTTP وجسم الاستجابة الموثّق لتحديد الإجراء الذي ينبغي أن يتخذه التكامل.

تشمل الحالات الشائعة ما يلي:

• 400 Bad Request — لا يفي المسار أو المعلمة أو جسم JSON بعقد نقطة النهاية. قارن الطلب بمخطط OpenAPI.
• 401 Unauthorized — ترويسة X-API-Key مفقودة أو فارغة أو غير صالحة أو محذوفة أو تحتوي على قيمة قديمة بعد التدوير.
• 403 Forbidden — لا يُسمح للمفتاح المصادَق عليه باستخدام هذه العملية.
• 404 Not Found — المسار أو المورد المشار إليه غير موجود في هذا الحساب.
• 429 Too Many Requests — بلغ التكامل حدًا من حدود معدل API. أوقف الطلبات والتزم بترويسة Retry-After عند وجودها.
• 5xx — تعذّر على Maildroppa إكمال الطلب. أعد محاولة العمليات الآمنة باستخدام تراجع أُسّي محدود وتسجيل يستبعد مفتاح API.

لا تُعد محاولة كل فشل بشكل أعمى. صحّح استجابات 400 و401 و403 ومعظم استجابات 404 قبل إرسال الطلب نفسه مرة أخرى.

بالنسبة إلى الطلبات التي تُجري تغييرات، تحقّق من سلوك إعادة المحاولة وعدم قابلية التكرار لنقطة النهاية قبل تكرار الطلب تلقائيًا. فلا يثبت فشل الاتصال دائمًا أن Maildroppa لم تُجرِ أي تغيير.

استكشاف الأخطاء وإصلاحها

لا يزال “Create API key” ظاهرًا

لا يوجد حاليًا أي مفتاح في الحساب. انقر على الزر مرة واحدة وانتظر حتى يكتمل الطلب.

إذا فشل الإنشاء، فأعد تحميل الصفحة قبل المحاولة مرة أخرى. قد تكون صفحة أخرى أو إعداد Automation قد أنشأ بالفعل مفتاح الحساب.

يبدو المفتاح في الصفحة قصيرًا جدًا

تعرض الصفحة عمدًا الأحرف الخمسة الأولى فقط و*****. انقر على “Copy” لنسخ القيمة الكاملة. لا ترسل النص المقنّع في طلب.

لا يتغير “Copy” إلى “Copied!”

قد يكون المتصفح قد حظر الوصول إلى الحافظة. أبقِ الصفحة في علامة التبويب النشطة، واسمح بالوصول إلى الحافظة إذا طُلب منك ذلك، ثم انقر على “Copy” مرة أخرى.

لا تحاول إعادة تكوين المفتاح من النص المقنّع.

يعيد الطلب 401 Unauthorized

تحقّق من أن:

• اسم الترويسة هو بالضبط X-API-Key.
• تحتوي الترويسة على القيمة الكاملة، من دون علامات النجمة الظاهرة.
• التكامل لا يرسل Authorization: Bearer بدلًا من ذلك.
• لم تُضف مسافات بيضاء أو علامات اقتباس أو سطر جديد إلى السر.
• لم يقم أحد بتدوير مفتاح الحساب أو حذفه.
• أُعيد تشغيل الخدمة إذا كانت تقرأ متغيرات البيئة عند بدء التشغيل فقط.
• أُرسل الطلب إلى بيئة Maildroppa API الصحيحة.

يعمل أحد التكاملات، لكن توقف آخر بعد التدوير

من المحتمل أن التكامل الثاني لا يزال يستخدم المفتاح القديم. لا توجد فترة تداخل. حدّث سره وأعد تشغيل أي عملية تخزّن الإعدادات مؤقتًا.

تعمل صفحة OpenAPI، لكن تعيد نقطة نهاية ما 403

لا تدعم كل نقاط نهاية التطبيق المصادقة باستخدام مفتاح API. استخدم عملية موثّقة لواجهة API الخاصة بالعملاء، وتحقّق من متطلبات المصادقة الخاصة بها في صفحة OpenAPI.

تعيد الطلبات 429 Too Many Requests

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

قائمة التحقق للإعداد الموصى به

قبل وضع التكامل قيد الاستخدام المنتظم، تأكد من أن:

• المفتاح مخزّن فقط في إعدادات الأسرار من جانب الخادم.
• تستخدم الطلبات ترويسة X-API-Key.
• يستخدم التكامل https://api.maildroppa.com في الإنتاج.
• تتبع كل طريقة ومسار ومعلمة وجسم JSON وثائق OpenAPI.
• تحجب السجلات وتقارير الأخطاء المفتاح.
• تم إعداد مهلات وإعادات محاولة محدودة.
• تتم مراقبة أخطاء 401 و403 و429 وأخطاء الخادم.
• تم تسجيل مالك التكامل.
• أُدرج كل نظام يشارك مفتاح الحساب في خطة التدوير.
• يمكن تدوير المفتاح المخترق بسرعة.

صفحة مفتاح API صغيرة عمدًا، لكن إجراءاتها تؤثر في كل تكامل API متصل بالحساب. أنشئ المفتاح عند الحاجة إليه فقط، واحتفظ به على خوادم موثوقة، وخطّط للتدوير باعتباره تغييرًا في بيانات اعتماد على مستوى الحساب.