إعداد المصادقة

يوفّر Brevo طريقتين للمصادقة بحسب حالة الاستخدام: المصادقة بمفتاح API للوصول القياسي إلى الواجهة، والمصادقة برمز MCP لعمليات تكامل الذكاء الاصطناعي. يغطي هذا الدليل الطريقتين.

المصادقة بمفتاح API

تُستخدم مفاتيح Brevo API للوصول القياسي عبر REST API إلى جميع خدمات Brevo.

أنشئ مفتاح API الخاص بك

1. سجّل الدخول إلى لوحة تحكم Brevo
2. انتقل إلى Settings → API Keys
3. اضغط Generate a New API Key
4. امنح مفتاحك اسمًا وصفيًا (مثل “My App Production”)
5. انسخ المفتاح واحفظه بأمان (لن تراه مرة أخرى!)

أفضل ممارسات أمان مفتاح API

✅ افعل

• خزّن المفاتيح بأمان باستخدام متغيرات البيئة
• استخدم مفاتيح مختلفة للتطوير وللإنتاج
• دوّر المفاتيح بانتظام (كل 90 يومًا مستحسن)
• قيّد صلاحيات المفتاح بما هو مطلوب فقط
• راقب استخدام المفتاح في لوحة التحكم

❌ لا تفعل

• لا تودع المفاتيح إطلاقًا في نظام التحكم بالإصدارات
• لا تكتب المفاتيح مباشرة داخل شيفرة تطبيقك
• لا تشارك المفاتيح عبر البريد الإلكتروني أو المحادثات
• لا تستخدم مفاتيح الإنتاج للاختبار

متغيرات البيئة

خزّن مفاتيح API كمتغيرات بيئة:

Linux/macOS (.bashrc أو .zshrc)

export BREVO_API_KEY="your_api_key_here"

Windows (موجّه الأوامر)

set BREVO_API_KEY=your_api_key_here

Node.js (ملف .env)

BREVO_API_KEY=your_api_key_here

// Load from environment
const apiKey = process.env.BREVO_API_KEY;

Python

import os

api_key = os.getenv('BREVO_API_KEY')

PHP

$apiKey = $_ENV['BREVO_API_KEY'];
// or
$apiKey = getenv('BREVO_API_KEY');

ترويسات المصادقة

ضمّن مفتاح API في ترويسات الطلب:

صيغة الترويسة القياسية

GET /v3/account HTTP/1.1
Host: api.brevo.com
Accept: application/json
api-key: your_api_key_here

مثال JavaScript

const headers = {
  'Accept': 'application/json',
  'api-key': process.env.BREVO_API_KEY
};

fetch('https://api.brevo.com/v3/account', { headers })
  .then(response => response.json())
  .then(data => console.log(data));

طلبات Python

import requests

headers = {
    'Accept': 'application/json',
    'api-key': os.getenv('BREVO_API_KEY')
}

response = requests.get('https://api.brevo.com/v3/account', headers=headers)

صلاحيات المفاتيح ونطاقاتها

يمكن أن تحمل مفاتيح API المختلفة صلاحيات مختلفة:

• قراءة فقط: طلبات GET فقط مسموح بها
• إرسال رسائل البريد: صلاحيات البريد الإلكتروني التعاملي
• إدارة جهات الاتصال: إنشاء جهات الاتصال وتحديثها وحذفها
• إدارة الحملات: إنشاء الحملات وإرسالها
• وصول كامل: جميع نقاط نهاية API

اختبار المصادقة لديك

استخدم نقطة النهاية هذه للتحقق من عمل المصادقة:

curl -X GET "https://api.brevo.com/v3/account" \
  -H "Accept: application/json" \
  -H "api-key: $BREVO_API_KEY"

استجابة النجاح (200 OK):

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe"
}

خطأ المصادقة (401 Unauthorized):

{
  "code": "unauthorized",
  "message": "Invalid API key provided"
}

تدوير المفاتيح

لتدوير مفتاح API الخاص بك:

1. أنشئ مفتاحًا جديدًا في لوحة التحكم
2. حدّث متغيرات البيئة بالمفتاح الجديد
3. انشر تطبيقك بالمفتاح الجديد
4. اختبر بدقة للتأكد من أن كل شيء يعمل
5. ألغِ المفتاح القديم بعد الاطمئنان إلى الجديد

