واجهة API في CompanyFlowHQ

البدء

1. في CompanyFlowHQ، انتقل إلى الإعدادات ← المطورون وأنشئ مفتاح API. حدّد الصلاحيات التي يحتاجها فقط.
2. انسخ المفتاح فورًا — يبدأ بـ cfhq_live_ ويُعرض مرة واحدة.
3. استدعِ واجهة API من خادمك (لا من صفحة ويب أو تطبيق يمكن للعميل رؤيته أبدًا).

العنوان الأساسي: https://companyflowhq.com/api/v1. الطلبات والردود بصيغة JSON ‏(UTF-8). الأوقات بصيغة ISO 8601 بتوقيت UTC. المبالغ بأصغر وحدة (البنس للجنيه GBP).

المصادقة

أرسل المفتاح في الترويسة Authorization:

curl https://companyflowhq.com/api/v1/leads -H "Authorization: Bearer cfhq_live_YOUR_KEY"

الصلاحيات (النطاقات):

يمكن إلغاء المفاتيح في أي وقت، ويمكن تحديد تاريخ لانتهائها. لا نحفظ إلا بصمة (SHA-256) لكل مفتاح.

نقاط النهاية

مثال العملاء المحتملين

إضافة عميل محتمل (curl)

curl -X POST https://companyflowhq.com/api/v1/leads \
  -H "Authorization: Bearer cfhq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-27-000123" \
  -d '{
    "first_name": "Amara",
    "last_name": "Perera",
    "email": "amara@example.com",
    "phone": "+44 7700 900123",
    "requirement": "MSc Data Science, January intake",
    "consent_marketing": true
  }'

يُرجع 201 مع { "data": { …lead } }. إذا كان الشخص موجودًا بالفعل في مساحة عملك (البريد أو الهاتف نفسه)، تحصل على 200 مع "duplicate": true والعميل المحتمل الموجود. إرسال Idempotency-Key نفسه مرتين لا يُنشئ عميلين محتملين أبدًا.

نقل عميل محتمل إلى مرحلة تالية (JavaScript)

const res = await fetch("https://companyflowhq.com/api/v1/leads/LEAD_ID", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CFHQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ stage: "qualified", priority: "hot" }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const { data: lead } = await res.json();

مثال منشورات التواصل الاجتماعي

ارفع صورة أولًا (اختياري)، ثم أنشئ المنشور. يمكن أن يكون لكل حساب نصه الخاص.

# 1. Upload a picture
curl -X POST https://companyflowhq.com/api/v1/media \
  -H "Authorization: Bearer cfhq_live_YOUR_KEY" \
  -F "file=@open-day.jpg"
# → { "data": { "id": "MEDIA_ID", ... } }

# 2. Schedule the post
curl -X POST https://companyflowhq.com/api/v1/social/posts \
  -H "Authorization: Bearer cfhq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Open day this Saturday, 10am to 2pm. Everyone welcome!",
    "media_ids": ["MEDIA_ID"],
    "accounts": [
      { "account_id": "FACEBOOK_ACCOUNT_ID" },
      { "account_id": "LINKEDIN_ACCOUNT_ID", "text": "Join our open day this Saturday (10:00–14:00)." }
    ],
    "schedule": { "mode": "at", "at": "2026-10-03T08:00:00Z" }
  }'

قيمة schedule.mode هي now أو at أو queue (أول فترة متاحة) أو draft. أضف "require_approval": true لإرساله للاعتماد في CompanyFlowHQ بدلًا من ذلك. تتبع المنشورات القواعد نفسها المتّبعة في التطبيق، بما في ذلك اعتماد العميل للوكالات. تابع التقدّم عبر GET /api/v1/social/posts/{id} — يسرد results حالة كل شبكة ورابطها وأي خطأ.

ترقيم الصفحات

تُرجع القوائم ما يصل إلى limit عنصر (25 افتراضيًا، و100 كحد أقصى)، الأحدث أولًا:

{ "data": [ … ], "has_more": true, "next_cursor": "WyIyMDI2LTA5…" }

