Çelësat API dhe webhook-et

Çelësat API dhe webhook-et e lidhin SADE CRM me pjesën tjetër të softuerit tuaj. Kërkojnë një zhvillues, ose një mjet, si një shërbim automatizimi, që mund të dërgojë dhe të marrë kërkesa HTTP.

• Një çelës API i lejon një serveri të dërgojë kërkesa dhe aktivitet në CRM-në tuaj: pjesën e pasme të faqes suaj, formularët e kërkesave të një mjeti reklamimi, sistemet tuaja.
• Një webhook është drejtimi i kundërt: SADE CRM thërret një adresë të internetit tuaj sa herë që ndodh diçka me një nga klientët tuaj, që softueri juaj tjetër ta ndjekë.

Të dyja i vendos një administrator i agjencisë te Cilësimet → Integrimet, vetëm në CRM-në web. Karta Çelësat API lidhet me këtë faqe: Si të konfiguroni çelësat API dhe webhook-et. Për një formular të thjeshtë kontakti në faqen tuaj nuk ju duhet asnjëri: përdorni një formular faqeje. Që portalet e tjera të lexojnë njoftimet tuaja, shihni feed-et Kyero dhe OpenImmo te Importet dhe feed-et.

Jepini këtë faqe zhvilluesit tuaj. Ka gjithçka që i duhet.

Cilësimet → Integrimet. Karta Çelësat API është më poshtë, dhe Webhooks poshtë saj.

Çelësat API

Krijimi i një çelësi

1. Hapni Cilësimet → Integrimet dhe shkoni te karta Çelësat API.
2. Klikoni Krijo çelës.
3. Jepini një Emri sipas asaj që do ta përdorë, si “Faqja jonë” ose “Facebook lead ads”. Emri ju tregon cilin çelës ta revokoni më vonë, dhe është burimi i kërkesave të dërguara me çelësin, përveç nëse dërguesi jep një tjetër.
4. Klikoni Krijo çelës.
5. Dritarja Kopjo çelësin e ri e tregon çelësin vetëm një herë. Klikoni Kopjo çelësin.
6. Klikoni E kopjova.
7. Jepuni çelësin zhvilluesit tuaj përmes një kanali të sigurt, si një menaxher fjalëkalimesh. Jo me email ose bisedë të thjeshtë.

E rëndësishme: nuk do ta shihni më çelësin. SADE CRM ruan vetëm një gjurmë dixhitale të tij, ndaj askush, as SADE, nuk mund t’jua tregojë më vonë. Nëse humbet, revokojeni dhe krijoni një të ri.

Mbajtja e çelësave sekretë

Një çelës fillon me sade_live_. Kushdo që e ka mund të dërgojë kërkesa në CRM-në tuaj.

• Mbajini çelësat vetëm në servera. Kurrë mos e vendosni një çelës në një faqe interneti, në një aplikacion telefoni ose në diçka që shfletuesi i një vizitori e shkarkon, ku kushdo mund ta lexojë.
• Krijoni një çelës për çdo faqe ose mjet. Kështu mund ta fikni njërin pa prekur të tjerët.
• Nëse një çelës mund të ketë dalë jashtë, revokojeni dhe krijoni një të ri.

Lista e çelësave

Lista tregon për çdo çelës Emri, fillimin e Çelësi (për shembull sade_live_XMfm…), kur u Krijuar, kur u Përdorur së fundi (“Kurrë” nëse ende jo), dhe Statusi: Aktiv ose Revokuar. Çdo çelës mund të bëjë të njëjtën gjë: të dërgojë ngjarje në agjencinë tuaj. Nuk ka leje të veçanta për të zgjedhur.

Revokimi i një çelësi

1. Klikoni Revoko te rreshti i çelësit.
2. Konfirmoni me Revoko çelësin.

Që nga ai çast çdo gjë që ende dërgon me çelësin refuzohet. Revokimi nuk kthehet pas; çelësi mbetet në listë, i zbehtë, si Revokuar.

Dërgimi i kërkesave me një çelës

Zhvilluesi juaj e dërgon çdo kërkesë ose pjesë aktiviteti si një kërkesë HTTP POST te shtegu /api/v1/events në adresën API të SADE. Kjo adresë është ajo në kodin e formularit të faqes suaj: pjesa para /forms/v1.js poshtë Kodi për faqen tuaj. Nëse nuk keni formular faqeje, kërkojani SADE-s.

Dërgojeni çelësin në header-in Authorization. Gjithçka është JSON, dhe kohët janë në ISO 8601 me zonë kohore.

POST /api/v1/events
Authorization: Bearer sade_live_…
Content-Type: application/json
Idempotency-Key: 7d4c0a3e-2b1f-4c55-9e0a-3f1d2a6b8c90

