كيفية استخدام API تطبيق Make (Integromat)؟

الملخص

يمكّن واجهة برمجة تطبيقات Make (المعروفة سابقًا باسم Integromat) المطورين من أتمتة سير العمل، وإدارة السيناريوهات، وتنفيذ عمليات التكامل برمجيًا. تستخدم مصادقة OAuth 2.0 ومفتاح API، ونقاط نهاية RESTful للسيناريوهات، وعمليات التنفيذ، وWebhooks، والفرق، مع حدود معدل تتراوح من 60 إلى 600 طلب في الدقيقة اعتمادًا على الخطة. يغطي هذا الدليل إعداد المصادقة، وإدارة السيناريوهات، ومشغلات Webhook، ومراقبة التنفيذ، واستراتيجيات أتمتة الإنتاج.

مقدمة

تعالج Make (Integromat) أكثر من 2 مليار عملية شهريًا لأكثر من مليون مستخدم في أكثر من 100 دولة. بالنسبة للمطورين الذين يقومون ببناء أدوات الأتمتة، أو إدارة سير عمل العملاء، أو التكامل مع أكثر من 1000 تطبيق، فإن التكامل مع Make API ليس اختياريًا - إنه ضروري للأتمتة القابلة للتوسع.

الواقع هو التالي: الوكالات التي تدير 50+ عملية أتمتة للعملاء تخسر 15-25 ساعة أسبوعيًا على التحديثات اليدوية للسيناريوهات، ومراقبة التنفيذ، وتقارير العملاء. يتيح التكامل القوي مع Make API أتمتة نشر السيناريوهات، وتتبع التنفيذ، ومعالجة الأخطاء، والتقارير ذات العلامة البيضاء.

يرشدك هذا الدليل خلال عملية التكامل الكاملة مع Make API. ستتعلم مصادقة OAuth 2.0 ومفتاح API، وإدارة السيناريوهات، ومشغلات Webhook، ومراقبة التنفيذ، وإدارة الفريق، واستراتيجيات النشر في الإنتاج. بحلول النهاية، سيكون لديك تكامل Make جاهز للإنتاج.

ما هو Make API؟

يوفر Make واجهة برمجة تطبيقات RESTful لإدارة سير عمل الأتمتة برمجيًا. يتعامل API مع:

• إنشاء السيناريوهات وتحديثها وحذفها
• تنفيذ السيناريوهات (التشغيل اليدوي)
• سجل التنفيذ والمراقبة
• إدارة الـ Webhook
• إدارة الفريق والمستخدمين
• إدارة الاتصال والتطبيقات
• إعدادات المؤسسة ومساحة العمل

الميزات الرئيسية

خطط Make والوصول إلى API

نظرة عامة على بنية API

يستخدم Make بنية API RESTful:

https://api.make.com/api/v2/

إصدارات API

البدء: إعداد المصادقة

الخطوة 1: إنشاء حساب Make

قبل الوصول إلى API:

1. زر Make.com
2. سجل للحصول على حساب
3. انتقل إلى الإعدادات > إعدادات المطور
4. أنشئ بيانات اعتماد API

الخطوة 2: اختيار طريقة المصادقة

يدعم Make طريقتين للمصادقة:

الخطوة 3: الحصول على مفتاح API (الطريقة الأبسط)

أنشئ مفتاح API للاستخدام الداخلي:

1. انتقل إلى الإعدادات > إعدادات المطور
2. انقر على إنشاء مفتاح API
3. انسخ المفتاح وخزنه بأمان

# ملف .env
MAKE_API_KEY="your_api_key_here"
MAKE_ORGANIZATION_ID="your_org_id"

الخطوة 4: إعداد OAuth 2.0 (للتطبيقات متعددة المستأجرين)

قم بتكوين OAuth لتكاملات العميل:

1. انتقل إلى الإعدادات > إعدادات المطور > تطبيقات OAuth
2. انقر على إنشاء تطبيق OAuth
3. قم بتكوين URI لإعادة التوجيه
4. احصل على بيانات اعتماد العميل

const MAKE_CLIENT_ID = process.env.MAKE_CLIENT_ID;
const MAKE_CLIENT_SECRET = process.env.MAKE_CLIENT_SECRET;
const MAKE_REDIRECT_URI = process.env.MAKE_REDIRECT_URI;

// بناء عنوان URL للتفويض
const getAuthUrl = (state) => {
  const params = new URLSearchParams({
    client_id: MAKE_CLIENT_ID,
    redirect_uri: MAKE_REDIRECT_URI,
    scope: 'read write execute',
    state: state,
    response_type: 'code'
  });

  return `https://www.make.com/oauth/authorize?${params.toString()}`;
};

