واجهة Brevo API: دليل عملي للمطورين

دليل Brevo API للمطورين: المصادقة، عنوان القاعدة، جهات الاتصال، البريد المعاملاتي، الحملات، كائنات CRM، الـ webhooks، حدود المعدل، والقيود الواقعية.

Tajo Team

تم التحديث ١٩ أغسطس ٢٠٢٦

0 زيارات · 7 أيام

Brevo API

واجهة Brevo API?

تعرض Brevo واجهة REST واحدة تمتد عبر المراسلة المعاملاتية، والحملات التسويقية، وبيانات جهات الاتصال، وسجلات CRM. الوصول بأول طلب إلى استجابة 201 يستغرق دقيقتين تقريبًا. أما بناء تكامل إنتاجي لا يفقد البيانات بصمت فيستغرق وقتًا أطول بكثير، لأن عدة قيود من أهم ما يجب أخذه في الحسبان إما غير موثّقة أو تناقض ما تقوله الواجهة عن نفسها.

يغطي هذا الدليل الجانبين معًا: نقاط النهاية وحزم SDK والمصادقة التي تحتاجها في اليوم الأول، وحدود المنصّة التي يجب أن تصمّم حولها قبل الإطلاق.

ما الذي تغطيه واجهة Brevo API

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

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

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

المعاملاتي مقابل التسويقي

تختلف العائلتان في سلوكهما بما يكفي لجعل الخلط بينهما أكثر أخطاء التصميم شيوعًا.

	معاملاتي	تسويقي
نقطة النهاية الأساسية	`POST /v3/smtp/email`	`POST /v3/emailCampaigns`
تحديد المستلمين	مستلمون صريحون في الطلب	`listIds` أو `segmentIds`
المُشغِّل	تطبيقك، في الوقت الفعلي	مجدول أو يُرسَل عند الطلب
شكل الحجم المعتاد	مستمر، رسالة واحدة في كل مرة	متقطع، إرسالة واحدة كبيرة
موقف حدود المعدل	مرتفع جدًا، 1,000 طلب في الثانية على الخطط القياسية	منخفض، نقاط نهاية الحملات تقع ضمن السقف العام

إذا كنت لا تزال تقرّر ما إذا كانت Brevo هي المنصّة المناسبة أصلًا، فإن نظرة عامة على المنصّة تغطي هذا الجانب.

المصادقة وإدارة المفاتيح

تستخدم Brevo مفتاح API بسيطًا داخل ترويسة مخصّصة. اسم الترويسة هو api-key، وليس Authorization، ولا توجد بادئة Bearer. هذه النقطة تُربك تقريبًا كل من استخدم واجهة مراسلة أخرى قبلها.

curl https://api.brevo.com/v3/account \
  -H "api-key: $BREVO_API_KEY"

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

بعض القواعد العملية:

أصدر مفتاحًا منفصلًا لكل بيئة نشر ولكل خدمة. إبطال مفتاح مسرَّب يجب ألا يوقف ثلاثة أنظمة غير مرتبطة.
مفاتيح API القياسية تشمل الحساب كله. تعامل مع أي مفتاح على أنه وصول كامل إلى جهات الاتصال والإرسال وبيانات CRM.
تدعم Brevo أيضًا OAuth 2.0 للتطبيقات التي تعمل نيابة عن حسابات Brevo أخرى، وهو موصوف إلى جانب تدفق المفاتيح في مخططات المصادقة.
خادم MCP الذي تستخدمه مساعدات AI يأخذ رمزًا منفصلًا، وهو يستخدم فعلًا ترويسة bearer. يُنشأ ذلك الرمز في شاشة API keys نفسها لكنه غير قابل للتبادل مع مفتاح REST.

عنوان القاعدة والإصدارات وأول عملية كتابة

عنوان القاعدة هو https://api.brevo.com/v3/. رقم الإصدار في المسار وليس في ترويسة، و v3 هو الجيل الحالي. كل مسار في هذا الدليل نسبي لذلك العنوان.