{
  "type": "property_inquiry",
  "source": "tiranaliving.al",
  "message": "Is the flat still available? Could I see it on Saturday?",
  "person": {
    "name": "Klea Muka",
    "email": "[email protected]",
    "phone": "+355 68 412 3377",
    "language": "sq"
  },
  "property": { "id": "c8f933f3-95d8-4d30-8ef5-f925e29aed3d" },
  "consents": [
    {
      "channel": "phone",
      "purpose": "contact",
      "granted": true,
      "wording": "I agree to be contacted about my enquiry.",
      "language": "en"
    }
  ]
}

Të detyrueshme janë vetëm type, dhe një email ose phone për personin.

Një çelës mund të emërtojë vetëm njoftimet dhe projektet tuaja. Emërtimi i atyre të një agjencie tjetër refuzohet.

Llojet e ngjarjeve

Ngjarjet e qëllimit janë dikush që kërkon të kontaktohet. Ato e krijojnë personin nëse nuk e keni ende, si kërkesë të re, dhe e shpërndajnë, e masin me kohë dhe e sinjalizojnë si çdo kërkesë:

registration, inquiry, property_inquiry, seller_inquiry, general_inquiry, incoming_call, visited_open_house.

Ngjarjet e sjelljes i shtohen vetëm kronologjisë së dikujt që e keni tashmë. Për një person që nuk e njihni, ato marrin përgjigjen ignored dhe nuk ruhet asgjë:

viewed_property, saved_property, property_search, saved_property_search, visited_website, viewed_page, unsubscribed.

Çfarë kthehet

{
  "status": "created",
  "eventId": "f1397256-2319-4810-a32b-4966c61777a9",
  "personId": "ccb5e979-4b32-4283-997f-74cd01cc3675",
  "inquiryId": "1b4a29af-d287-48d0-9399-32e75c3528de"
}

inquiryId është null kur ngjarja nuk hapi asnjë pyetje për një njoftim.

Rregulla për dërguesit

• Dërgojeni çdo ngjarje një herë, në mënyrë të sigurt. Jepini çdo ngjarjeje një id, në header-in Idempotency-Key ose si id, dhe dërgoni të njëjtën id kur provoni përsëri. CRM-ja e regjistron një herë.
• Kufiri i shpeshtësisë. Çdo çelës mund të dërgojë 60 ngjarje në minutë.
• Një person, shumë ngjarje. Njerëzit përputhen brenda agjencisë suaj sipas emailit, pastaj sipas telefonit, cilado mënyrë që të shkruhet numri. Një ngjarje kurrë nuk mbishkruan atë që keni tashmë; plotëson vetëm ato që mungojnë.
• Kërkesat e dërguara me një çelës shpërndahen, maten me kohë dhe sinjalizohen si kërkesat nga marketplace, dhe nxisin webhook-et tuaja.

Webhook-et

Shtimi i një webhook-u

1. Hapni Cilësimet → Integrimet dhe shkoni te karta Webhooks.
2. Klikoni Shto webhook.
3. Shkruani URL-në ku SADE CRM duhet t’i dërgojë kërkesat HTTP. Duhet të fillojë me https://.
4. Poshtë Dërgo kur, shënoni Ndodh çdo gjë, edhe ngjarje që shtohen më vonë, ose shënoni ngjarjet që doni.
5. Klikoni Shto webhook.
6. Te rreshti i webhook-ut, klikoni Shfaq sekretin, pastaj Kopjo sekretin. Jepini zhvilluesit tuaj URL-në dhe sekretin.
7. Klikoni Dërgo test dhe lexoni rezultatin.

URL-ja duhet të jetë një adresë publike https:// në internet, deri në 2.048 shenja. Adresat pa https://, adresat e rrjeteve private dhe adresat me emër përdoruesi ose fjalëkalim në to refuzohen.

Ngjarjet

Rreshti tregon ngjarjet që dëgjon një webhook, ose Të gjitha ngjarjet.

Si duket një dërgesë

Çdo dërgesë është një POST me një trup JSON si ky, për një ndryshim faze:

{
  "id": "5a0e6c1e-8a4f-4f5b-9d43-1c2b7e9f0a11",
  "event": "person.stage_changed",
  "companyId": "3f7a1c28-6d0b-4f8e-a1c2-9b7d5e4f3a20",
  "createdAt": "2026-11-05T14:54:12Z",
  "data": {
    "person": {
      "id": "ccb5e979-4b32-4283-997f-74cd01cc3675",
      "companyId": "3f7a1c28-6d0b-4f8e-a1c2-9b7d5e4f3a20",
      "name": "Klea Muka",
      "email": "[email protected]",
      "phone": "+355684123377",
      "stage": "spoke_with_customer",
      "assignedAgentId": "8d2e4b61-0c3a-4f7e-b5d9-2a1c6e8f4b03",
      "source": "tiranaliving.al",
      "createdAt": "2026-11-05T14:41:07Z",
      "lastActivityAt": "2026-11-05T14:53:58Z"
    },
    "change": { "from": "lead", "to": "spoke_with_customer" }
  }
}

