Dokumentacija | AivaShop

Početak

Nalog otvarate sami, u panelu AivaShopa, na stranici Otvorite nalog. Upisujete naziv prodavnice, adresu sajta, vaše ime, email i lozinku od najmanje 8 znakova. Adresu sajta možete dodati i kasnije.

Posle prve prijave panel vas vodi kroz tri koraka:

Uvezite proizvode. Agent preporučuje samo ono što je u katalogu.
Nalijepite kod na sajt. Na svaku stranicu, tik prije zatvaranja taga </body>.
Probajte ga. Pitajte agenta ono što pitaju vaši kupci.

Prije nego što agenta pustite kupcima, u Podešavanja upišite Radno vrijeme i Kontakt telefon. Agent ih kaže kupcu kad ga pita.

Ugradnja na sajt

Kod je u panelu, u meniju Widget / Integracija, u kartici Kod za ugradnju, sa dugmetom za kopiranje. Izgleda ovako:

<script>
  window.AivaShopApiKey='VAŠ_KLJUČ';
</script>
<script src="https://aivashop.me/widget.js" data-aiva-shop-api-key="VAŠ_KLJUČ" defer></script>

U panelu je kod već popunjen vašim ključem. Nalijepite ga na svaku stranicu sajta, tik prije </body>. Na WordPressu to može biti footer teme ili dodatak za umetanje koda.

Domene i ključ

Ključ ima primarna domena. Dodajete je u kartici Domene, dugmetom + Dodaj domenu.
Domenu upišite bez https:// i bez www, na primjer vasa-prodavnica.me.
Dugme Novi ključ izdaje novi ključ, a stari odmah prestaje da radi. Posle toga zamijenite kod na sajtu.

Izgled i pozdrav

U Podešavanja, kartica Widget izgled:

primarna boja, stil (Aurora, Minimal, Soft ili Bold) i dugme za otvaranje: maskota, znak brenda ili ikona chata;
logo asistenta: SVG, PNG, WEBP ili JPG do 512 KB, ili adresa slike preko https;
pozicija (dolje desno, lijevo ili po sredini), veličina (Standard, Comfort ili Fullscreen na desktopu) i tema (dnevna, tamna ili po sistemu).

Pregled se mijenja dok birate. Izmjene sačuvajte dugmetom Sačuvaj.

Pozdravna poruka je prva poruka koju kupac vidi. Na druge jezike prevodi se sama, jednom, i taj prevod se čuva.
Lead forma prije novog chata: ako označite ime, prezime, email ili telefon kao obavezne, kupac ih upisuje prije prvog pitanja, a kontakt stiže u Leadovi.
U Brendiranje mijenjate naziv koji widget prikazuje u zaglavlju i možete sakriti oznaku „Pokreće Aiva AI“.

Katalog proizvoda

Proizvodi se uvoze u meniju Proizvodi, u kartici Uvoz kataloga, na jedan od tri načina.

Iz fajla

Excel (.xlsx ili .xlsm) ili CSV, do 20 MB i 50.000 redova. Kolone se prepoznaju same, a možete ih i sami povezati: Naziv i Cijena su obavezne, a tu su i Akcijska cijena, Šifra, Barkod, Stanje, Brend, Kategorija, Podkategorija, Opis, Slika i Link. Prije uvoza vidite pregled prvih redova. Dugme Preuzmi predložak daje prazan fajl sa kolonama, a Izvezi trenutni katalog ono što je već u AivaShopu.

Sa feed adrese

Google Merchant ili XML feed, do 40 MB: Provjeri, pa Uvezi. Uvoz je jednokratan. Kad se ponuda promijeni, pokrenite ga ponovo.

Ručno

Dugme + Novi proizvod za pojedinačne artikle. Više artikala odjednom možete aktivirati, deaktivirati, označiti da su ili nisu na stanju, premjestiti u kategoriju ili obrisati.

Pravila uvoza

