CompanyFlowHQ API

آغاز

1. CompanyFlowHQ میں سیٹنگز ← ڈیولپرز پر جائیں اور ایک API کلید بنائیں۔ صرف وہی اجازتیں منتخب کریں جن کی ضرورت ہے۔
2. کلید فوراً کاپی کریں — یہ cfhq_live_ سے شروع ہوتی ہے اور صرف ایک بار دکھائی جاتی ہے۔
3. API کو اپنے سرور سے کال کریں (کبھی بھی ایسے ویب صفحے یا ایپ سے نہیں جسے گاہک دیکھ سکے)۔

بنیادی پتہ: https://companyflowhq.com/api/v1۔ درخواستیں اور جوابات JSON ‏(UTF-8) میں ہیں۔ اوقات UTC میں ISO 8601 کے مطابق ہیں۔ رقم سب سے چھوٹی اکائی میں ہے (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 ہوتی ہے۔ اس کے بجائے CompanyFlowHQ میں منظوری کے لیے بھیجنے کو "require_approval": true شامل کریں۔ پوسٹس ایپ جیسے ہی قواعد پر چلتی ہیں، ایجنسیوں کے لیے کلائنٹ کی منظوری سمیت۔ پیش رفت GET /api/v1/social/posts/{id} سے دیکھیں — results ہر نیٹ ورک کی حالت، لنک اور کوئی بھی غلطی بتاتا ہے۔

صفحہ بندی

فہرستیں زیادہ سے زیادہ limit اشیاء واپس کرتی ہیں (طے شدہ 25، زیادہ سے زیادہ 100)، نئی پہلے:

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

اگلا صفحہ لینے کے لیے next_cursor کی قدر کے ساتھ ?cursor= بھیجیں۔ جب has_more کی قدر false ہو تو رک جائیں۔

ویب ہکس

سیٹنگز ← ڈیولپرز میں (یا API سے) ویب ہک شامل کریں۔ کچھ ہونے پر ہم آپ کے HTTPS پتے پر JSON کو POST کرتے ہیں:

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" } }

10 سیکنڈ کے اندر کوئی بھی 2xx حالت واپس کریں۔ باقی سب ناکامی شمار ہوتا ہے اور ہم 1 منٹ، 5 منٹ، 30 منٹ، 2 گھنٹے اور 12 گھنٹے بعد دوبارہ کوشش کرتے ہیں۔ لگاتار 20 ناکامیوں کے بعد ویب ہک بند کر دیا جاتا ہے اور مالک کو ای میل بھیجی جاتی ہے۔ ری ڈائریکٹس کی پیروی نہیں کی جاتی، اور پتے عوامی ہونے چاہییں (نجی یا مقامی نیٹ ورک نہیں)۔ ایک ہی واقعہ کبھی کبھار دو بار آ سکتا ہے — تکرار نظر انداز کرنے کے لیے id استعمال کریں۔

Zapier اور Make

CompanyFlowHQ کو کوڈ کے بغیر 7,000 سے زیادہ ایپس سے جوڑیں — Xero، QuickBooks، Slack، Google Sheets اور بہت کچھ۔

1. سیٹنگز ← ڈیولپرز میں Zapier کلید بنائیں (یا Make کلید بنائیں) دبائیں اور کلید کاپی کریں۔
2. Zapier میں CompanyFlowHQ ایپ منتخب کریں اور پوچھے جانے پر کلید پیسٹ کریں۔ Make میں CompanyFlowHQ ایپ شامل کریں (یا Authorization: Bearer cfhq_live_… ہیڈر کے ساتھ اس کا HTTP ماڈیول استعمال کریں)۔
3. نئی لیڈ، انوائس ادا ہو گئی یا ڈیل جیت لی جیسا ٹرگر منتخب کریں، پھر دوسری ایپ میں کوئی کارروائی۔

ٹرگرز فوری ہیں: جب Zap چالو ہوتا ہے تو Zapier POST /api/v1/hooks { "event": "lead.created", "target_url": "https://hooks.zapier.com/…" } سے سبسکرائب کرتا ہے اور بند ہونے پر DELETE /api/v1/hooks/{id} سے ان سبسکرائب کرتا ہے۔ ترسیل ویب ہکس جیسا ہی فارمیٹ، دستخط اور دوبارہ کوشش استعمال کرتی ہے؛ 410 Gone سے جواب دینے پر سبسکرپشن ختم ہو جاتی ہے۔ فعال ٹرگرز آپ سیٹنگز ← ڈیولپرز میں دیکھ اور ہٹا سکتے ہیں۔

دستخطوں کی جانچ

ہر پیغام آپ کے ویب ہک کے خفیہ کوڈ سے دستخط شدہ ہوتا ہے (جو whsec_ سے شروع ہوتا ہے)۔ دستخط <t>.<raw body> کا HMAC-SHA256 ہے۔ اسے ہمیشہ جانچیں، اور 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 ہوتے ہیں۔ حد سے تجاوز پر آپ کو Retry-After ہیڈر کے ساتھ 429 ملتا ہے — اتنے سیکنڈ انتظار کریں اور دوبارہ کوشش کریں۔

غلطیاں

غلطیاں ہمیشہ ایک جیسی دکھتی ہیں:

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

سوالات؟ support@companyflowhq.com پر ای میل کریں۔