API మరియు webhooksతో మీ సొంత సాఫ్ట్‌వేర్‌ను కనెక్ట్ చేయండి

ఆ టూల్‌కు అవసరమైన అనుమతులు మాత్రమే ఉన్న key సృష్టించండి

సెట్టింగ్‌లు → API & webhooks → Key సృష్టించండి. దానికి వ్యక్తి పేరు కాకుండా టూల్ పేరు పెట్టండి — నెలల తర్వాత ఈ జాబితాలో, భద్రతా లాగ్‌లో మీరు చూసేది ఆ పేరే. ఆపై అనుమతులను టిక్ చేయండి, అవసరమైనవి మాత్రమే: చదవడానికి మాత్రమే ఉన్న key‌తో ఏదీ రాయించలేరు.

• leads:read — లీడ్‌లు, దశలు, ఫలితాలను చదవడం
• leads:write — లీడ్‌లను సృష్టించడం, అప్‌డేట్ చేయడం, తొలగించడం, నోట్లు జోడించడం
• calls:read — కాల్ హిస్టరీ చదవడం
• users:read — ఈ వర్క్‌స్పేస్‌లోని వ్యక్తులను చదవడం
• webhooks:manage — webhooks సృష్టించడం, తొలగించడం

ఇప్పుడే కాపీ చేయండి — అది ఒక్కసారే చూపబడుతుంది

key lk_live_తో ప్రారంభమవుతుంది, మీరు దాన్ని సృష్టించిన వెంటనే వచ్చే డైలాగ్‌లో సరిగ్గా ఒక్కసారి మాత్రమే కనిపిస్తుంది. దాని hash మాత్రమే నిల్వ చేయబడుతుంది, కాబట్టి తర్వాత ఎవరూ దాన్ని తిరిగి చదవలేరు; మీ keys‌ను వేరుగా గుర్తించడానికి జాబితాలో మొదటి కొన్ని అక్షరాలు కనిపిస్తాయి. అది పోగొట్టుకుంటే, ఆ key‌ను రద్దు చేసి కొత్తది జారీ చేయడమే పరిష్కారం. key ఒక ఏజెంట్‌కు కాకుండా వర్క్‌స్పేస్‌కు చెందుతుంది — మీ లీడ్‌లలో కొంత భాగాన్ని మాత్రమే చూసే ఇంటిగ్రేషన్ మీ డేటాలో సగమే సింక్ చేసి పాడైనట్లు కనిపిస్తుంది — మరియు అది రాసే ప్రతిదీ భద్రతా లాగ్‌లో దాని పేరుతోనే నమోదవుతుంది.

బేస్ URL మరియు మొదటి కాల్

సెట్టింగ్‌లు → API & webhooks మీ బేస్ URLను చూపిస్తుంది — ప్రస్తుతం https://api.lumakol.com/api/v1 — మరియు key ప్రతి అభ్యర్థనపై bearer token‌గా వెళ్తుంది. ముందుగా చేయాల్సిన కాల్ GET /ping: key ఏ వర్క్‌స్పేస్‌కు చెందిందో, దానికి ఏ అనుమతులు ఉన్నాయో అది సమాధానంగా ఇస్తుంది; దీంతో మీరు అసలు కోడ్ రాసే ముందే key, హెడర్, చిరునామా అన్నీ సరైనవని నిర్ధారణ అవుతుంది. ప్రతి ఎండ్‌పాయింట్, ఫీల్డ్, ఎర్రర్ కోడ్ API రిఫరెన్స్‌లో జాబితా చేయబడ్డాయి: సెట్టింగ్‌లు → API & webhooks → API రిఫరెన్స్ (మీరు సైన్ ఇన్ అయి ఉండాలి).

• curl https://api.lumakol.com/api/v1/ping -H "Authorization: Bearer lk_live_…"

మీ లీడ్‌లను చదవండి

GET /leads ఒక పేజీ లీడ్‌లను ఇస్తుంది, మీరు ఆశించే ఫిల్టర్‌లతో: stage, owner, source, tag, టెక్స్ట్ సెర్చ్ కోసం q, మరియు ఒకేసారి గరిష్ఠంగా 200 వరకు limit. సమాధానం ఒక ఆబ్జెక్ట్, కేవలం జాబితా కాదు — లీడ్‌లు dataలో ఉంటాయి, వాటి పక్కన next_cursor మరియు has_more ఉంటాయి.

