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 முகவரிக்கு மின்னஞ்சல் அனுப்புங்கள்.