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

১০ সেকেন্ডের মধ্যে যেকোনো 2xx অবস্থা দিয়ে উত্তর দিন। অন্য কিছু ব্যর্থতা হিসেবে গণ্য হয় এবং আমরা ১ মিনিট, ৫ মিনিট, ৩০ মিনিট, ২ ঘণ্টা আর ১২ ঘণ্টা পরে আবার চেষ্টা করি। টানা ২০ বার ব্যর্থ হলে ওয়েবহুক বন্ধ করে মালিককে ইমেইল করা হয়। রিডাইরেক্ট অনুসরণ করা হয় না, আর ঠিকানা পাবলিক হতে হবে (ব্যক্তিগত বা স্থানীয় নেটওয়ার্ক নয়)। একই ঘটনা মাঝে মাঝে দুবার আসতে পারে — পুনরাবৃত্তি উপেক্ষা করতে id ব্যবহার করুন।

Zapier ও Make

কোড ছাড়াই CompanyFlowHQ-কে ৭,০০০-এর বেশি অ্যাপের সাথে যুক্ত করুন — 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। সবসময় এটি যাচাই করুন, আর ৫ মিনিটের বেশি পুরোনো মেসেজ প্রত্যাখ্যান করুন।

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-এ ইমেইল করুন।