أول عملية كتابة أكثر إفادة من أول عملية قراءة، لأنها تختبر الأجزاء التي عادة ما تكون مضبوطة بشكل خاطئ في الحساب (المرسِلون الموثَّقون تحديدًا):

curl -X POST https://api.brevo.com/v3/smtp/email \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": { "name": "Ops", "email": "[email protected]" },
    "to": [{ "email": "[email protected]", "name": "Dev" }],
    "subject": "First transactional send",
    "htmlContent": "<html><body><p>It works.</p></body></html>",
    "tags": ["smoke-test"]
  }'

الإرسال الناجح يعيد 201 مع messageId. أما الإرسال المجدول فيعيد 202.

نقاط النهاية التي ستستخدمها فعلًا

جهات الاتصال

POST /v3/contacts ينشئ جهة اتصال. يأخذ الجسم email، وخريطة attributes للحقول المخصّصة، و listIds، و ext_id لمفتاحك الخارجي، إضافة إلى العَلَمَين الأهم عمليًا: updateEnabled الذي يحوّل الاستدعاء إلى upsert، و getId الذي يجعل الاستجابة تعيد معرّف جهة الاتصال.

تمر القراءات عبر GET /v3/contacts، الذي يرقّم النتائج باستخدام limit (الافتراضي 50، والحد الأقصى 1000) و offset، ويدعم modifiedSince و createdSince بتوقيت UTC. عمليات المزامنة التزايدية يجب أن تعتمد على modifiedSince بدل المرور على القائمة كاملة. لاحظ أن المعامل filter يدعم عامل المساواة فقط، لذا فإن أي شيء أكثر تعبيرًا مكانه شريحة.

للتحميل الجماعي، يقبل POST /v3/contacts/import القيم fileUrl أو fileBody أو jsonBody، ويستهدف listIds، ويعمل بشكل غير متزامن مُعيدًا processId. توثّق Brevo حدًا أقصى للجسم يبلغ 10 ميجابايت وتنصح بالبقاء قرب 8 ميجابايت لأن التحليل يضخّم الحمولة. مرّر notifyUrl كي تعرف النتيجة بدل الاستعلام المتكرر.

البريد المعاملاتي

POST /v3/smtp/email هو حصان العمل. إلى جانب sender و to و subject و htmlContent، الحقول التي تستحق المعرفة هي:

templateId مع params، وهو يستبدل المحتوى المضمَّن بقالب Brevo واستبدالات متغيراته. حدود معاملات النسخة الواحدة 100 كيلوبايت، والمجموع التراكمي 1000 كيلوبايت.
messageVersions، الذي يرسل نسخًا مخصّصة في استدعاء واحد، بحد أقصى 99 مستلمًا لكل نسخة.
tags، ويجب أن تضبطه دائمًا. تعود الوسوم مع أحداث الـ webhook، وهي الطريقة الرخيصة الوحيدة لربط حدث تسليم بمسار الشيفرة الذي أنتجه.
scheduledAt مع batchId، للإرسالات المستقبلية التي قد ترغب في إلغائها كمجموعة.
headers، بصيغة Title-Case، لترويسات SMTP المخصّصة.

يقبل الطلب الواحد 2,000 مستلم كحد أقصى. وللفرق بين هذه النقطة وإرسال الحملات، يقدّم دليل البريد المعاملاتي وجهة نظر استراتيجية المراسلة.

حملات البريد الإلكتروني

يتطلب POST /v3/emailCampaigns الحقلين name و sender، إضافة إلى مصدر محتوى واحد بالضبط: htmlContent (10 أحرف كحد أدنى، وأقل من 1 ميجابايت)، أو htmlUrl، أو templateId. يوضع الجمهور في recipients بصيغة listIds أو segmentIds، ويستخدم scheduledAt صيغة YYYY-MM-DDTHH:mm:ss.SSSZ بتوقيت UTC. وتغطي المسارات المرافقة الإرسال الفوري، وإرسال اختبار، وتحديث الحالة، وسحب تقرير الحملة.