Proizvod se prepoznaje po šifri, pa po barkodu, pa ponovni uvoz ažurira postojeće proizvode umjesto da ih duplira.
Prazna ćelija ne briše podatak koji već postoji.
Proizvod bez podatka o stanju smatra se dostupnim.
Red bez naziva ili cijene se preskače, uz poruku koji je red u pitanju.

Kad kupac upiše barkod ili šifru, agent traži tačno taj proizvod. Iz pretraga koje više puta ništa nisu našle sistem sam uči druge nazive za vaše proizvode.

Šta agent zna

O proizvodima agent zna ono što je u katalogu. O prodavnici zna ono što upišete na dva mjesta.

Baza znanja

Pitanja i odgovori po kategorijama: FAQ, dostava, garancija, povrat, plaćanje i druge, sa prioritetom. Unos može i glasom: izgovorite pravilo, a AI strukturiraj i sačuvaj ga pretvori u pitanje i odgovor i upozori ako slično već postoji. Adrese, telefone i radno vrijeme agent uzima samo odavde i iz podešavanja.

Podešavanja

Radno vrijeme i Kontakt telefon. Ako polje ostavite prazno, agent kupcu kaže da tu informaciju nema.
Dostava, Načini plaćanja i Plaćanje na rate, opisani pod Korpa i narudžbe.
System Prompt (Custom Instructions): dodatna uputstva agentu, na primjer kako da se obraća kupcima ili šta da naglasi.
AI podešavanja: koji model odgovara, Claude, OpenAI ili Gemini. Ako upišete svoj ključ za OpenAI ili Gemini, taj dio ide preko vašeg naloga kod njih.

Promo kodovi i dodaci

U Promo kodovi pravite kod sa popustom u procentima ili u eurima, uz najmanji iznos korpe, broj korišćenja i period važenja. Kod se provjerava kad se narudžba pravi.
Kad kupac doda proizvod u korpu, widget jednom u razgovoru predloži do tri dodatka iz vaše ponude koji su na stanju.
Na stranici proizvoda widget zna koji je to proizvod, pa kupac može da pita „ima li jeftinije“ bez objašnjavanja. Posle nekoliko sekundi ponudi i sam pomoć oko izbora.

Jezici

Agent odgovara na jeziku na kojem kupac piše. U Podešavanja, Jezik agenta, birate da li widget prati jezik posjetioca ili je uvijek na jednom jeziku. To određuje pozdrav, dugmad i forme. Widget postoji na crnogorskom, engleskom, njemačkom, ruskom i albanskom.

Kad kupac piše na drugom jeziku, widget mu jednom ponudi da cijeli chat prebaci na taj jezik. Razgovori na Telegramu, WhatsAppu i telefonu počinju na jeziku prodavnice.

Korpa i narudžbe

Agent prikazuje proizvode kao kartice sa cijenom, stanjem i dugmadima Dodaj u korpu i Pogledaj na sajtu. Kad kupac želi da naruči, u widgetu dobija formu: ime i prezime, telefon, email, promo kod, način dostave, adresa, grad, poštanski broj, način plaćanja i napomena. Na Telegramu, WhatsAppu i telefonu agent ista pitanja postavlja jedno po jedno i potvrđuje ih prije narudžbe.

Dostava. U Podešavanja, Dostava, birate koje načine nudite: lično preuzimanje, kurirsku dostavu i poštu. Za svaki upisujete cijenu, i po želji iznos od kog je dostava besplatna. Agent kupcu navodi te cijene, a ukupno na narudžbi se po njima računa. Za način bez upisane cijene ukupno je bez dostave, a agent kupcu kaže da cijenu javlja prodavnica.
Plaćanje. AivaShop ne naplaćuje kupca. U Podešavanja birate koje načine plaćanja nudite: pouzeće, bankovni transfer ili platnu karticu. Naplata ide između vas i kupca.
Plaćanje na rate. Isključeno je dok ga u Podešavanja ne uključite i ne upišete svoje uslove: od koje cijene, na koliko rata i za koliko je cijena na rate veća. Agent tada kupcu navodi te uslove.
Broj narudžbe. Oblik je AB-2026-00001, sa brojačem po godini. Slova birate u Podešavanja, polje Slova ispred broja narudžbe, od 2 do 5 slova. Dok ih ne izaberete, uzimaju se iz naziva prodavnice pri prvoj narudžbi. Već izdati brojevi se ne mijenjaju.
Status. Kupac može u razgovoru da pita za narudžbu po broju, i sa malim slovima ili bez slova.
Panel. Narudžbe su u meniju Narudžbe, a broj novih piše pored menija. Status mijenjate tamo. O promjeni statusa kupca obavještavate vi.

