API-ga
Ma jiro endpoint gaar ah. Xitaa interface-ka.
Badeecadaha badankood waxay leeyihiin laba API: mid la ogyahay oo lagu siiyo, iyo mid xiiso leh oo shaashadahoodu u isticmaalo. Midka labaad had iyo jeer waa kan fiican, adiguna lama ogola inaad u dhowaato. Halkan waxaa jira mid keliya, interface-kuna waa macmiil (client) oo ka mid ah sida wax kasta — taas oo nuqul nagu ah, iyo sababta wax kasta oo aad rabto inaad dhisayso suurtogal noqdaa.
Xeerkaas runtii waxa uu kharash ka noqdo
Waxay la macno tahay in shaashad mararka qaar sugto in API-gu sax yahay, halkay ka gudban lahayd hal beer oo fudud. Maalinta shaashad u baahdo wax aan API-ga dadweynuhu siin karin waa maalinta API-gu qaldan yahay, xalkuna waa API-ga.
Faa'iidadu waa in saddex macmiil oo aad u duwan kharash dheeraad ah ku dhowaan waxba ma leh. Server-ka MCP waa macmiil. Tile-ka dash-b waa macmiil. Script-kaada waa macmiil. Midkoodna ma aha muwaadin labaad oo ku dhaqaaqaya dusha loo qorsheeyay qof kale, sababtoo ah ma jiro dusha kale loo labaad noqdo.
La ogyahay, la isticmaalo
OpenAPI waxaa la abuuraa /docs oo waddada kastaa waxay leedahay tijaabo ah tusaalaha dukumeentiyada. Dukumeenti si gooni loo qoro wuxuu ka baxaa xeerka hal bil gudihiis; dukumeentiga marka uu qaldan yahay dhismaha fashliya midkaas ma fadhiisto.
Gelida (Sign-in)
Xisaabtaada castomo, iyada oo loo marayo authorization code flow oo leh PKCE — xisaabtaas oo la mid ah ta aad isticmaasho dash-b iyo qoyska intiisa kale. Bog aan server u lahayn wuxuu si fiican u fulin karaa flow-gaas; waa tan loogu talagalay. Shaqada mashiin-to-mashiin, furaha API oo mashruuc u gaar ah.
- 1Dadka
/v1/contacts·/lists·/segments·/tags·/imports - 2Waxa ku jira
/v1/creatives, oo leh hubin, preview iyo render target kasta - 3Otomaatig
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Tebin
/v1/campaigns, oo leh audience, materialise, jadwal iyo dirid talaabooyin kala duwan - 5Dhacdooyin gelitaan
/v1/events— dhacdooyinka codsigaada u gaarka ah, sida kiciyayaal (triggers) - 6Gaadhsiinta
/sender-identities·/domains·/apps·/webhooks - 7Tirooyinka
/v1/reports/*, iyo/track/*ee host-ka la socodka
OpenAPI ee /docs/mcp ee nidaamka la mid ah
Caadooyin
Qaabka la mid ah adeegga castomo kasta oo kale
Taas oo ka muhiimsan sida ay u maqan tahay. Haddaad horey u wacdo mid ka mid ah kuwan, horeyba waad ogtahay sida kan ugu jawaabo, u fashlo, u page-gareeyo.
Hal xidhmo khalad (error envelope)
Fashilaad kastaa waxay leedahay qaab la mid ah, kood deggan iyo fariin loogu talagalay qof. Waddad ma abuurto si u gaar ah oo aan ku faraxsanahay.
Pagination-ka cursor
Ma aha offsets. Liiska isbeddelaya inta aad ku socdo ma dhaafayn ama ku celinayn saf si qarsoodi ah, taas oo offset pagination si qarsoodi ah iyo joogto ah u sameyso.
Furahe idempotency
Waddad kasta oo wax beddela. Ku celi codsi aad shaki ku tahay inuu gaaray oo hel jawaabta la mid ah, halka laga horreeyo xiriir labaad, ololhe labaad ama dirin labaad.
Mashruuc u gaar ah
Token-ku wuxuu tilmaamaa hal tenant iyo hal mashruuc, labadaba. Amniga heerka saf (row-level security) waxaa lagu dhaqaaqay database-ka laftiisa, ma aha xasuista in la kudho qayd (clause).
Webhooks bannaanka
La saxeexay, la dib ku celiyay dib-u-gujiyo (backoff), oo la gaarsiiyay ugu yaraan hal mar — sidaa darteed dhamaadkaaga waa inuu ahaado mid idempotent. Dhacdooyinku waa ereyada la isku dheelitiray kuwa warbixinadu adeegsadaan.
Tirtirid iyo dhoofin
Xiriiriye waa la dhoofin karaa ama la tirtiri karaa iyada oo loo marayo API-ga, tirtiriddu waxayna gaaraa adeeg kasta oo walaal ah oo nuqul haysta iyada oo loo marayo waddada gudaha ee qoyska oo dhan.
Wax kasta oo interface-ku qabto, POST baa qabi kara.
Dhacdooyinku waa qaybta xiisaha leh
Wax kasta oo kale oo boggaan ku yaal waa tubooyin aad ka filayso. POST /v1/events waa waddada beddeshay ujeeddada badeecadda.
Codsigaaga horeyba wuxuu ogyahay wax aan qalabka suuqgelinta arki karin: qofka dhameeyay onboarding-ka, qofka saaxiib ku casuumay, qofka gaaray xad, qofka Axad galab ah dhoofiyay xogtiisa. Ku soo dir kuwan dhacdooyin ahaan adigoo isticmaalaya calaamaddaada, mid kastana wuxuu noqdaa kiciye (trigger), xaalad iyo qayb (segment).
Inta kale waxay ka soo baxdaa moodelka xiriiriyaha. Dhacdooyinka la dhufto (append), lama waxba loo beddelo; waa diiwaanka badeecaddu ku xiran tahay. Funnel dhacdo aad ku qeexday ku kicada waa la isku dheeli maaha — waa habka message_opened isticmaalo, magac keliya oo ku dhex qoran oo ka duwan.
- 1Adiga ayaa ku diraysa
POST /v1/events— magac, xiriiriye, payload, iyo furaha idempotency. - 2Waxay gaaraaWaxaa lagu daraa diiwaanka xiriiriyaha. Waxba ma u baahna inay ogyihiin inay jirto.
- 3Funnel bilaabmaaFunnel kasta oo gelintiisu sheegayso dhacdoogaas, xiriiriye kasta oo sharrti gelintiisa u qalma.
- 4Funnels kale waxay ku laayiyaan"Dhacdoogaan 14 maalmood ee ugu dambeeyay dhacay" waa xaqiijin (predicate) qayb caadi ah.
- iOo waxay joojisaa socodsiintaGoon (goal) dhacdoogaas la midka magacaaba waxay joojisaa taxane (sequence) marka qofku waxaas sameeyo, isla markiiba.
EreyadaadaCalaamaddaada (token)
Xuduudo aad ka ogaato ka hor intaadan dhisin
ClickSomo waxay kaydisaa saddex aqoonsi oo ku saabsan adiga — tenant, mashruuc iyo isticmaale, sii ids qarsoon (opaque) — iyo waxba. Wax password ah, wax profile ah, wax kaarka ah, wax fatura ah. Xaddidaadaha qorshaha waxay imadaan tirooyin ahaan: immisa xiriiriye, immisa dirid, immisa abuurid. Ereyyada lacag-bixinta kuma gudbaan xuduudaas labada dhinacba.
Xiriiriyayaashaada waa kuwaada. Adigu waa maamulaha xogta (data controller); annagu waa shaqaalaha xogta (processor). Ma jiro waddo ay badeecad kale oo qoyska ka tirsan ku akhriyto ama ku qorto liiska xiriiriyayaashaaga, mana jiro waddo maareyn (ingest) ay mid isticmaalo.
Haddii aad si dhab ah u qiimeynaysid: akhri /docs ka hor intaadan akhriyin wax kale oo boggaan ah. API-gu waa sharaxaadda daacad ah ee waxa badeecaddu qabto, iyo sheeko kasta oo boggan ku yaal waxay u dhigantaa waddo ama nooc goon (node kind) halkaas laga helo. Marka schema-gu isbeddelo, boggani way isbeddelaan.