الشركات والصفقات والكائنات

يمتلك نظام CRM في Brevo مسارَي كتابة متداخلين، والاختيار الصحيح بينهما مهم.

مسارات CRM هي POST /v3/companies و PATCH /v3/companies/{id} و DELETE /v3/companies/{id}، والمجموعة المكافئة للصفقات. هذه المسارات متزامنة. يعيد PATCH الحالة 204 بمجرد تطبيق التغيير.

أما واجهة الكائنات فهي المسار الجماعي: POST /v3/objects/{object_type}/batch/upsert يأخذ حتى 1000 سجل و 1 ميجابايت لكل طلب، وحتى 500 سمة لكل سجل، وحتى 10 سجلات ارتباط لكل نوع كائن في السجل الواحد. يعيد 202 مع processId، أي مقبول لا مطبَّق.

curl -X POST https://api.brevo.com/v3/objects/company/batch/upsert \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "identifiers": { "id": 12345 },
        "attributes": { "domain": "acme.example", "industry": "retail" }
      }
    ]
  }'

يغطي دليل Brevo CRM نموذج الكائنات من زاوية المشغّل.

حزم SDK الرسمية

تحافظ Brevo على عملاء برمجيين ضمن منظمة getbrevo على GitHub:

اللغة	المستودع
Node.js	`github.com/getbrevo/brevo-node`
Python	`github.com/getbrevo/brevo-python`
PHP	`github.com/getbrevo/brevo-php`
Java	`github.com/getbrevo/brevo-java`
C#	`github.com/getbrevo/brevo-csharp`
Go	`github.com/getbrevo/brevo-go`
Ruby	`github.com/getbrevo/brevo-ruby`

يُثبَّت عميل Node باسم @getbrevo/brevo:

npm install @getbrevo/brevo

import { BrevoClient } from "@getbrevo/brevo";

const brevo = new BrevoClient({ apiKey: process.env.BREVO_API_KEY });

const result = await brevo.transactionalEmails.sendTransacEmail({
  subject: "Order confirmed",
  htmlContent: "<html><body><p>Thanks for your order.</p></body></html>",
  sender: { name: "Acme", email: "[email protected]" },
  to: [{ email: "[email protected]", name: "Customer" }],
  tags: ["order-confirmation"],
});

console.log("Message ID:", result.messageId);

يُثبَّت عميل Python عبر pip install brevo-python. وإذا كنت تفضّل ألا تحمل اعتمادية SDK من أجل نقطتَي نهاية فقط، فإن سطح HTTP الخام صغير بما يكفي لاستدعائه مباشرة، وهذا يعزلك أيضًا عن تقلّبات إصدارات SDK:

import os
import requests

BASE = "https://api.brevo.com/v3"
HEADERS = {
    "api-key": os.environ["BREVO_API_KEY"],
    "Content-Type": "application/json",
}

