Conexiuni API

Conectează API-urile externe la enuchat astfel încât AI-ul și regulile să poată prelua date în timp real din sistemele tale.

Cum funcționează

Conexiunile API îți permit să integrezi enuchat cu propriile sisteme backend — motoare de rezervare, CRM-uri, gestionarea comenzilor, inventar și altele. Când un vizitator pune o întrebare, enuchat poate apela API-ul tău pentru a obține date reale și a le include în răspuns.

Fluxul

Configurează o conexiune — URL-ul de bază al API-ului și autentificare
Adaugă endpoint-uri — apeluri API specifice cu șabloane de cale și maparea răspunsului
Creează o regulă — o regulă AI sau statică cu o acțiune CALL_API
Vizitatorul pune o întrebare — regula se declanșează, apelează API-ul, mapează răspunsul la variabilele de sesiune
AI-ul răspunde cu date reale — variabilele de sesiune sunt disponibile AI-ului pentru a genera un răspuns precis

Exemplu: Disponibilitate cameră hotel

Vizitator: «Camera 205 este disponibilă săptămâna viitoare?»

Regula AI se potrivește: «Când vizitatorul întreabă despre disponibilitatea camerei»

Acțiune CALL_API: GET https://api.hotel.com/rooms/205/availability

Răspuns mapat: room_available = true, price = «120€/noapte»

AI-ul răspunde: «Camera 205 este disponibilă săptămâna viitoare la 120€/noapte. Dorești să o rezervi?»

Configurarea unei conexiuni

Mergi la Setări → Conexiuni API în dashboard.

1. Creează o conexiune

O conexiune reprezintă un API extern. Ai nevoie de:

Câmp	Descriere	Exemplu
Nume	O etichetă pentru această conexiune	API rezervare hotel
URL de bază	URL-ul rădăcină al API-ului	`https://api.hotel.com/v1`
Tip Auth	Cum se autentifică	Bearer Token, OAuth2, etc.

2. Tipuri de autentificare

Niciuna

Pentru API-uri publice care nu necesită autentificare.

Cheie API

Trimite o cheie statică ca header sau parametru query.

Câmp	Descriere
Cheie	Valoarea cheii API
Nume header	Header de folosit (implicit: `X-Api-Key`)

Cheia este trimisă ca: X-Api-Key: your_key_here

Bearer Token

Trimite un token static în header-ul Authorization.

Trimis ca: Authorization: Bearer your_token_here

Basic Auth

Trimite utilizator și parolă, codificate în base64.

Trimis ca: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

Preia un access token automat și îl cache-uiește până la expirare. Cel mai bun pentru API-uri moderne precum Salesforce, Google sau servere OAuth personalizate.

Câmp	Descriere
Token URL	Endpoint token OAuth (ex. `https://auth.example.com/oauth/token`)
Client ID	ID-ul clientului OAuth
Client Secret	Secretul clientului OAuth
Scope	Scope-uri separate prin spații (ex. `read write`)

enuchat gestionează ciclul de viață al token-ului automat — preia la primul apel, cache-uiește până la expirare, reînnoiește când este necesar.

Securitate: Toate credențialele sunt criptate în repaus folosind libsodium. Nu sunt expuse niciodată în răspunsurile API — doar valori mascate sunt afișate în dashboard.

Configurarea endpoint-urilor

Fiecare conexiune poate avea mai multe endpoint-uri — apeluri API specifice pe care vrei să le faci.

Câmp	Descriere	Exemplu
Nume	Etichetă pentru acest endpoint	Verifică disponibilitatea
Metodă	Metodă HTTP	GET, POST, PUT, DELETE
Cale	Calea URL (adăugată la URL-ul de bază). Folosește `{'{'}variable}` pentru valori dinamice	`/rooms/{'{'}roomId}/availability`
Parametri query	Parametri URL ca perechi cheie-valoare. Valorile acceptă `{'{'}variable}`	`date={'{'}checkIn}`
Șablon corp	Corp JSON pentru POST/PUT. Acceptă interpolare `{'{'}variable}`	`{'{'}"guest": "{'{'}name}"}`
Mapare răspuns	Mapează câmpurile răspunsului JSON la variabile de sesiune folosind notația cu punct	`data.available → room_available`
Descriere	Context pentru AI (ce date returnează acest endpoint)	Returnează disponibilitatea și prețul camerei

Interpolarea variabilelor

Folosește {'{'}variableName} în căi, parametri query și șabloane de corp. Variabilele provin din:

Variabile de sesiune — setate de reguli anterioare (acțiunea SET_VARIABLE)
Parametri de acțiune — hardcoded în acțiunea regulii CALL_API

Maparea răspunsului

Mapează câmpurile răspunsului JSON la variabile de sesiune folosind notația cu punct:

// 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"

Variabilele mapate sunt stocate ca variabile de sesiune pe conversație și sunt disponibile AI-ului pentru generarea răspunsurilor.

Utilizare cu reguli

Apelurile API sunt declanșate de acțiunea CALL_API în reguli. Le poți combina cu alte acțiuni.

Rețetă: Căutare stare comandă

Conexiune: API gestionare comenzi — https://api.shop.com/v2 — Bearer Token

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

Regulă (tip AI): «Când vizitatorul întreabă despre starea comenzii sau livrare»

Acțiuni:

CALL_API → endpoint stare comandă
REPLY_AI → AI-ul folosește order_status și delivery_eta pentru a răspunde

Rezultat: Vizitator: «Unde este comanda mea #4521?» — AI: «Comanda ta #4521 este în prezent în curs de expediere și ar trebui să ajungă până joi.»

Rețetă: Prețuri în timp real

Conexiune: API de prețuri — https://pricing.example.com — Cheie API

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

Regulă (statică): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Acțiuni:

CALL_API → endpoint prețuri
REPLY_TEXT → «Prețul curent este {'{'}current_price} {'{'}price_currency}.»

Testare

Testează întotdeauna conexiunile și endpoint-urile înainte de a le folosi în reguli:

Testează conexiunea — verifică dacă autentificarea funcționează (pentru OAuth2: preia un token)
Testează endpoint-ul — efectuează un apel API real cu variabile de mostră și afișează răspunsul
Testează regula (dry-run) — pe pagina Reguli, testează dacă o regulă s-ar potrivi și ce acțiuni s-ar executa

Sfat: Începe prin testarea conexiunii, apoi a fiecărui endpoint, apoi a regulii complete. Așa poți izola problemele la fiecare nivel.

Securitate

Criptare în repaus — toate credențialele sunt criptate folosind libsodium înainte de stocare
Niciodată expuse — răspunsurile API nu includ niciodată credențiale decriptate, doar valori mascate
Protecție SSRF — enuchat blochează apelurile către localhost, IP-uri private și nume de host interne
Timeout — apelurile API externe au un timeout de 5 secunde pentru a preveni blocările
Caching token OAuth2 — access token-urile sunt cache-uite în siguranță și reînnoite automat
Izolare tenant — conexiunile sunt scopate la tenant-ul tău, inaccesibile altora

Gata să-ți conectezi API-urile?

Începe astăzi să-ți integrezi sistemele cu enuchat.

Începe gratuit