Lidhjet API

Lidh API-të tuaja të jashtme me enuchat që AI dhe rregullat të marrin të dhëna në kohë reale nga sistemet tuaja.

Si funksionon

Lidhjet API ju lejojnë të integroni enuchat me sistemet tuaja të brendshme — engine-t e rezervimeve, CRM-të, menaxhimin e porosive, inventarin dhe më shumë. Kur një vizitor bën një pyetje, enuchat mund të thirrë API-n tuaj për të marrë të dhëna reale dhe për t'i përfshirë në përgjigje.

Rrjedha

Konfiguro një lidhje — URL bazë të API-t tuaj dhe autentifikimin
Shto endpoint-e — thirrje specifike API me shabllone të rrugës dhe mapim të përgjigjes
Krijo një rregull — një rregull AI ose statik me një veprim CALL_API
Vizitori bën një pyetje — rregulli aktivizohet, thirr API-n tuaj, mapon përgjigjen te variablat e sesionit
AI përgjigjet me të dhëna reale — variablat e sesionit janë të disponueshme për AI për të gjeneruar një përgjigje të saktë

Shembull: Disponueshmëria e dhomave të hotelit

Vizitori: "A është dhoma 205 e disponueshme javën tjetër?"

Rregulla AI përputhet: "Kur vizitori pyet për disponueshmërinë e dhomës"

Veprimi CALL_API: GET https://api.hotel.com/rooms/205/availability

Përgjigja e mapuar: room_available = true, price = "€120/natë"

AI përgjigjet: "Dhoma 205 është e disponueshme javën tjetër për €120/natë. Dëshironi ta rezervoni?"

Vendosja e një lidhjeje

Shko te Cilësimet → Lidhjet API në dashboard-in tënd.

1. Krijo një lidhje

Një lidhje përfaqëson një API të jashtëm. Ju nevojiten:

Fusha	Përshkrimi	Shembull
Emri	Një etiketë për këtë lidhje	API i rezervimit të hotelit
URL bazë	URL rrënjësor i API-t	`https://api.hotel.com/v1`
Lloji i Auth	Si të autentifikoni	Bearer Token, OAuth2, etj.

2. Llojet e autentifikimit

Asnjë

Për API publikë që nuk kërkojnë autentifikim.

Çelës API

Dërgon një çelës statik si header ose parametër query.

Fusha	Përshkrimi
Çelësi	Vlera e çelësit tuaj API
Emri i header-it	Header për të përdorur (paracaktuar: `X-Api-Key`)

Çelësi dërgohet si: X-Api-Key: your_key_here

Bearer Token

Dërgon një token statik në header-in Authorization.

Dërgohet si: Authorization: Bearer your_token_here

Basic Auth

Dërgon username dhe fjalëkalim, të koduar në base64.

Dërgohet si: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

Merr një access token automatikisht dhe e ruan në cache deri në skadim. Më e mira për API moderne si Salesforce, Google ose servera OAuth të personalizuar.

Fusha	Përshkrimi
Token URL	Endpoint i token-it OAuth (p.sh. `https://auth.example.com/oauth/token`)
Client ID	Client ID-ja juaj OAuth
Client Secret	Client secret-i juaj OAuth
Scope	Scope të ndarë me hapësira (p.sh. `read write`)

enuchat trajton ciklin e jetës së token-it automatikisht — merr në thirrjen e parë, ruan në cache deri në skadim, rifreskon kur nevojitet.

Siguria: Të gjitha kredencialet janë të enkriptuara në prehje duke përdorur libsodium. Ato nuk ekspozohen kurrë në përgjigjet API — vetëm vlerat e maskuara shfaqen në dashboard.

Konfigurimi i endpoint-eve

Çdo lidhje mund të ketë shumë endpoint-e — thirrje specifike API që dëshironi të bëni.