def upsert_contact(email, attributes, list_ids):
    response = requests.post(
        f"{BASE}/contacts",
        headers=HEADERS,
        json={
            "email": email,
            "attributes": attributes,
            "listIds": list_ids,
            "updateEnabled": True,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response

يوجد أيضًا خادم MCP على https://mcp.brevo.com/v1/brevo/mcp لمساعدات AI، تتم المصادقة عليه برمز bearer يُنشأ في شاشة الإعدادات نفسها. وهو مفيد للاستكشاف وأسئلة الحساب، لا لمسارات البيانات الإنتاجية.

الـ webhooks

الـ webhooks هي وسيلتك لمعرفة ما حدث بعد الإرسال. ينشئ POST /v3/webhooks واحدًا، مع url و events و type، واختياريًا channel (email أو sms)، و batched، وترويسات headers مخصّصة، وكائن auth.

هناك ثلاثة أنواع من الـ webhooks بمفردات أحداث مختلفة:

معاملاتي: sent، request، delivered، hardBounce، softBounce، blocked، spam، invalid، deferred، click، opened، uniqueOpened، unsubscribed.
تسويقي: spam، opened، click، hardBounce، softBounce، unsubscribed، listAddition، delivered، contactUpdated، contactDeleted.
وارد: inboundEmailProcessed و reply، وهما يتطلبان إضافة domain.

curl -X POST https://api.brevo.com/v3/webhooks \
  -H "api-key: $BREVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example/hooks/brevo",
    "type": "transactional",
    "events": ["delivered", "hardBounce", "spam", "unsubscribed"],
    "description": "Deliverability signals"
  }'

ثلاثة أمور يجب ضبطها جيدًا. أولًا، لا يستطيع الحساب الاحتفاظ بأكثر من 40 webhook عبر جميع الأنواع، لذا وجّه حسب الحدث داخل معالجك بدل تسجيل نقطة نهاية لكل حدث. ثانيًا، استخدم العَلَم batched عندما تتوقع حجمًا كبيرًا، لأن طلبًا واحدًا يحمل أحداثًا كثيرة أرخص في المعالجة بكثير من طلبات كثيرة. ثالثًا، احمِ المستقبِل: تنشر Brevo نطاقات عناوين الإرسال الخاصة بها، وتقييد نقطة نهايتك على تلك النطاقات هو الأسلوب الموثَّق. أضف سرًا مشتركًا خاصًا بك عبر الحقل headers كطبقة ثانية.

يجب أن تكون المعالِجات متكافئة التنفيذ. اعتبر معرّف الرسالة مع نوع الحدث مع الطابع الزمني مفتاحًا لإزالة التكرار.

حدود المعدل ومعالجة الأخطاء

حدود المعدل في Brevo محدَّدة لكل نقطة نهاية ولكل مستوى خطّة، والفارق بين نقاط النهاية هائل.

نقطة النهاية	القياسية	Professional و Enterprise
`POST /v3/smtp/email`	1,000 طلب في الثانية	2,000 طلب في الثانية
`POST /v3/transactionalSMS/send`	150 طلبًا في الثانية	200 طلب في الثانية
`/v3/contacts/...`	10 في الثانية، 36,000 في الساعة	20 في الثانية، 72,000 في الساعة
`POST /v3/events`	10 في الثانية، 36,000 في الساعة	أعلى في Enterprise
`GET /v3/smtp/emails`	2 في الثانية، 7,200 في الساعة	3 في الثانية، 10,800 في الساعة
كل ما عدا ذلك	100 في الساعة	200 في الساعة

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

كل استجابة تحمل x-sib-ratelimit-limit و x-sib-ratelimit-remaining و x-sib-ratelimit-reset. اقرأها عند النجاح، لا عند الفشل فقط. تجاوز الحد يعيد 429، والاستجابة الصحيحة هي الانتظار للمدة الواردة في ترويسة إعادة الضبط ثم تطبيق تراجع أسّي مع تشويش عشوائي.

async function callBrevo(path, init, attempt = 0) {
  const response = await fetch(`https://api.brevo.com/v3${path}`, {
    ...init,
    headers: { "api-key": process.env.BREVO_API_KEY, "Content-Type": "application/json", ...init.headers },
  });

  if (response.status === 429 && attempt < 5) {
    const reset = Number(response.headers.get("x-sib-ratelimit-reset") || 1);
    const backoff = Math.pow(2, attempt) * 250 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, reset * 1000 + backoff));
    return callBrevo(path, init, attempt + 1);
  }

  return response;
}

أعد المحاولة مع 429 و 5xx. لا تعد المحاولة أبدًا مع 400 أو 409 بشكل أعمى، لأن كليهما يعني عادة أن الطلب خاطئ لا أنه مبكر، و 409 تحديدًا يحتاج إلى إجراء مختلف لا إلى تكرار.

