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

{ "data": { …lead } } සමඟ 201 ලැබේ. පුද්ගලයා දැනටමත් ඔබේ වැඩබිමේ සිටී නම් (එකම ඊමේල් හෝ දුරකථන අංකය), "duplicate": true සහ පවතින ලීඩ් එක සමඟ 200 ලැබේ. එකම 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 වෙත ඊමේල් කරන්න.