Narudžbe iz razgovora ostaju u panelu. U vaš sistem prodaje ih prenosite vi.

Telegram i WhatsApp

Kanali se povezuju u meniju Kanali i telefon. Sačuvane tokene panel više ne prikazuje. Dugme Isključi gasi kanal, a pristupni podaci ostaju.

Na Telegramu, kod @BotFather, napravite bota i kopirajte token.
Nalijepite ga u polje Bot token.
Kliknite Poveži. Webhook i meni komandi podešavaju se sami.

WhatsApp (Cloud API)

Iz Meta naloga za programere upišite Access token i Phone number ID, po želji i App secret.
U polje Verify token upišite riječ koju sami izmislite.
Kliknite Poveži. Panel prikaže Callback URL i Verify token koje upisujete u Meta dashboard, sa webhook poljem messages.

Meta dozvoljava odgovor kupcu 24 sata od njegove posljednje poruke. Postoji i povezivanje preko open-wa mosta, ali je ono nezvanično i broj može biti blokiran.

Komande

/korpa prikazuje korpu, /narudzba počinje narudžbu, /ponisti prazni korpu.
/pomoc kaže šta bot sve može.
/stop gasi podsjetnike, a /start ili /nastavi ih vraća.

Podsjetnik na ostavljenu korpu stiže jednom, samo na Telegramu i WhatsAppu: ako kupac nije pisao bar sat vremena, a pisao je u posljednja dva dana, između 9 i 20 časova. Ne stiže ako je kupac već naručio ili ugasio podsjetnike, ni dok razgovor vodite vi.

Fotografiju koju kupac pošalje na Telegramu agent pogleda i traži proizvod sa nje. Na WhatsAppu čita samo tekst uz fotografiju.

Glas i telefon

Glas u widgetu

Ako vaš plan uključuje glasovne minute, u zaglavlju widgeta je dugme Pozovi AI asistenta. Kupac razgovara sa agentom glasom, a agent za to vrijeme traži proizvode, puni korpu i prima narudžbu. Minuti se računaju kad se poziv završi.

Snimanje uključujete u Podešavanja, Snimanje glasovnih poziva u widgetu. Kad je uključeno, kupac prije poziva vidi da se razgovor snima, a snimak je u razgovoru u panelu, pod Audio snimci. Navedite to i u svojoj politici privatnosti. Kad je isključeno, ništa se ne snima, a prepis razgovora ostaje.

Telefonska linija

Telefon radi preko Twilija, sa vašim Twilio nalogom i brojem. U kartici Telefon upisujete Twilio Account SID, Twilio Auth Token i broj, a po želji i pozdrav, glas i broj na koji se poziv prebacuje. Poveži sam usmjeri broj na AivaShop.

Agent na telefonu govori kratko, nabraja najviše tri proizvoda, cijene izgovara riječima, a narudžbu uzima pitanje po pitanje i ponavlja broj telefona i adresu.
Kad pozivalac traži čovjeka, kad ga agent dvaput ne razumije, kod tehničke greške ili kad ste razgovor preuzeli u panelu, poziv ide na broj iz polja Prebaci na broj. Ako je polje prazno, pozivalac čuje da će mu se javiti neko iz prodavnice.
Pozivi na telefonskoj liniji se ne snimaju. U Konverzacije su kao prepis, sa brojem pozivaoca.

Razgovori i kontakti