الاختبار دون إرسال بريد

أضف الترويسة X-Sib-Sandbox بالقيمة drop إلى طلب إرسال معاملاتي. تتحقق Brevo من صحة الطلب، وتعيد 201 مع messageId، ولا تسلّم شيئًا، ولا تكتب أي سجل بريد.

curl -X POST https://api.brevo.com/v3/smtp/email \
  -H "api-key: $BREVO_API_KEY" \
  -H "X-Sib-Sandbox: drop" \
  -H "Content-Type: application/json" \
  -d '{ "sender": { "email": "[email protected]" }, "to": [{ "email": "[email protected]" }], "subject": "Sandbox", "htmlContent": "<p>hi</p>" }'

افهم ما يثبته هذا وما لا يثبته. وضع الاختبار المعزول يتحقق من صيغة الطلب فقط. وهو لا يقول شيئًا عن مصادقة المرسِل، أو عرض القالب، أو قابلية التسليم. احتفظ بحساب Brevo منفصل لاختبار تكامل أي شيء يمس جهات الاتصال أو بيانات CRM، لأن الوضع المعزول يغطي الإرسال لا بقية الواجهة.

القيود التي تشكّل تصميم تكاملك

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

الشركات تتطلب نطاقًا، وشركة واحدة فقط لكل نطاق

يُبلِّغ GET /v3/crm/attributes/companies عن كل سمة بأنها غير مطلوبة، ومرجع إنشاء الشركة يذكر name وحده كإلزامي. عمليًا، فإن POST /v3/companies بدون سمة domain غير فارغة يعيد 400 برسالة عن سمات افتراضية إلزامية مفقودة. والسلسلة الفارغة تفشل تمامًا كما لو حذفتها.

والأسوأ أن تفرّد النطاق مفروض. شركة ثانية على نطاق مستخدم بالفعل تعيد 409. وبالنسبة إلى تجارة B2B هذا قيد بنيوي: الشركات التابعة التي تتشارك نطاق بريد مشترٍ واحد لا يمكن أن توجد جميعًا كشركات منفصلة في Brevo. كما أن مزامنة جهة اتصال وحدها كافية لجعل شركة تظهر على نطاق بريد تلك الجهة، فقد يصطدم إنشاؤك بشركة لم ينشئها أحد صراحة. المعالج الصحيح يتبنّى الشركة الموجودة عند 409 بدل الفشل أو إعادة المحاولة.

السمات غير المعلَنة تُهمَل بصمت

هذا أخطر سلوك في المنصّة، وتوثّقه Brevo بوضوح: إذا ظهرت سمة في الطلب ولم تكن معرَّفة مسبقًا في مخطط الكائن، فلا يحدث شيء. لا خطأ، ولا إنشاء سمة، ولا تحذير.

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

مرشّحات السمات تُقبَل وتُتجاهَل

GET /v3/companies?filters[attributes.domain]=... يعيد 200 ويتجاهل المرشّح. مرشّحان مختلفان تمامًا يعيدان السجلات نفسها. لا توجد طريقة عاملة للبحث عن شركة بحسب سمة عبر ذلك المسار.

وبالاقتران مع أن القائمة غير المرشّحة تنتهي مهلتها بخطأ 504 على الحسابات الكبيرة عند أي حجم صفحة، يمكن أن تكون شركة موجودة غير قابلة للعثور عليها فعليًا عبر المسار الموثَّق. الحل البديل هو مسح GET /v3/objects/company/records مع sort=desc، وهو سريع ومرقَّم ويعيد السمات، مع تحديده بعدد معقول من الصفحات. والشركة التي أطلقت 409 للتو تكون غالبًا قد أُنشئت قبل لحظات، لذا فإن المسح من الأحدث يجدها بسرعة.

مليون سجل لكل نوع كائن، ولا حذف جماعي

