On this page

مفاتيح API

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

ما هي مفاتيح API؟

مفاتيح API هي معرّفات فريدة تقوم بمصادقة تطبيقك عند إجراء طلبات إلى Brevo API. كل مفتاح هو سلسلة من 64 حرفًا تعمل كمعرّف وككلمة مرور في آن واحد.

Example API key: xkeysib-a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456-Ab1Cd2Ef3Gh4

إنشاء مفاتيح API

دليل خطوة بخطوة

  1. تسجيل الدخول إلى Brevo: الوصول إلى لوحة تحكم Brevo
  2. الانتقال إلى الإعدادات: انقر على ملفك الشخصي ← الإعدادات
  3. الذهاب إلى مفاتيح API: اختر “API Keys” من القائمة اليسرى
  4. إنشاء مفتاح جديد: انقر على “Generate a New API Key”
  5. تسمية المفتاح: أعطه اسمًا وصفيًا (مثل “Production App”، “Development Testing”)
  6. تعيين الأذونات: اختر مستوى الوصول المناسب
  7. الإنشاء: انقر على “Generate” وانسخ المفتاح فورًا

اصطلاحات تسمية مفاتيح API

استخدم أسماء وصفية تساعدك على تحديد الغرض من المفتاح:

  • production-web-app
  • staging-environment
  • mobile-app-ios
  • webhook-listener
  • data-sync-service

أنواع مفاتيح API والأذونات

مفاتيح الوصول الكامل 

Permissions: All API endpoints
Use cases: Complete application integration
Risk level: High - protect carefully

مفاتيح القراءة فقط 

Permissions: GET requests only
Use cases: Analytics, reporting, dashboards
Risk level: Low - limited access

مفاتيح الإرسال فقط 

Permissions: Transactional email sending
Use cases: Application notifications, receipts
Risk level: Medium - can send emails

مفاتيح إدارة جهات الاتصال 

Permissions: Contact CRUD operations
Use cases: CRM integrations, form submissions
Risk level: Medium - data modification

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

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

قم بتضمين مفتاح API الخاص بك في ترويسة api-key:

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

أمثلة الكود

JavaScript/Node.js 

const brevo = require('@brevo/api');


const apiInstance = new brevo.AccountApi();
apiInstance.setApiKey(brevo.AccountApiApiKeys.apiKey, process.env.BREVO_API_KEY);


// Make authenticated request
apiInstance.getAccount()
  .then(data => console.log('Account info:', data))
  .catch(error => console.error('Error:', error));

Python 

import sib_api_v3_sdk
from sib_api_v3_sdk.rest import ApiException


# Configure API key
configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'


# Create API instance
api_instance = sib_api_v3_sdk.AccountApi(sib_api_v3_sdk.ApiClient(configuration))


try:
    # Get account info
    api_response = api_instance.get_account()
    print(api_response)
except ApiException as e:
    print("Exception when calling AccountApi->get_account: %s\n" % e)

PHP 

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure API key
$config = SendinBlue\Client\Configuration::getDefaultConfiguration()->setApiKey('api-key', 'YOUR_API_KEY');


// Create API instance
$apiInstance = new SendinBlue\Client\Api\AccountApi(
    new GuzzleHttp\Client(),
    $config
);


try {
    $result = $apiInstance->getAccount();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling AccountApi->getAccount: ', $e->getMessage(), PHP_EOL;
}
?>

Ruby 

require 'sib-api-v3-sdk'


# Configure API key
SibApiV3Sdk.configure do |config|
  config.api_key['api-key'] = 'YOUR_API_KEY'
end


# Create API instance
api_instance = SibApiV3Sdk::AccountApi.new


begin
  # Get account info
  result = api_instance.get_account
  puts result
rescue SibApiV3Sdk::ApiError => e
  puts "Exception when calling AccountApi->get_account: #{e}"
end

أمان مفاتيح API

التخزين الآمن

متغيرات البيئة (الطريقة الموصى بها)

Terminal window
# .env file
BREVO_API_KEY=xkeysib-your-api-key-here