الخطوة 5: تبادل الكود مقابل رمز الوصول

معالجة رد نداء OAuth:

const exchangeCodeForToken = async (code) => {
  const response = await fetch('https://www.make.com/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: MAKE_CLIENT_ID,
      client_secret: MAKE_CLIENT_SECRET,
      redirect_uri: MAKE_REDIRECT_URI,
      code: code
    })
  });

  const data = await response.json();

  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresIn: data.expires_in
  };
};

// معالجة رد النداء
app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;

  try {
    const tokens = await exchangeCodeForToken(code);

    // تخزين الرموز بأمان
    await db.integrations.create({
      userId: req.session.userId,
      accessToken: tokens.accessToken,
      refreshToken: tokens.refreshToken,
      tokenExpiry: Date.now() + (tokens.expiresIn * 1000)
    });

    res.redirect('/success');
  } catch (error) {
    console.error('خطأ في OAuth:', error);
    res.status(500).send('فشل المصادقة');
  }
});

الخطوة 6: إجراء استدعاءات API مصادق عليها

إنشاء عميل API قابل لإعادة الاستخدام:

const MAKE_BASE_URL = 'https://api.make.com/api/v2';

const makeRequest = async (endpoint, options = {}) => {
  const apiKey = options.useOAuth ? await getOAuthToken() : process.env.MAKE_API_KEY;

  const response = await fetch(`${MAKE_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Token ${apiKey}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`خطأ في Make API: ${error.message}`);
  }

  return response.json();
};

// الاستخدام
const scenarios = await makeRequest('/scenarios');
console.log(`تم العثور على ${scenarios.data.length} سيناريو`);

إدارة السيناريوهات

سرد السيناريوهات

جلب جميع السيناريوهات:

const listScenarios = async (filters = {}) => {
  const params = new URLSearchParams({
    limit: filters.limit || 50,
    offset: filters.offset || 0
  });

  if (filters.folder) {
    params.append('folder', filters.folder);
  }

  const response = await makeRequest(`/scenarios?${params.toString()}`);
  return response;
};

// الاستخدام
const scenarios = await listScenarios({ limit: 100 });
scenarios.data.forEach(scenario => {
  console.log(`${scenario.name} - ${scenario.active ? 'نشط' : 'متوقف مؤقتًا'}`);
  console.log(`  آخر تشغيل: ${scenario.lastRunDate || 'لم يتم تشغيله مطلقًا'}`);
});

الحصول على تفاصيل السيناريو

جلب سيناريو واحد:

const getScenario = async (scenarioId) => {
  const response = await makeRequest(`/scenarios/${scenarioId}`);
  return response;
};

// الاستخدام
const scenario = await getScenario('12345');
console.log(`الاسم: ${scenario.name}`);
console.log(`الوحدات: ${scenario.modules.length}`);
console.log(`الجدول الزمني: ${scenario.schedule?.cronExpression || 'يدوي'}`);

إنشاء سيناريو

إنشاء سيناريو جديد:

const createScenario = async (scenarioData) => {
  const scenario = {
    name: scenarioData.name,
    blueprint: scenarioData.blueprint, // مخطط JSON للسيناريو
    active: scenarioData.active || false,
    priority: scenarioData.priority || 1,
    maxErrors: scenarioData.maxErrors || 3,
    autoCommit: scenarioData.autoCommit || true,
    description: scenarioData.description || ''
  };

  const response = await makeRequest('/scenarios', {
    method: 'POST',
    body: JSON.stringify(scenario)
  });

  return response;
};

// الاستخدام - إنشاء من المخطط
const newScenario = await createScenario({
  name: 'مزامنة العملاء المتوقعين مع CRM',
  blueprint: {
    // مخطط JSON للسيناريو
    // يمكن تصديره من محرر Make أو بناؤه برمجيًا
    modules: [
      {
        id: 1,
        app: 'webhooks',
        action: 'customWebhook',
        parameters: { /* ... */ }
      },
      {
        id: 2,
        app: 'salesforce',
        action: 'createRecord',
        parameters: { /* ... */ }
      }
    ],
    connections: [
      { from: 1, to: 2 }
    ]
  },
  active: true,
  description: 'مزامنة العملاء المتوقعين من Webhook إلى Salesforce'
});

console.log(`تم إنشاء السيناريو: ${newScenario.id}`);

تحديث سيناريو

تعديل تكوين السيناريو:

const updateScenario = async (scenarioId, updates) => {
  const response = await makeRequest(`/scenarios/${scenarioId}`, {
    method: 'PATCH',
    body: JSON.stringify(updates)
  });

  return response;
};

// الاستخدام - إيقاف السيناريو مؤقتًا
await updateScenario('12345', { active: false });

// الاستخدام - تحديث الجدول الزمني
await updateScenario('12345', {
  schedule: {
    cronExpression: '0 */6 * * *', // كل 6 ساعات
    timezone: 'America/New_York'
  }
});

حذف سيناريو

إزالة سيناريو:

const deleteScenario = async (scenarioId) => {
  await makeRequest(`/scenarios/${scenarioId}`, {
    method: 'DELETE'
  });

  console.log(`تم حذف السيناريو ${scenarioId}`);
};

إدارة التنفيذ

تشغيل تنفيذ السيناريو

تشغيل السيناريو يدويًا:

const executeScenario = async (scenarioId, inputData = null) => {
  const response = await makeRequest(`/scenarios/${scenarioId}/execute`, {
    method: 'POST',
    body: inputData ? JSON.stringify(inputData) : undefined
  });

  return response;
};

// الاستخدام - تشغيل بدون إدخال
const execution = await executeScenario('12345');
console.log(`بدأ التنفيذ: ${execution.id}`);

// الاستخدام - تشغيل مع بيانات الإدخال
const executionWithData = await executeScenario('12345', {
  lead: {
    email: 'prospect@example.com',
    name: 'جون دو',
    company: 'Acme Corp'
  }
});

الحصول على سجل التنفيذ

جلب سجلات التنفيذ:

const getExecutionHistory = async (scenarioId, filters = {}) => {
  const params = new URLSearchParams({
    limit: filters.limit || 50,
    from: filters.from,
    to: filters.to,
    status: filters.status // 'success', 'error', 'running'
  });

  const response = await makeRequest(`/scenarios/${scenarioId}/executions?${params.toString()}`);
  return response;
};

// الاستخدام - الحصول على التنفيذات الفاشلة من آخر 24 ساعة
const failedExecutions = await getExecutionHistory('12345', {
  from: new Date(Date.now() - 86400000).toISOString(),
  status: 'error',
  limit: 100
});

failedExecutions.data.forEach(exec => {
  console.log(`التنفيذ ${exec.id}: ${exec.error?.message}`);
});

الحصول على تفاصيل التنفيذ

جلب تنفيذ واحد:

const getExecution = async (executionId) => {
  const response = await makeRequest(`/executions/${executionId}`);
  return response;
};

// الاستخدام
const execution = await getExecution('98765');
console.log(`الحالة: ${execution.status}`);
console.log(`المدة: ${execution.duration}ms`);
console.log(`الوحدات المنفذة: ${execution.modulesExecuted}`);

إيقاف التنفيذ الجاري

إلغاء التنفيذ:

const stopExecution = async (executionId) => {
  await makeRequest(`/executions/${executionId}`, {
    method: 'DELETE'
  });

  console.log(`تم إيقاف التنفيذ ${executionId}`);
};

إدارة الـ Webhook

إنشاء Webhook

إعداد Webhook وارد:

const createWebhook = async (webhookData) => {
  const webhook = {
    name: webhookData.name,
    scenarioId: webhookData.scenarioId,
    type: 'custom', // 'custom' or 'raw'
    hookType: 'HEAD', // 'HEAD' or 'GET'
    security: {
      type: 'none' // 'none', 'basic', 'token'
    }
  };

  const response = await makeRequest('/webhooks', {
    method: 'POST',
    body: JSON.stringify(webhook)
  });

  return response;
};

// الاستخدام
const webhook = await createWebhook({
  name: 'Webhook لالتقاط العملاء المتوقعين',
  scenarioId: '12345',
  type: 'custom',
  hookType: 'HEAD',
  security: { type: 'none' }
});

console.log(`عنوان URL للـ Webhook: ${hook.url}`);

سرد الـ Webhooks

جلب جميع الـ Webhooks:

const listWebhooks = async () => {
  const response = await makeRequest('/webhooks');
  return response;
};

// الاستخدام
const webhooks = await listWebhooks();
webhooks.data.forEach(webhook => {
  console.log(`${webhook.name}: ${webhook.url}`);
});

حذف Webhook

إزالة Webhook:

const deleteWebhook = async (webhookId) => {
  await makeRequest(`/webhooks/${webhookId}`, {
    method: 'DELETE'
  });

  console.log(`تم حذف الـ Webhook ${webhookId}`);
};

إدارة الفريق والمستخدمين

سرد أعضاء الفريق

جلب المستخدمين في المؤسسة:

const listTeamMembers = async (organizationId) => {
  const response = await makeRequest(`/organizations/${organizationId}/users`);
  return response;
};

// الاستخدام
const members = await listTeamMembers('org-123');
members.data.forEach(member => {
  console.log(`${member.email} - ${member.role}`);
});

إضافة عضو فريق

دعوة مستخدم إلى المؤسسة:

const addTeamMember = async (organizationId, email, role) => {
  const response = await makeRequest(`/organizations/${organizationId}/users`, {
    method: 'POST',
    body: JSON.stringify({
      email: email,
      role: role // 'viewer', 'builder', 'manager', 'admin'
    })
  });

  return response;
};

// الاستخدام
await addTeamMember('org-123', 'newuser@example.com', 'builder');

تحديث دور المستخدم

تغيير أذونات المستخدم:

const updateUserRole = async (organizationId, userId, newRole) => {
  await makeRequest(`/organizations/${organizationId}/users/${userId}`, {
    method: 'PATCH',
    body: JSON.stringify({ role: newRole })
  });

  console.log(`تم تحديث دور المستخدم ${userId} إلى ${newRole}`);
};

أدوار المستخدمين

تحديد المعدل

فهم حدود المعدل

يطبق Make حدودًا للمعدل حسب الخطة:

رؤوس حدود المعدل

تطبيق معالجة حدود المعدل

const makeRateLimitedRequest = async (endpoint, options = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await makeRequest(endpoint, options);

      const remaining = response.headers.get('X-RateLimit-Remaining');
      if (remaining < 10) {
        console.warn(`حد معدل منخفض: ${remaining} متبقي`);
      }

      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`تم تحديد المعدل. إعادة المحاولة في ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

قائمة التحقق من النشر في الإنتاج

قبل الانطلاق:

• [ ] استخدم مفاتيح API للتكاملات الداخلية، وOAuth لتكاملات العملاء
• [ ] خزن بيانات الاعتماد بأمان (قاعدة بيانات مشفرة)
• [ ] طبق تحديد المعدل وتحديد أولوية الطلبات
• [ ] أعد إعداد مراقبة التنفيذ والتنبيهات
• [ ] قم بتكوين إشعارات الأخطاء (بريد إلكتروني، Slack)
• [ ] طبق منطق إعادة المحاولة للتنفيذات الفاشلة
• [ ] أضف تسجيلًا شاملًا
• [ ] أنشئ نسخًا احتياطية/تصديرًا للسيناريوهات الهامة

حالات الاستخدام الواقعية

إدارة عملاء الوكالات

تدير وكالة تسويق أكثر من 100 عملية أتمتة للعملاء:

• التحدي: التحديثات اليدوية للسيناريوهات عبر حسابات العملاء
• الحل: لوحة تحكم مركزية مع Make API
• النتيجة: توفير 70% من الوقت، نشر متسق

التطبيق الرئيسي:

• تكامل OAuth متعدد الحسابات
• نشر السيناريوهات بالجملة
• تقارير استخدام العميل

معالجة طلبات التجارة الإلكترونية

متجر إلكتروني يقوم بأتمتة تنفيذ الطلبات:

• التحدي: إدخال الطلبات يدويًا إلى نظام المستودع
• الحل: سيناريو Make يعمل بواسطة Webhook
• النتيجة: صفر إدخال يدوي، دقة 99.9%

التطبيق الرئيسي:

• Webhook من Shopify إلى Make
• السيناريو يعالج الطلب، ويحدث المستودع
• معالجة الأخطاء بمنطق إعادة المحاولة

الخلاصة

يوفر Make API إمكانيات شاملة لأتمتة سير العمل. النقاط الرئيسية:

• مفتاح API للاستخدام الداخلي، وOAuth 2.0 للتطبيقات متعددة المستأجرين
• عمليات CRUD كاملة للسيناريوهات، وعمليات التنفيذ، والـ Webhooks
• إدارة الفريق للتحكم في المؤسسة
• تختلف حدود المعدل حسب الخطة (60-600 طلب/دقيقة)
• مراقبة التنفيذ ضرورية للإنتاج
• Apidog يبسط اختبار API والتعاون بين الفرق

كيف يمكنني المصادقة باستخدام Make API؟

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

هل يمكنني تشغيل السيناريوهات برمجيًا؟

نعم، استخدم نقطة النهاية /scenarios/{id}/execute لتشغيل السيناريوهات يدويًا مع بيانات إدخال اختيارية.

ما هي حدود معدل Make؟

تتراوح حدود المعدل من 60 طلبًا/دقيقة (الخطة المجانية) إلى 600 طلب/دقيقة (خطط الفرق/المؤسسات).

كيف أحصل على سجلات التنفيذ؟

استخدم /scenarios/{id}/executions لجلب سجل التنفيذ مع إمكانية التصفية حسب التاريخ والحالة.

هل يمكنني إنشاء Webhooks عبر API؟

نعم، استخدم نقطة النهاية /webhooks لإنشاء الـ Webhooks للسيناريوهات وسردها وحذفها.