يعيد POST /v3/objects/{type}/batch/upsert الحالة 400 بمجرد أن يحتوي نوع الكائن على مليون سجل. وهو يمنع التحديثات كما يمنع الإنشاء: مخاطبة سجل موجود بمعرّفه الرقمي تفشل بالطريقة نفسها. مسار الكتابة على الكائنات يُغلق بالكامل دفعة واحدة.

والعودة إلى ما دون السقف بطيئة، لأن POST /v3/objects/{type}/batch/delete يعيد 403 لأنواع كائنات Brevo القياسية مثل company. المسار الوحيد هو DELETE /v3/companies/{id}، سجل واحد لكل استدعاء بنحو 156 مللي ثانية. تنظيف 124,000 سجل بهذه الطريقة استغرق ساعات مع 20 عاملًا متوازيًا. راقب عدد السجلات وفق جدول بدل اكتشاف السقف عبر مزامنة فاشلة، ووجّه التحديثات كثيفة الحجم عبر PATCH /v3/companies/{id} الذي لا يخضع لهذا القيد.

`ext_id` هو معرّف Brevo، لا معرّفك

في سجلات الكائنات، يحمل identifiers.ext_id معرّف شركة CRM الخاص بـ Brevo نفسها، وهو نصّ بأسلوب Mongo. وليس مفتاحًا خارجيًا حرًا. إسناد upsert إلى ext_id مضبوطًا على معرّف منصّتك يُنشئ نسخًا مكررة بدل المطابقة. معرّفك الخارجي مكانه سمة معلَنة خاصة به.

عمليات upsert على الكائنات غير متزامنة، وكتابات CRM متزامنة

يعيد batch/upsert الحالة 202 مع processId، ثم يطبّق لاحقًا. المعرّف غير الموجود يفشل بشكل غير متزامن ومع ذلك يعيد 202 إلى المستدعي. أما PATCH /v3/companies/{id} فيعيد 204 ويُطبَّق بشكل متزامن. إذا أبلغت مزامنتك عن نجاح، فالمسار المتزامن وحده يستحق تلك الكلمة دون قراءة تحقق لاحقة.

قائمة تحقق موجزة للتكامل

مفاتيح API منفصلة لكل خدمة ولكل بيئة، مع تدويرها عند تغيّر الموظفين.
كل عمليات الكتابة تمر عبر عميل واحد يقرأ ترويسات حدود المعدل ويتراجع عند 429.
مخطط السمات يُتحقق منه عند الإقلاع، وترفض المزامنة العمل إذا كانت سماتها مفقودة.
409 عند إنشاء شركة تعني التبنّي، لا إعادة المحاولة.
المسارات الجماعية تستخدم واجهة الكائنات للإنتاجية، ومسارات CRM لكل ما يجب تأكيده.
الـ webhooks متكافئة التنفيذ، ومجمّعة، ومقيَّدة بعناوين IP، وتحمل ترويسة سرّ مشترك.
المزامنات التزايدية لجهات الاتصال تستخدم modifiedSince، لا المرور على القائمة كاملة.

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

أهم النقاط

الواجهة سطح REST واحد على https://api.brevo.com/v3/، تتم المصادقة عليه بترويسة api-key لا برمز bearer.
حدود المعدل متفاوتة بشدة: الإرسال غير مقنَّن عمليًا، بينما تتشارك معظم نقاط النهاية الأخرى 100 طلب في الساعة على الخطط القياسية.
تتوفر حزم SDK رسمية لسبع لغات، لكن سطح HTTP بسيط بما يكفي لاستدعائه مباشرة عندما تحتاج نقاط نهاية قليلة فقط.
الوضع المعزول يتحقق من صيغة الطلب فقط، لذا احتفظ بحساب منفصل لاختبار أي شيء يتجاوز الإرسال.
استجابة 2xx لا تثبت أن الكتابة طُبِّقت. السمات غير المعلَنة تُهمَل بصمت، وعمليات upsert على الكائنات غير متزامنة.
صمّم حول القيود الثابتة: شركة واحدة لكل نطاق، ومليون سجل لكل نوع كائن، ولا حذف جماعي للكائنات القياسية، ومرشّحات سمات لا تفعل شيئًا بصمت.