# Usage in code
const apiKey = process.env.BREVO_API_KEY;

مديرو أسرار السحابة

  • AWS Secrets Manager
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault

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

  1. لا تقم أبدًا بتضمين المفاتيح في الكود مباشرة

    // Bad - hardcoded
    const apiKey = "xkeysib-a1b2c3d4...";
    

    // Good - environment variable
    const apiKey = process.env.BREVO_API_KEY;

  2. استخدم مفاتيح مختلفة لكل بيئة

    Production:  BREVO_API_KEY_PROD
    Staging:     BREVO_API_KEY_STAGING
    Development: BREVO_API_KEY_DEV

  3. قم بتدوير المفاتيح بانتظام

    • عيّن تذكيرات تقويمية للتدوير الربع سنوي
    • استخدم أدوات الأتمتة لتدوير المفاتيح
    • احتفظ بخطة تراجع جاهزة

  4. راقب استخدام المفاتيح

    • أعد تنبيهات للنشاط غير المعتاد
    • راجع سجلات استخدام المفاتيح شهريًا
    • تتبع أنماط الوصول الجغرافي

إدارة المفاتيح

مراقبة المفاتيح النشطة

راقب مفاتيحك النشطة في لوحة التحكم:

Key Name: production-web-app
Created: 2024-01-15
Last Used: 2024-01-20 14:30 UTC
Requests Today: 1,247
Status: Active

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

  1. إنشاء مفتاح جديد: إنشاء مفتاح بديل
  2. تحديث التكوين: النشر بالمفتاح الجديد
  3. المراقبة: التأكد من عمل المفتاح الجديد بشكل صحيح
  4. فترة السماح: إبقاء المفتاح القديم نشطًا لمدة 24-48 ساعة
  5. إلغاء المفتاح القديم: حذف المفتاح السابق

إلغاء المفتاح في حالات الطوارئ

إذا تم اختراق مفتاح:

  1. الإلغاء الفوري: حذف المفتاح من لوحة التحكم
  2. إنشاء بديل: إنشاء مفتاح جديد فورًا
  3. تحديث التطبيقات: النشر بالمفتاح الجديد في أسرع وقت
  4. مراقبة النشاط: التحقق من الاستخدام غير المصرح به
  5. تقرير الحادث: توثيق حادثة الأمان

تحديد معدل الطلبات ومفاتيح API

لكل مفتاح API حدود معدل طلبات فردية:

  • الخطة المجانية: 300 طلب/يوم
  • خطة المبتدئين: 20,000 طلب/يوم
  • خطة الأعمال: 50,000 طلب/يوم
  • خطة المؤسسات: حدود مخصصة

ترويسات تحديد معدل الطلبات 

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

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

async function makeApiCall() {
  try {
    const response = await fetch(url, { headers });


    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = resetTime - Math.floor(Date.now() / 1000);


      console.log(`Rate limited. Waiting ${waitTime} seconds`);
      await new Promise(resolve => setTimeout(resolve, waitTime * 1000));


      // Retry the request
      return makeApiCall();
    }


    return response.json();
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

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

رسائل الخطأ الشائعة

مفتاح API غير صالح (401)

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

أذونات غير كافية (403)

{
  "code": "permission_denied",
  "message": "API key does not have required permissions"
}

تجاوز حد معدل الطلبات (429)

{
  "code": "too_many_requests",
  "message": "Rate limit exceeded for API key"
}

قائمة التحقق لتصحيح الأخطاء

  • المفتاح بالتنسيق الصحيح (64 حرفًا)
  • لا توجد مسافات إضافية أو أحرف مخفية
  • المفتاح لديه الأذونات المطلوبة
  • المفتاح نشط (غير ملغي)
  • ضمن حدود معدل الطلبات
  • استخدام نقطة نهاية API الصحيحة
  • الترويسات بالتنسيق الصحيح

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

مساعد AI

مرحباً! اسألني أي شيء عن الوثائق.

ابدأ مجانًا مع Brevo