• curl "https://api.lumakol.com/api/v1/leads?limit=100" -H "Authorization: Bearer lk_live_…"
• GET /leads/find ఫోన్, ఇమెయిల్ లేదా మీరే సెట్ చేసిన external_id ద్వారా ఒక లీడ్‌ను వెతుకుతుంది
• GET /stages మరియు GET /dispositions మీ సొంత పైప్‌లైన్, ఫలితాల జాబితాల వెనుక ఉన్న ids‌ను ఇస్తాయి

పేజింగ్, మరియు కాపీని సమకాలీకరణలో ఉంచడం

ఒక పేజీ next_cursorను cursorగా తిరిగి పంపండి, has_more false అయ్యే వరకు పునరావృతం చేయండి; cursor స్థిరంగా ఉంటుంది, కాబట్టి మీరు పేజింగ్ చేస్తున్నప్పుడు మారే లీడ్‌ల వల్ల మీరు ఏ వరుసనూ వదిలేయరు. నిరంతర సింక్ కోసం, చివరిసారి ఎప్పుడు రన్ చేశారో గుర్తుంచుకుని, తదుపరి రన్‌లో దాన్ని updated_sinceగా పంపండి — అప్పటి నుంచి మారినవి మాత్రమే మీకు వస్తాయి, వాటిని కూడా అదే విధంగా పేజింగ్ చేయండి. ప్రతి key నిమిషానికి 60 అభ్యర్థనలు చేయవచ్చు, ఒక వర్క్‌స్పేస్ తన అన్ని keys కలిపి నిమిషానికి 120, రోజుకు 10,000. API keys చెల్లింపు ప్లాన్‌లలో అందుబాటులో ఉంటాయి, ఉచిత ట్రయల్ సమయంలో కాదు. ప్రతిస్పందనలలో RateLimit-Limit, RateLimit-Remaining మరియు RateLimit-Reset హెడర్‌లు ఉంటాయి, 429తో పాటు Retry-After వస్తుంది; Remaining సున్నాకు చేరినప్పుడు, లూప్‌లో మళ్లీ మళ్లీ ప్రయత్నించకుండా reset కోసం వేచి ఉండండి.

Webhook జోడించండి

సెట్టింగ్‌లు → API & webhooks → Webhook జోడించండి. URL httpsగా ఉండాలి, ఇంటర్నెట్ నుంచి చేరుకోగలగాలి — ప్రైవేట్ లేదా అంతర్గత చిరునామాను సేవ్ చేసేటప్పుడే తిరస్కరిస్తాం, ప్రతి డెలివరీకి ముందు మళ్లీ తనిఖీ చేస్తాం, కాబట్టి తర్వాత DNSను వేరే చోటికి మళ్లించినా అది దాటి వెళ్లదు. మీకు కావలసిన ఈవెంట్‌లను టిక్ చేయండి, ఆపై దానిపై ఆధారపడే ముందు టెస్ట్‌తో ఒక నమూనా డెలివరీని క్యూలో పెట్టి మీ రిసీవర్ పనిచేస్తుందని నిర్ధారించుకోండి. డెలివరీలు ప్రతి పది సెకన్లకు తనిఖీ చేసే క్యూ నుంచి పంపబడతాయి, కాబట్టి అవి తక్షణమే కాకుండా కొన్ని సెకన్లలో వస్తాయని ఆశించండి.

• lead.created — ఒక లీడ్‌ను చేతితో, API ద్వారా, ఫారమ్, లీడ్ సోర్స్, వెబ్‌సైట్ చాట్ లేదా మిస్డ్ కాల్ ద్వారా జోడించినప్పుడు (ఫైల్ దిగుమతి ద్వారా కాదు)
• lead.updated — ఒక లీడ్‌ను యాప్‌లో, API ద్వారా లేదా ఆటోమేషన్ నియమం ద్వారా ఎడిట్ చేసినప్పుడు (కాల్ ఫలితాన్ని నమోదు చేస్తే బదులుగా call.logged పంపబడుతుంది)
• lead.stage_changed — ఒక లీడ్ మరో పైప్‌లైన్ దశకు మారినప్పుడు
• lead.assigned — ఒక లీడ్‌ను ఎవరికైనా ఇచ్చినప్పుడు, లేదా తీసివేసినప్పుడు
• call.logged — ఒక కాల్‌పై ఫలితం నమోదు చేసినప్పుడు
• follow_up.due — యజమాని ఉన్న లీడ్‌కు 15 నిమిషాలలోపు ఫాలో-అప్ గడువు ఉన్నప్పుడు

సంతకాన్ని ధృవీకరించండి

