Vodiči

Povezave

Vaš AI-pomočnik (Claude, ChatGPT) in glasovni agent med klicem znata prebrati Google Koledar in Apple Calendar ter po vaši odobritvi urediti obstoječi dogodek - glasovni agent na lastnem motorju volai pa med klicem tudi neposredno poišče prost termin in sestanek takoj vpiše. Pri Applu je treba ohraniti neprozorne ID-je in paziti na ponavljajoče se serije.

Kaj zna in česa ne

• Izpiše povezane koledarje in njihove dogodke.
• Spremeni naslov, začetek ali konec obstoječega dogodka.
• Glasovni agent na lastnem motorju volai med klicem poišče prost termin in sestanek takoj vpiše.
• Poišče proste termine in ustvari sestanek tudi zunaj klica prek REST in MCP.

Ne zna

• Ne izbriše nobenega dogodka.
• Ne išče prostih terminov med več udeleženci.

Povezava računa Google

Račun Google povežete v portalu v razdelku Povezave (v angleškem meniju portala postavka „Integrations“). Ko je račun povezan, isti API-ključ prek REST in MCP vidi isto - dodatna prijava ni potrebna.

Račun lahko prekinete v portalu ali prek REST DELETE /v1/integrations/{id}. REST integracijo prekine takoj in brez dodatnega polja za potrditev, zato ga pokličite šele po izrecni odobritvi uporabnika. MCP orodja za prekinitev nima.

Apple Calendar

Povezava poteka z geslom za posamezno aplikacijo (ne z navadnim geslom Apple računa) v portalu v razdelku Podatki in integracije. Povezavo omogoča tudi REST POST /v1/integrations z {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP prijavnih podatkov ne sprejema in račun uporablja šele po povezavi.

list_calendar_events in REST GET /v1/integrations/{id}/events podpirata Apple Calendar. Vrnjeni neprozorni externalId brez sprememb posredujte kot eventId v get_calendar_event in pri urejanju; to ni iCalendar UID. Vrstica z recurring: true predstavlja celotno ponavljajočo se serijo in njeno urejanje spremeni osnovo serije, ne ene same pojavitve; posamezne izjeme ostanejo ohranjene.

calendarId mora biti eden od naslovov, ki jih vrne list_calendars - vse drugo API zavrne z napako 400 calendar_invalid_calendar.

Termini med klicem

Glasovni agent na lastnem motorju volai lahko med telefonskim klicem neposredno poišče prost termin in sestanek takoj vpiše - ne gre za AI-pomočnika v klepetu, temveč za klic, ki ga vodi glasovni agent sam. Vklopi se v urejevalniku agenta na zavihku Koledar: izberete povezavo, koledar in pravila razpoložljivosti (okna po dnevih v tednu, trajanje sestanka, rezerva med termini, najmanjši predhodni čas, obzorje iskanja).

• Deluje samo pri agentu na lastnem glasovnem motorju volai - pri agentu na ElevenLabs se nastavitev shrani in čaka na samodejni preklop motorja.
• Agent nikoli ne pove, kaj je v koledarju vpisano - le, ali je določen čas prost.
• Telefonska številka klicatelja se v dogodek vpiše le, če jo agent pozna; skrita številka pomeni dogodek brez telefona.
• Isto iskanje prostih terminov in vpis sestanka je mogoč tudi zunaj klica prek REST (POST .../availability, POST .../events) in MCP (find_free_slots, create_calendar_event).

Fakturoid in ABRA Flexi

Ta stran pokriva le koledarje. Fakturoid in ABRA Flexi se povezujeta na istem mestu (list_integrations/GET /v1/integrations, razdelek Podatki in integracije v portalu), vendar ima branje računov in njihova uporaba v opomnikih med Nalogami lasten vodič Računi.

Postopek za agenta

Urejanje dogodka ima vedno šest korakov, v tem vrstnem redu:

• 1. list_integrations - povezani koledarji in njihovi integrationId.
• 2. list_calendars - koledarji dane povezave in njihovi calendarId.
• 3. list_calendar_events, nato get_calendar_event z vrnjenim externalId kot eventId - naloži dogodek in njegov trenutni sourceRevision.
• 4. propose_calendar_update - pripravi predlog spremembe, zaenkrat ničesar ne zapiše.
• 5. Odobritev uporabnika - agent pokaže prvotne vrednosti in predlog, šele nato nadaljuje.
• 6. confirm_calendar_update s confirm: true - šele ta korak zapiše spremembo pri Google/Apple.

REST ustreznice: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, nato POST /v1/integrations/{id}/events/{eventId}/propose z {calendarId, sourceRevision, patch} in po odobritvi PATCH /v1/integrations/{id}/events/{eventId} z istimi vrednostmi in confirm: true.

Napake

• calendar_stale_revision - Dogodek se je vmes spremenil drugje - naložite ga znova (get_calendar_event) in uporabniku dajte v odobritev nov predlog.
• calendar_oauth_failed - Google je zavrnil prijavo - povezavo je treba znova vzpostaviti v portalu.
• calendar_unauthorized - Povezava ne velja več (preklican dostop, potekel žeton) - račun povežite znova.
• calendar_confirmation_required - Zapis brez confirm: true - predlog potrdite šele po odobritvi uporabnika.
• calendar_verification_failed - Zapis je uspel, a sveže branje nazaj ne ustreza poslani spremembi - stanje preverite ročno, ne urejajte znova na slepo.

Celotno tabelo z vsemi kodami najdete v razdelku Koledarji v referenci REST API in v napakah MCP.

Varnost

Dostopnih žetonov za račun Google ali Apple REST API in MCP nikoli ne vrneta, mi pa jih shranjujemo šifrirano. Apple appPassword prek REST pošljite le, kadar ga je uporabnik že varno shranil v spremenljivko okolja ali v z njim poimenovano datoteko - nikoli ga ne zahtevajte v pogovoru in ga ne ponavljajte nazaj. Integracijo prekinete v portalu ali prek REST DELETE /v1/integrations/{id} po izrecni odobritvi uporabnika; MCP prekinitve ne ponuja.