Fusha	Përshkrimi	Shembull
Emri	Etiketë për këtë endpoint	Kontrollo disponueshmërinë
Metoda	Metoda HTTP	GET, POST, PUT, DELETE
Rruga	Rruga URL (e shtuar te URL bazë). Përdor `{'{'}variable}` për vlera dinamike	`/rooms/{'{'}roomId}/availability`
Query Params	Parametrat URL si çifte çelës-vlerë. Vlerat mbështesin `{'{'}variable}`	`date={'{'}checkIn}`
Shablloni i trupit	Trupi JSON për POST/PUT. Mbështet interpolimin `{'{'}variable}`	`{'{'}"guest": "{'{'}name}"}`
Mapimi i përgjigjes	Mapo fushat e përgjigjes JSON te variablat e sesionit duke përdorur shënimin me pikë	`data.available → room_available`
Përshkrimi	Kontekst për AI (çfarë të dhënash kthen ky endpoint)	Kthen disponueshmërinë dhe çmimin e dhomës

Interpolimi i variablave

Përdor {'{'}variableName} në rrugë, parametra query dhe shabllone trupi. Variablat vijnë nga:

Variablat e sesionit — të vendosura nga rregulla të mëparshme (veprimi SET_VARIABLE)
Parametrat e veprimit — të fiksuar në veprimin e rregullës CALL_API

Mapimi i përgjigjes

Mapo fushat e përgjigjes JSON te variablat e sesionit duke përdorur shënimin me pikë:

// API returns:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Mapping:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

Variablat e mapuara ruhen si variabla sesioni në bisedë dhe janë të disponueshme për AI për të gjeneruar përgjigje.

Përdorimi me rregullat

Thirrjet API aktivizohen nga veprimi CALL_API në rregulla. Mund t'i kombinoni me veprime të tjera.

Receta: Kërkimi i statusit të porosisë

Lidhja: Order Management API — https://api.shop.com/v2 — Bearer Token

Endpoint: GET /orders/{'{'}orderId} → mapon data.status → order_status, data.eta → delivery_eta

Rregulla (lloji AI): "Kur vizitori pyet për statusin e porosisë ose dorëzimin"

Veprimet:

CALL_API → Endpoint-i Order Status
REPLY_AI → AI përdor order_status dhe delivery_eta për t'u përgjigjur

Rezultati: Vizitori: "Ku është porosia ime #4521?" — AI: "Porosia juaj #4521 është aktualisht duke u dërguar dhe duhet të mbërrijë të enjten."

Receta: Çmimet në kohë reale

Lidhja: Pricing API — https://pricing.example.com — Çelës API

Endpoint: GET /products/{'{'}productId}/price → mapon price → current_price, currency → price_currency

Rregulla (statike): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Veprimet:

CALL_API → Endpoint-i Pricing
REPLY_TEXT → "Çmimi aktual është {'{'}current_price} {'{'}price_currency}."

Testimi

Gjithmonë testoni lidhjet dhe endpoint-et tuaja para se t'i përdorni në rregulla:

Test i lidhjes — verifikon që autentifikimi funksionon (për OAuth2: merr një token)
Test i endpoint-it — bën një thirrje reale API me variabla shembull dhe tregon përgjigjen
Test i rregullës (dry-run) — në faqen Rregullat, testo nëse një rregull do të përputhej dhe cilat veprime do të ekzekutoheshin

Këshillë: Fillo duke testuar lidhjen, pastaj çdo endpoint, pastaj rregullën e plotë. Në këtë mënyrë mund të izolosh problemet në çdo nivel.

Siguria

Enkriptim në prehje — të gjitha kredencialet janë të enkriptuara duke përdorur libsodium para ruajtjes
Nuk ekspozohen kurrë — përgjigjet API nuk përfshijnë kurrë kredencialet e dekriptuara, vetëm vlerat e maskuara
Mbrojtje SSRF — enuchat bllokon thirrjet te localhost, IP private dhe hostname të brendshëm
Timeout — thirrjet e API-ve të jashtme kanë një timeout 5-sekondësh për të parandaluar varjen
Cache e token-it OAuth2 — token-et e aksesit ruhen në cache në mënyrë të sigurt dhe rifreskohen automatikisht
Izolim tenant-i — lidhjet janë të kufizuara për tenant-in tuaj, të paarritshme për të tjerët

Gati për të lidhur API-të tuaja?

Fillo të integrosh sistemet e tua me enuchat sot.

Fillo falas