الأسئلة المتكررة

ما هو عنوان القاعدة لواجهة Brevo API؟

كل استدعاءات REST في Brevo تذهب إلى https://api.brevo.com/v3/. رقم الإصدار جزء من المسار، و v3 هو الجيل الحالي، لذا فإن نقطة نهاية مثل الإرسال المعاملاتي تكون بالمسار الكامل https://api.brevo.com/v3/smtp/email.

كيف تتم المصادقة مع واجهة Brevo API؟

أرسل مفتاحك في ترويسة HTTP اسمها api-key. لا تستخدم Brevo ترويسة Authorization أو Bearer لمفاتيح API القياسية. تُنشَأ المفاتيح ضمن إعدادات الحساب، ثم SMTP and API، ثم API keys، وتُعرض القيمة مرة واحدة فقط.

ما هي حدود المعدل في واجهة Brevo API؟

الحدود محدَّدة لكل نقطة نهاية ولكل مستوى خطّة. في الحسابات القياسية تسمح نقطة نهاية الإرسال المعاملاتي بـ 1,000 طلب في الثانية، وتسمح نقاط نهاية جهات الاتصال بـ 10 في الثانية، أما بقية نقاط النهاية فمحدودة بـ 100 طلب في الساعة. خطّتا Professional و Enterprise تحصلان على مستويات أعلى. تجاوز الحد يعيد 429.

هل لدى Brevo حزم SDK رسمية؟

نعم. تنشر Brevo عملاء برمجيين للغات Node.js و Python و PHP و Java و C# و Go و Ruby ضمن منظمة getbrevo على GitHub. حزمة Node هي @getbrevo/brevo على npm، وحزمة Python هي brevo-python على PyPI.

كيف أختبر واجهة Brevo API دون إرسال بريد حقيقي؟

أضف الترويسة X-Sib-Sandbox بالقيمة drop إلى طلب إرسال معاملاتي. تتحقق Brevo من صحة الطلب، وتعيد 201 مع messageId، ولا ترسل شيئًا، ولا تكتب أي سجل بريد. هذا يفحص صيغة الطلب فقط، لا قابلية التسليم.

ما أحداث الـ webhook التي تدعمها Brevo؟

تغطي الـ webhooks المعاملاتية الأحداث sent و request و delivered و hardBounce و softBounce و blocked و spam و invalid و deferred و click و opened و uniqueOpened و unsubscribed. وتضيف الـ webhooks التسويقية listAddition و contactUpdated و contactDeleted. أما الواردة فتغطي inboundEmailProcessed و reply. يمكن للحساب الواحد أن يحتفظ بـ 40 webhook كحد أقصى.

هل يمكنني إنشاء شركتين بالنطاق نفسه في Brevo؟

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

لماذا أعادت عملية الكتابة عبر Brevo API نجاحًا دون أن تغيّر شيئًا؟

عمليات الكتابة على الكائنات و CRM تتجاهل بصمت أي سمة غير معرَّفة في مخطط الكائن. توثّق Brevo هذا السلوك صراحة: لا يُرفع أي خطأ ولا تُنشأ أي سمة. اقرأ المخطط أولًا وتحقق من نتيجة الكتابة بدل الوثوق بحالة 2xx.

هل يوجد حذف جماعي في واجهة Brevo API؟

ليس لأنواع كائنات Brevo القياسية مثل company. مسار الحذف الجماعي يعيد 403 لها، لذا يجري التنظيف بسجل واحد لكل استدعاء عبر DELETE /v3/companies/{id}. خطّط للتنظيف الجماعي بالساعات، لا بالدقائق.

شارك هذا المقال:

العودة إلى جميع المقالات

business-tools