Connexions API

Connecta les teves APIs externes a enuchat perquè la IA i les regles puguin obtenir dades en temps real dels teus sistemes.

Com funciona

Les connexions API et permeten integrar enuchat amb els teus propis sistemes backend — motors de reserva, CRMs, gestió de comandes, inventari i més. Quan un visitant fa una pregunta, enuchat pot cridar la teva API per obtenir dades reals i incloure-les a la resposta.

El flux

Configura una connexió — la URL base i autenticació de la teva API
Afegeix endpoints — crides API específiques amb plantilles de ruta i mapeig de resposta
Crea una regla — una regla d'IA o estàtica amb una acció CALL_API
El visitant fa una pregunta — la regla es dispara, crida la teva API, mapeja la resposta a variables de sessió
La IA respon amb dades reals — les variables de sessió estan disponibles per a la IA per generar una resposta precisa

Exemple: Disponibilitat d'habitació d'hotel

Visitant: "L'habitació 205 està disponible la setmana que ve?"

Coincideix la regla d'IA: "Quan el visitant pregunta sobre disponibilitat d'habitació"

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

Resposta mapejada: room_available = true, price = "120 €/nit"

La IA respon: "L'habitació 205 està disponible la setmana que ve a 120 €/nit. Vols reservar-la?"

Configurant una connexió

Vés a Configuració → Connexions API al teu panell.

1. Crea una connexió

Una connexió representa una API externa. Necessites:

Camp	Descripció	Exemple
Nom	Una etiqueta per a aquesta connexió	API de reserves d'hotel
URL base	L'URL arrel de l'API	`https://api.hotel.com/v1`
Tipus d'auth	Com autenticar	Token Bearer, OAuth2, etc.

2. Tipus d'autenticació

Cap

Per a APIs públiques que no requereixen autenticació.

Clau API

Envia una clau estàtica com a capçalera o paràmetre de consulta.

Camp	Descripció
Clau	El valor de la teva clau API
Nom de capçalera	Capçalera a utilitzar (per defecte: `X-Api-Key`)

La clau s'envia com: X-Api-Key: your_key_here

Token Bearer

Envia un token estàtic a la capçalera Authorization.

Enviat com: Authorization: Bearer your_token_here

Auth bàsica

Envia nom d'usuari i contrasenya, codificats en base64.

Enviat com: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Credencials de client)

Obté un token d'accés automàticament i el guarda fins a la caducitat. Millor per a APIs modernes com Salesforce, Google o servidors OAuth personalitzats.

Camp	Descripció
URL del token	Endpoint de token OAuth (p. ex. `https://auth.example.com/oauth/token`)
ID del client	El teu ID de client OAuth
Secret del client	El teu secret de client OAuth
Abast	Abasts separats per espais (p. ex. `read write`)

enuchat gestiona el cicle de vida del token automàticament — obté a la primera crida, guarda fins a la caducitat, refresca quan cal.

Seguretat: Totes les credencials estan xifrades en repòs utilitzant libsodium. Mai s'exposen a les respostes d'API — només es mostren valors emmascarats al panell.

Configurant endpoints

Cada connexió pot tenir múltiples endpoints — crides API específiques que vols fer.

Camp	Descripció	Exemple
Nom	Etiqueta per a aquest endpoint	Comprova disponibilitat
Mètode	Mètode HTTP	GET, POST, PUT, DELETE
Ruta	Ruta URL (afegida a la URL base). Utilitza `{'{'}variable}` per a valors dinàmics	`/rooms/{'{'}roomId}/availability`
Paràmetres de consulta	Paràmetres URL com a parells clau-valor. Els valors admeten `{'{'}variable}`	`date={'{'}checkIn}`
Plantilla del cos	Cos JSON per a POST/PUT. Admet interpolació de `{'{'}variable}`	`{'{'}"guest": "{'{'}name}"}`
Mapeig de resposta	Mapeja camps de resposta JSON a variables de sessió utilitzant notació de punt	`data.available → room_available`
Descripció	Context per a la IA (quines dades retorna aquest endpoint)	Retorna disponibilitat d'habitació i preus

Interpolació de variables

Utilitza {'{'}variableName} a rutes, paràmetres de consulta i plantilles de cos. Les variables vénen de:

Variables de sessió — establertes per regles anteriors (acció SET_VARIABLE)
Paràmetres d'acció — codificats a la regla d'acció CALL_API

Mapeig de resposta

Mapeja camps de resposta JSON a variables de sessió utilitzant notació de punt:

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

Les variables mapejades s'emmagatzemen com a variables de sessió a la conversa i estan disponibles per a la IA per generar respostes.

Utilitzant amb regles

Les crides API es desencadenen per l'acció CALL_API a les regles. Pots combinar-les amb altres accions.

Recepta: Cerca d'estat de comanda

Connexió: API de gestió de comandes — https://api.shop.com/v2 — Token Bearer

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

Regla (tipus IA): "Quan el visitant pregunta sobre l'estat de la seva comanda o lliurament"

Accions:

CALL_API → endpoint d'estat de comanda
REPLY_AI → la IA utilitza order_status i delivery_eta per respondre

Resultat: Visitant: "On és la meva comanda #4521?" — IA: "La teva comanda #4521 està actualment sent enviada i hauria d'arribar el dijous."

Recepta: Preus en temps real

Connexió: API de preus — https://pricing.example.com — Clau API

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

Regla (estàtica): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Accions:

CALL_API → endpoint de preus
REPLY_TEXT → "El preu actual és {'{'}current_price} {'{'}price_currency}."

Proves

Sempre prova les teves connexions i endpoints abans d'utilitzar-los a regles:

Prova de connexió — verifica que l'autenticació funciona (per a OAuth2: obté un token)
Prova d'endpoint — fa una crida API real amb variables de mostra i mostra la resposta
Prova de regla (assaig) — a la pàgina de Regles, prova si una regla coincidiria i quines accions s'executarien

Consell: Comença provant la connexió, després cada endpoint, després la regla completa. D'aquesta manera pots aïllar problemes a cada nivell.

Seguretat

Xifrat en repòs — totes les credencials es xifren utilitzant libsodium abans de l'emmagatzematge
Mai exposades — les respostes d'API mai inclouen credencials desxifrades, només valors emmascarats
Protecció SSRF — enuchat bloqueja crides a localhost, IPs privades i noms d'amfitrió interns
Temps d'espera — les crides API externes tenen un temps d'espera de 5 segons per evitar penjades
Memòria cau de tokens OAuth2 — els tokens d'accés es guarden de manera segura i es refresquen automàticament
Aïllament de tenant — les connexions estan limitades al teu tenant, inaccessibles per a altres

Preparat per connectar les teves APIs?

Comença a integrar els teus sistemes amb enuchat avui.

Comença gratis