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 पर ईमेल करें।