REST · Embed · CORS

API dokumentáció

Integráld a Vondarót a weboldaladba vagy a szerveredre. Itt minden nyilvános végpont, a hitelesítés és a példakérések egy helyen vannak.

Alap URL

Az éles környezet bázis URL-je: https://vondaro.io. A példák ezt használják.

A JSON API-k CORS-t engedélyeznek a böngészős hívásokhoz (ahol releváns). A private API kulcsot soha ne tedd be frontend kódba – csak szerverről hívható.

API kulcsok (public / private)

A kulcsokat a Vondaro dashboardon, a Beágyazás menüben hozhatod létre.

Public – beágyazott scriptekhez (chat widget, embed config). A böngészőben is használható.
Private – szerveroldali integrációkhoz (pl. REST lead felvétel). Ha a kéréshez tartozik böngészős Origin fejléc, a szolgáltatás elutasítja a hívást.

Embed script (chat widget)

Illeszd be a weboldalad body végéhez. A script betölti a buborék chatet és a data-base-url alapján hívja a szervereinket.

<script
  src="https://vondaro.io/embed.js"
  data-api-key="lgp_..."
  data-base-url="https://vondaro.io"
  async
></script>

POST

/api/v1/leads

Lead létrehozása (REST)

Új leadet hoz létre a céghez társított kulcs alapján. A public kulcsnál a domain egyezés számít (kivéve, ha a scriptben ki van kapcsolva a hostname ellenőrzés).

Header: x-api-key vagy Authorization: Bearer <kulcs>, vagy JSON mező: api_key.

JSON body

body
Name	Type	Required	Description
first_name	string	yes	Keresztnév vagy keresztnév + vezetéknév.
email	string	yes	Érvényes email cím.
last_name	string	no	Vezetéknév.
phone	string	no	Telefonszám.
service	string	no	Szolgáltatás / termék rövid megnevezése.
details	string	no	Szabad szöveg; a rendszer `details.note` alatt tárolja.
source	string	no	Egyik: `form` \| `api` \| `chat` \| `manual`. Alapértelmezés: `api`.
referral_data	object	no	Forrás / UTM mezők (pl. utm_source, landing_page, referrer_url). Csak engedélyezett kulcsok.

Válasz mezők

response
Name	Type	Description
success	boolean	Sikeres mentés.
lead_id	uuid	Az új lead azonosítója.
over_limit	boolean	Ha a csomag lead limitje túllépve, a lead így is mentve, státusz: over_limit.

HTTP

400Hiányzó kötelező mező vagy érvénytelen email.
401Hiányzó vagy érvénytelen API kulcs.
403Private kulcs böngészőből, vagy nem engedélyezett origin (public).
500Szerverhiba.

cURL (private kulcs, szerverről)

curl -sS -X POST "https://vondaro.io/api/v1/leads" \
  -H "Content-Type: application/json" \
  -H "x-api-key: lgp_PRIVATE_..." \
  -d '{
    "first_name": "Péter",
    "email": "peter@example.com",
    "phone": "+36301234567",
    "service": "Térkövezés",
    "details": "40 m2, Budapest",
    "source": "api"
  }'

GET

/api/embed/config

Chat widget konfiguráció

Visszaadja a cég AI chat beállításait (üdvözlő szöveg, gyors gombok, kontakt szövegek). Csak public kulccsal.

Query paraméterek

query
Name	Type	Required	Description
api_key	string	yes	Public API kulcs.

Válasz mezők

response
Name	Type	Description
welcome_message	string	Üdvözlő üzenet.
quick_buttons	string[]	Gyors gombok feliratai.
contact_prompt_text	string \| null	Egyedi kontakt kérés szöveg.
require_phone	boolean	Kötelező-e a telefon.
gate_quote	boolean	Árajánlat kapu beállítás.
chat_theme	object \| null	Pro+: { primary_hex }. Business/Enterprise (white label): + opcionálisan accent_hex, header_title, border_radius_px (8–28), hide_powered_by. Csomagnak megfelelő mezők; egyébként null.

HTTP

400Hiányzó api_key.
401Érvénytelen kulcs.
403Private kulcs – itt nem használható.

Példa

curl -sS "https://vondaro.io/api/embed/config?api_key=lgp_..."

POST

/api/embed/chat

AI chat üzenet

Egy felhasználói üzenetet küld az AI-nak, és a válasz szöveget adja vissza. Beszélgetéshez és leadhez kapcsolódó session kezelés a szerveren történik.

JSON body

body
Name	Type	Required	Description
api_key	string	yes	Public API kulcs.
message	string	yes	Felhasználó üzenete.
session_id	string	no	Munkamenet azonosító (kliens oldalon generálható, stabil).
first_name	string	no	Ha a kontakt már megvan, add meg a pontosabb leadhez.
email	string	no	Email cím, ha már megvan.
phone	string	no	Telefon, ha megvan.
referral_data	object	no	Ugyanazok a mezők, mint a lead API-nál (engedélyezett kulcsok).

Válasz mezők

response
Name	Type	Description
reply	string	Az AI válasz szövege.
lead_id	uuid	Az aktuális lead azonosítója.
session_id	string	Session azonosító.
request_contact	boolean	Jelzi, ha a válasz alapján érdemes a kontakt adatokat kérni.

HTTP

400Hiányzó api_key vagy üzenet.
401Érvénytelen kulcs.
403Private kulcs – böngészőből nem.
500Szerverhiba.

Minimális JSON body

curl -sS -X POST "https://vondaro.io/api/embed/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "lgp_...",
    "message": "Sziasztok, árajánlatot kérnék térkövezésre.",
    "session_id": "lgp_session_abc123"
  }'

CORS és hibák

A dokumentált végpontok Access-Control-Allow-Origin: * értékkel válaszolnak a megfelelő OPTIONS preflight kérésekre.

A hibaüzenetek többsége JSON: { "error": "…" } magyar szöveggel.

Limit és válaszfejlécek (lead)

A POST /api/v1/leads sikeres válaszában a szerver opcionálisan küldi az X-Lead-Limit és X-Lead-Count fejléceket, ha a csomaghoz tartozik limit.