Svi razgovori sa sajta, Telegrama, WhatsAppa i telefona su u meniju Konverzacije. Pretražujete ih po imenu, emailu, telefonu ili tekstu poruke, a filtrirate po izvoru, jeziku, datumu, broju poruka i tome da li je kupac ostavio kontakt. Razgovor nosi ime kupca ili naslov iz njegovog prvog pitanja. Lista se osvježava sama.

Dugmetom ⚡ Preuzmi razgovor preuzimate vi: agent ne odgovara dok ga ne vratite dugmetom Vrati AI-u, ni u chatu na sajtu, ni na Telegramu i WhatsAppu, ni na telefonskoj liniji. Poruke kupca i dalje stižu u panel kao nepročitane, a kupac u chatu vidi da je razgovor preuzela osoba iz prodavnice.

U razgovoru možete i:

pisati kupcu kao operater;
naći artikal po nazivu, brendu, šifri ili barkodu i dodati ga u kupčevu korpu;
od korpe napraviti narudžbu;
pozvati kupca glasom u widgetu, dugmetom Pokreni poziv, kad kupac to dozvoli u pregledaču; ti pozivi se ne snimaju;
prikazati samo prepis razgovora ili zatvoriti chat.

Razgovore možete arhivirati i obrisati. Brisanje je trajno, briše i slike i snimke iz razgovora, i ne važi za razgovor koji ima narudžbu.

Leadovi

U Leadovi su kontakti: iz forme prije chata, sa Telegrama, iz svake narudžbe i oni koje dodate ručno. Svakom dajete status i zaduženu osobu, a iz kartice kontakta mu šaljete email ili poruku na Telegramu i bilježite pozive. U Podešavanja birate da li vas o novom kontaktu obavještava panel, email ili oba.

Analitika i tržište

Analitika

Razgovori, poruke, narudžbe iz razgovora i prihod, za posljednjih 7, 14, 30 ili 90 dana, uz najtraženije proizvode i najčešća pitanja.

Dio Koliko je agent donio poredi narudžbe sa vašeg sajta: one čiji je kupac u prethodnih sedam dana, u istom pregledaču, pisao agentu, i sve ostale. Da bi radio, sajt mora da javi svaku narudžbu, vidite Za developere.

Konkurencija i tržište

U Konkurencija dodajete prodavnice sa kojima se poredite, i kako se sa njihovih stranica čita cijena: automatski ili CSS selektorom. Cijenu sa stranice koju gledate možete sačuvati i dugmetom „uzmi cijenu“ u pregledaču.
Artikli sa istim barkodom uparuju se sami. Uparivanje po modelu ili prijedlog AI-a čeka vašu potvrdu.
Tržište pokazuje gdje ste najjeftiniji, gdje možete podići cijenu, gdje ste najskuplji, šta konkurencija ima a vi nemate, i šta su kupci tražili u razgovorima a nisu našli. Tu su i savjetnik koji odgovara na pitanja o ovim brojevima, tekstovi za kampanje i izvoz u Excel.
Izvještaj sedmice stiže ponedjeljkom ujutru, u panel i na email, ako imate bar jedan izvor konkurencije.
U Podešavanja, Poruka o cijeni na stranici artikla, možete kupcu pokazati koliko ste povoljniji. Poruka se prikazuje samo kad je cijena konkurencije potvrđena, dovoljno svježa i razlika veća od praga koji zadate.

Tim i pretplata

Korisnike dodajete u meniju Korisnici: ime, email, lozinka i uloga. Svi korisnici prodavnice zasad imaju pristup cijelom panelu.
Planovi i cijene su na stranici Cijene. Plan birate u meniju Pretplata, a plaćate preko Stripea. Potrošnju pratite u Korišćenje, a račune u Fakture. Za otkazivanje nam se javite.
Kad plan ne uključuje glas ili slanje slika, ili su minuti potrošeni, widget te dugmadi ne prikazuje.

Šta widget čuva u pregledaču

Widget ne postavlja kolačiće. U lokalnom skladištu pregledača, na vašem sajtu, čuva ovo:

Ključ	Čemu služi	Koliko traje
`tp_visitor_id`	Nasumični identifikator posjetioca, da se razgovor nastavi i da se prodaja pripiše razgovoru	Dok ga kupac ne obriše
`tp_chat_session`	Trenutni razgovor	Dok se razgovor ne zatvori
`tp_chat_session_closed`	Oznaka da je razgovor zatvoren	Dok ga kupac ne obriše
`tp_chat_proactive_seen:…`	Da se ista ponuda pomoći ne prikaže ponovo	7 dana
`aiva_locale_choice`	Jezik koji je kupac izabrao	Dok ga kupac ne obriše

Navedite ih u svojoj politici privatnosti ili politici kolačića. Šta AivaShop radi sa podacima vaših kupaca piše u ugovoru o obradi podataka.

Za developere

Podešavanja na stranici

Umjesto koda iz panela, widget se može podesiti i objektom na stranici. Ono što napišete ovdje ima prednost nad panelom, osim logotipa.

<script>
  window.AivaShopChat = {
    widgetKey: 'VAŠ_KLJUČ',
    position: 'bottom-left',   // ili 'bottom-right'
    size: 'comfort',           // 'standard', 'comfort' ili 'fullscreen'
    theme: 'auto',             // 'light', 'dark' ili 'auto'
    language: 'en',
    primaryColor: '#5b2bff'
  };
</script>

Prodaja sa sajta

Na stranici zahvalnice posle kupovine pozovite ovo za svaku narudžbu, i za one o kojima kupac nije pričao sa agentom: one su poređenje koje ostalim brojevima daje smisao. Dvostruki poziv za isti broj narudžbe je bezbjedan.

<script>
  AivaShop.orderCompleted({ ref: '12345', total: 1392, currency: 'EUR' });
</script>

Katalog preko API-ja

Ključ izdajete u Proizvodi → Uvoz kataloga, na tabu WooCommerce, dugmetom Izdaj ključ. Ključ se prikazuje jednom, uz ID prodavnice i adresu API-ja. Može samo da upisuje katalog, a novi ključ gasi prethodni.

POST https://aivashop.me/api/store/catalogue/push
Authorization: Bearer VAŠ_KLJUČ_ZA_POVEZIVANJE
X-Tenant-ID: ID_PRODAVNICE
Content-Type: application/json

{
  "products": [
    {
      "sku": "TV-55-001",
      "ean": "3800000000017",
      "name": "Televizor 55 inča 4K",
      "price": 599,
      "sale_price": 549,
      "stock_quantity": 4,
      "brand": "Primjer",
      "category": "Televizori",
      "url": "https://vasa-prodavnica.me/televizor-55",
      "images": ["https://vasa-prodavnica.me/slike/tv-55.jpg"]
    }
  ]
}

Do 200 proizvoda po zahtjevu. Obavezni su name i price.
Ostala polja: sku, ean, description, short_description, brand, category, subcategory, sale_price, stock_quantity, url, images i currency.
Važe ista pravila kao za uvoz iz fajla. Odgovor kaže koliko je proizvoda dodato, ažurirano i preskočeno, i zašto: created, updated, skipped, problems.

Za AI asistente

Da bi vaše proizvode našli i AI asistenti kupaca, AivaShop za svaku prodavnicu objavljuje četiri javne adrese, sa widget ključem u putanji. Spisak je u Widget / Integracija, u dijelu Za AI asistente.

/api/agent/{ključ}/feed.xml: feed proizvoda u obliku koji čitaju pretraživači;
/api/agent/{ključ}/products?q=: pretraga u JSON-u;
/api/agent/{ključ}/llms.txt: opis prodavnice za jezičke modele;
/api/agent/{ključ}/mcp: MCP server sa alatima search_products i get_product.

Kroz njih idu samo podaci o proizvodima, sa linkovima na vaš sajt, nikad podaci o kupcima, narudžbama ili razgovorima. Ograničenje je 120 zahtjeva u minuti.

Pomoć

Ako nešto ne radi kako ovdje piše, prvo pogledajte status sistema. Ako je tamo sve u redu, pišite nam kroz formu za kontakt na početnoj stranici, sa nazivom prodavnice i opisom šta se desilo.