مرّر ?cursor= مع قيمة next_cursor للحصول على الصفحة التالية. توقّف عندما تكون قيمة has_more هي false.

خطافات الويب

أضف خطاف ويب في الإعدادات ← المطورون (أو عبر واجهة API). نرسل JSON بطريقة POST إلى عنوان HTTPS الخاص بك عند حدوث شيء:

POST /your-webhook
Content-Type: application/json
X-CompanyFlow-Event: lead.created
X-CompanyFlow-Delivery: 5f0c…
X-CompanyFlow-Signature: t=1790000000,v1=6b1f…

{ "id": "evt_…", "type": "lead.created", "created": "2026-09-27T10:00:00.000Z",
  "data": { "lead": { "id": "…", "first_name": "Amara", … }, "source": "Website" } }

أجب بأي حالة 2xx خلال 10 ثوانٍ. أي شيء آخر يُعدّ فشلًا، ونعيد المحاولة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 12 ساعة. بعد 20 فشلًا متتاليًا يُوقف خطاف الويب ويُرسل بريد إلى المالك. لا تُتّبع عمليات إعادة التوجيه، ويجب أن تكون العناوين عامة (لا شبكات خاصة أو محلية). قد يصل الحدث نفسه مرتين أحيانًا — استخدم id لتجاهل التكرار.

Zapier وMake

اربط CompanyFlowHQ بأكثر من 7,000 تطبيق — Xero وQuickBooks وSlack وGoogle Sheets وغيرها — دون برمجة.

1. في الإعدادات ← المطورون، اضغط إنشاء مفتاح Zapier (أو إنشاء مفتاح Make) وانسخ المفتاح.
2. في Zapier، اختر تطبيق CompanyFlowHQ والصق المفتاح عند الطلب. وفي Make، أضف تطبيق CompanyFlowHQ (أو استخدم وحدة HTTP مع الترويسة Authorization: Bearer cfhq_live_…).
3. اختر مُشغّلًا مثل عميل محتمل جديد أو فاتورة مدفوعة أو صفقة ناجحة، ثم إجراءً في التطبيق الآخر.

المُشغّلات فورية: عند تشغيل Zap، يشترك Zapier عبر POST /api/v1/hooks { "event": "lead.created", "target_url": "https://hooks.zapier.com/…" } ويلغي الاشتراك عبر DELETE /api/v1/hooks/{id} عند إيقافه. تستخدم عمليات التسليم الصيغة والتوقيع وإعادة المحاولة نفسها المستخدمة في خطافات الويب؛ والرد بـ 410 Gone يزيل الاشتراك. يمكنك رؤية المُشغّلات النشطة وإزالتها في الإعدادات ← المطورون.

التحقق من التوقيعات

كل رسالة موقّعة بالسر الخاص بخطاف الويب (يبدأ بـ whsec_). التوقيع هو HMAC-SHA256 للقيمة <t>.<raw body>. تحقّق منه دائمًا، وارفض الرسائل الأقدم من 5 دقائق.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/companyflow-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-CompanyFlow-Signature") ?? "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", process.env.CFHQ_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const ok =
    fresh && v1 && v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  if (!ok) return res.status(400).send("Bad signature");
  const event = JSON.parse(req.body);
  // … handle event.type / event.data …
  res.sendStatus(200);
});

Cloudflare Workers / Deno / المتصفحات (Web Crypto)

async function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const key = await crypto.subtle.importKey(
    "raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${t}.${rawBody}`));
  const hex = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
  return hex === v1; // use a constant-time compare in production
}

حدود المعدّل

يمكن لكل مفتاح إجراء 120 طلب في الدقيقة. يتضمن كل رد X-RateLimit-Limit وX-Request-Id. عند تجاوز الحد تحصل على 429 مع الترويسة Retry-After — انتظر ذلك العدد من الثواني ثم أعد المحاولة.

الأخطاء

تبدو الأخطاء دائمًا بالشكل نفسه:

{ "error": { "code": "insufficient_scope", "message": "This API key doesn't have the “leads:write” permission." } }

لديك أسئلة؟ راسلنا على support@companyflowhq.com.