• data.person është në çdo ngjarje person.*. Fushat pa vlerë lihen jashtë.
• event.created dërgon data.event (llojin, burimin, mesazhin, njoftimin e kështu me radhë) dhe data.person.
• note.created e dërgon shënimin te data: id, personId, text, authorUserId dhe createdAt.
• Fazat dërgohen me çelësat e tyre: lead, attempted_contact, spoke_with_customer, appointment_set, met_with_customer, showing_homes, listing_agreement, active_listing, submitting_offers, under_contract, closed, nurture dhe trash.
• Kohët janë në UTC.

Kërkesa mbart këto header-a:

X-Sade-Event: person.stage_changed
X-Sade-Delivery: 5a0e6c1e-8a4f-4f5b-9d43-1c2b7e9f0a11
X-Sade-Signature: t=1793890452,v1=9f3c…
User-Agent: SadeCRM-Webhooks/1.0

X-Sade-Delivery është i njëjtë me id. Dërgesat mund të arrijnë më shumë se një herë dhe jashtë radhe: përdorni X-Sade-Delivery për të hequr përsëritjet, dhe createdAt për t’i vënë në radhë.

Kontrolli i nënshkrimit

Çdo dërgesë nënshkruhet me sekretin e webhook-ut, që fillon me whsec_. Kontrolloni nënshkrimin para se t’i besoni një dërgese:

1. Lexoni t (një kohë në sekonda Unix) dhe v1 nga header-i X-Sade-Signature.
2. Llogaritni HMAC-SHA256 të tekstit {t}.{raw body} (kohën, një pikë, pastaj trupin saktësisht siç u mor), me sekretin si çelës, të shkruar si heksadecimal me shkronja të vogla.
3. Krahasojeni me v1, në kohë konstante.
4. Refuzojeni dërgesën nëse t është më i vjetër se pesë minuta.

Në Node.js:

import crypto from "node:crypto";

function isFromSade(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Sekreti mund të shfaqet përsëri në çdo kohë me Shfaq sekretin. Nuk ka buton për ta ndryshuar: për të marrë një sekret të ri, fshini webhook-un dhe shtojeni përsëri, gjë që heq edhe historikun e dërgesave të tij.

Përgjigjja, riprovimet dhe çaktivizimi

• Përgjigjuni me çfarëdo statusi 2xx brenda 10 sekondash. Çdo gjë tjetër llogaritet si dështim, dhe po ashtu një ridrejtim: ridrejtimet nuk ndiqen.
• Një dërgesë e dështuar provohet përsëri me ndarje gjithnjë më të mëdha, deri në 9 përpjekje në rreth një orë e gjysmë.
• Pas 50 përpjekjesh të dështuara radhazi (çdo riprovim llogaritet si një), webhook-u e çaktivizon veten, Joaktiv, dhe karta shpjegon pse: “U çaktivizua pas 50 dërgesave të dështuara radhazi. Gabimi i fundit: …”. Rregulloni marrësin, pastaj aktivizojeni përsëri webhook-un. Aktivizimi e fillon numërimin nga e para.
• Sa kohë një webhook është joaktiv, nuk i dërgohet asgjë.

Testimi dhe regjistri i dërgesave

Dërgo test dërgon menjëherë një ngjarje ping, me data.message “A test from SADE CRM.” (një test nga SADE CRM), edhe kur webhook-u është joaktiv. Karta tregon “Testi u dërgua. Serveri juaj u përgjigj 200.” ose pse dështoi. Testet ping nuk renditen në regjistër dhe nuk llogariten si dështime.

Dërgesat e fundit hap 50 dërgesat e fundit, më e reja së pari, me Ngjarja, Statusi (Dërguar, Dështoi ose Në pritje), numrin e Përpjekje, Përgjigja që dha serveri juaj, dhe kur u Krijuar. Klikoni Rifresko për ta përditësuar.

Ndryshimi, ndalimi dhe fshirja

• Ndërruesi Aktiv / Joaktiv e ndalon një webhook pa humbur asgjë.
• Lapsi hap Ndrysho webhook-un për të ndryshuar URL-në ose ngjarjet.
• Koshi e fshin webhook-un. Nuk i dërgohet më asgjë, dhe historiku i dërgesave të tij hiqet.

Shembull

Diçka e paqartë apo që mungon? Shkruani në [email protected] ose telefononi në +355 69 808 0118.