مراقبة استخدام مفتاح API

تتبّع استخدام مفتاح API في لوحة تحكم Brevo:

• الطلبات في اليوم أو الشهر
• معدلات الأخطاء بحسب نقطة النهاية
• أنماط الاستخدام الجغرافية
• أوقات الذروة في الاستخدام

استراتيجية تعدد مفاتيح API

في التطبيقات الأكبر، فكّر في استخدام عدة مفاتيح API:

• الإنتاج: بيانات العملاء ورسائل البريد الحقيقية
• التجهيز: اختبار ما قبل الإنتاج
• التطوير: التطوير والاختبار المحلي
• المراقبة: فحوص السلامة والمقاييس
• الأطراف الثالثة: عمليات التكامل الخارجية

المصادقة برمز MCP

بروتوكول سياق النموذج من Brevo (MCP) هو إطار لتكامل الذكاء الاصطناعي يتيح لمساعدي الذكاء الاصطناعي التفاعل مع خدمات Brevo. يستخدم MCP طريقة مصادقة منفصلة عبر رموز MCP.

ما هو MCP؟

يوفّر MCP وصولًا موحّدًا للذكاء الاصطناعي إلى واجهات Brevo API عبر:

• النقل: HTTPS
• الرابط الأساسي: https://mcp.brevo.com/v1/
• صيغة الاستجابة: JSON
• المصادقة: رمز MCP (مختلف عن مفاتيح API)

أنشئ رمز MCP الخاص بك

1. سجّل الدخول إلى لوحة تحكم Brevo
2. انتقل إلى Settings → MCP Tokens (أو إعدادات الحساب)
3. أنشئ رمز MCP جديدًا
4. انسخ الرمز واحفظه بأمان

ملاحظة: MCP متاح حاليًا لمستخدمي الوصول المبكر فقط.

استخدام رموز MCP

تُستخدم رموز MCP تحديدًا لعمليات تكامل الذكاء الاصطناعي واتصالات Model Context Protocol:

export BREVO_MCP_TOKEN="your_mcp_token_here"

ضمّن رمز MCP في الطلبات الموجّهة إلى نقاط نهاية MCP:

GET /v1/account HTTP/1.1
Host: mcp.brevo.com
Accept: application/json
Authorization: Bearer your_mcp_token_here

MCP مقابل مفتاح API

أفضل ممارسات أمان MCP

• خزّن رموز MCP بمعزل عن مفاتيح API
• استخدم متغيرات البيئة لتخزين الرموز
• دوّر الرموز بانتظام
• لا تودع الرموز إطلاقًا في نظام التحكم بالإصدارات
• راقب استخدام MCP في لوحة التحكم

حل مشكلات المصادقة

مشكلات شائعة في مفتاح API

صيغة مفتاح API غير صالحة

• يجب أن يكون طول المفاتيح 64 محرفًا بالضبط
• تحقق من عدم وجود مسافات أو محارف زائدة

خطأ في الصلاحيات

• تأكد من أن مفتاحك يملك الصلاحيات المطلوبة
• تحقق مما إذا كان المفتاح نشطًا في لوحة التحكم

تحديد معدل الطلبات

• تُحتسب حالات فشل المصادقة ضمن حدود المعدل
• انتظر قبل إعادة المحاولة ببيانات اعتماد صحيحة

قيود جغرافية

• بعض الحسابات لديها قيود على عناوين IP
• تواصل مع الدعم إذا احتجت إلى إضافة عناوين IP إلى قائمة السماح

مشكلات شائعة في رمز MCP

MCP غير متاح

• تأكد من امتلاكك وصولًا مبكرًا إلى ميزات MCP
• تواصل مع دعم Brevo لطلب الوصول

رمز غير صالح

• تأكد من نسخ الرمز بشكل صحيح دون مسافات
• تحقق من أن الرمز لم تنتهِ صلاحيته ولم يُلغَ

رابط أساسي خاطئ

• تعمل رموز MCP مع mcp.brevo.com فقط
• لا تستخدم رموز MCP مع نقاط نهاية api.brevo.com

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

• تعرّف على حدود المعدل
• ثبّت SDK
• نفّذ أول استدعاء API