ప్రతి అభ్యర్థనలో నాలుగు హెడర్‌లు ఉంటాయి: X-LumaKol-Event, X-LumaKol-Delivery, X-LumaKol-Timestamp మరియు X-LumaKol-Signature. సంతకం అంటే sha256= తర్వాత timestamp, ఒక ఫుల్ స్టాప్ (.), మరియు raw body యొక్క HMAC-SHA256 — webhook సృష్టించినప్పుడు చూపిన signing secret‌ను key‌గా వాడి లెక్కిస్తారు — అది whsec_తో ప్రారంభమవుతుంది. మీరు మళ్లీ serialise చేసిన JSONపై కాకుండా, మీరు నిజంగా అందుకున్న బైట్‌లపై దాన్ని మళ్లీ లెక్కించండి, రెండింటినీ constant-time comparisonతో పోల్చండి, timestamp ఇటీవలిది కాని దేన్నైనా తిరస్కరించండి. సరిపోలని అభ్యర్థన మా నుంచి వచ్చినది కాదు.

• సంతకం చేసే స్ట్రింగ్: timestamp, ఒక ఫుల్ స్టాప్ (.), ఆపై body — ఇదే క్రమంలో
• X-LumaKol-Delivery మళ్లీ ప్రయత్నాలలో మారదు: దాన్ని నిల్వ చేసి, పునరావృతమైనదాన్ని విస్మరించండి, ఎందుకంటే మా వైపు టైమ్ అవుట్ అయిన డెలివరీని, మీ సర్వర్ దాన్ని పూర్తి చేసినా, మళ్లీ ప్రయత్నిస్తాం
• “కొత్త secret” key‌ను మారుస్తుంది, పాతది వెంటనే పనిచేయడం ఆగిపోతుంది, కాబట్టి ముందుగా మీ రిసీవర్‌ను అప్‌డేట్ చేయండి

డెలివరీ లాగ్ మరియు మళ్లీ ప్రయత్నాలు

ఒక webhook కింద “ఇటీవలి డెలివరీలు” తెరిస్తే చివరి డెలివరీలు కనిపిస్తాయి — ఈవెంట్, అవి చేరాయా లేదా, మీ సర్వర్ ఇచ్చిన స్టేటస్ కోడ్ లేదా మాకు వచ్చిన ఎర్రర్, మరియు ఎప్పుడు. 2xx కాని ఏదైనా — redirect కూడా వైఫల్యంగానే లెక్క — ఐదు నిమిషాలు, పదిహేను నిమిషాలు, ఒక గంట, మూడు గంటలు, ఆరు గంటలు, మళ్లీ ఆరు గంటల తర్వాత మళ్లీ ప్రయత్నించబడుతుంది: సుమారు పదహారు గంటల్లో ఏడు ప్రయత్నాలు, కాబట్టి కొంతసేపు డౌన్ అయిన రిసీవర్ ఏమీ కోల్పోదు, రోజంతా డౌన్ అయిన దాన్ని చివరికి వదిలేస్తాం. స్టేటస్ కోడ్ లేదా ఎర్రర్ మాత్రమే ఉంచబడుతుంది, మీ response body కాదు. webhook విజయవంతమయ్యే వరకు, లేదా మీరు దాన్ని ఆఫ్ చేసి ఆన్ చేసే వరకు, దాని చివరి వైఫల్యాన్ని చూపిస్తూనే ఉంటుంది.

• స్విచ్ webhook‌ను తొలగించకుండా నిలిపివేస్తుంది — మీరు redeploy చేస్తున్నప్పుడు కావలసింది ఇదే
• డెలివరీ వరుసలు డీబగ్గింగ్ సహాయం మాత్రమే, రికార్డు కాదు — సుమారు రెండు వారాల తర్వాత అవి తొలగించబడతాయి
• webhook‌ను తొలగిస్తే, దానికోసం ఇంకా క్యూలో ఉన్నవన్నీ వదిలేయబడతాయి

అవసరం తీరిన key‌ను రద్దు చేయండి

రద్దు చేయండి ఆ key వాడుతున్న ప్రతిదాన్నీ వెంటనే ఆపేస్తుంది, దాన్ని వెనక్కి తీసుకోలేరు — ఉద్దేశపూర్వకంగానే pause లేదు. ఒక టూల్‌ను ఇక వాడనప్పుడు, దాన్ని సెటప్ చేసిన వ్యక్తి వెళ్లిపోయినప్పుడు, లేదా key లీక్ అయిందని అనుమానం వచ్చిన క్షణంలోనే రద్దు చేయండి; ఆపై కొత్తది జారీ చేసి టూల్‌లో పేస్ట్ చేయండి. ప్రతి key చివరిసారి ఎప్పుడు వాడబడిందో జాబితా చూపిస్తుంది — ఇక దేనికీ అవసరం లేని key‌ను గుర్తించడానికి ఇదే వేగవంతమైన మార్గం.