Integracija

Kaj dobite

• Dva ključa API, produkcijskega in testnega, na istem računu. Avtentikacija je Authorization: Bearer, OAuth ni potreben. Ključ zamenjate brez izpada, ker stari in novi delujeta hkrati; preklic velja od naslednje zahteve. Po želji ključem nastavimo rok veljavnosti.
• Paket Partner:

• MCP ali REST, z istim ključem. MCP Streamable HTTP za klepete, ki znajo MCP, in REST pod /v1/ za vse drugo, z opisom na mcp.bloki.si/docs.
• Stanje kvote v vsakem odgovoru: pri MCP v _meta.quota, pri REST v glavah X-Quota-*.
• Strukturirane zavrnitve: vsaka pove kodo in razlog, iz kode pa je jasno, ali je smiselno ponoviti. Zavrnjena zahteva ne porabi kreditov.
• Mesečno poročilo o porabi: krediti po orodjih, število vaših končnih uporabnikov in najzahtevnejši med njimi.
• Navodila za integracijo v slovenščini: endpoint, glave, omejitve, kode napak in preverjanje povezave.

Koraki

1. Pišite na info@bloki.si. Povejte, kaj je vaš izdelek in kdo so njegovi uporabniki, ali vaš klepet uporablja MCP ali boste klicali REST, kolikšen promet pričakujete (seje na dan in klici orodij na sejo) in kdo je vaša tehnična kontaktna oseba.

2. Dogovorimo se o paketu in pogojih: omejitve, mesečni krediti in cena na kredit. Obračun je po kreditih, ne po zahtevah: orodja stanejo od 1 do 25 kreditov, cena vsakega je na strani orodja in v orodju account_status.

3. Prejmete ključa po varnem kanalu, nikoli po e-pošti v čistopisu. Ključ je viden le ob izdaji, zato ga shranite takoj. Hranite ga samo na strežniku: nikoli v brskalniku, v mobilni aplikaciji ali v pozivu modela.

4. Povežite se. Endpoint MCP ima poševnico na koncu; brez nje strežnik odgovori s 307, ki mu nekateri odjemalci ne sledijo.

   MCP:   https://mcp.bloki.si/mcp/
   REST:  https://mcp.bloki.si/v1/…
   Authorization: Bearer bloki_sk_live_…

5. Pri vsaki zahtevi pošljite X-Bloki-End-User, neprozoren identifikator končnega uporabnika (do 64 znakov A–Z a–z 0–9 _ -). Isti uporabnik naj ima vedno isto vrednost. Nikoli ne pošljite e-naslova, imena ali česar koli, kar osebo identificira; priporočamo HMAC-SHA256 vašega internega ID-ja s skrivnostjo, ki jo poznate samo vi. Tako en uporabnik, ki avtomatizira vaš klepet, ne ustavi vseh drugih.

6. Navodila strežnika vključite v sistemski poziv modela. Strežnik jih pošlje ob povezavi. Bistvo: najprej razreši (find_area, find_address, resolve_property), identifikatorji so vedno nizi, statistika pride skupaj s svojim n. Na voljo sta tudi pripravljena poziva analyse_address in area_brief.

7. Obravnavajte kvoto in zavrnitve. Preveč zahtev v minuti: počakajte in ponovite. Porabljeni mesečni krediti ali orodje zunaj paketa: ne ponavljajte. Vsebinska zavrnitev, ko register na vprašanje ne odgovarja, ni napaka, ampak odgovor, ki ga prenesete uporabniku.

8. Preverite povezavo:

   curl -si https://mcp.bloki.si/v1/server-info \
     -H "Authorization: Bearer $BLOKI_KEY" \
     -H "X-Bloki-End-User: test" | grep -i '^HTTP\|^x-quota'

   Pričakovan odgovor je HTTP/2 200 z glavami X-Quota-*; 401 pomeni napačen ali preklican ključ.

Pogoji

Med strežnikom in uporabnikom je vaš model, zato pogodba vsebuje pet pravil:

• Opozorila se prenesejo. Opozoril, velikosti vzorca (n), zastavic redkih podatkov (thin) in vsebinskih zavrnitev uporabniku ne odstranite ali prikrijete. Povzetek je dovoljen, če ohrani njihov pomen.
• Navedba vira: »Vir: bloki.si (GURS, ETN in drugi javni registri)«.
• Osebni podatki. Zasebni lastniki niso prepoznavni in naslova samostojnega podjetnika strežnik po imenu ne vrne. To so lastnosti strežnika, ne nastavitve, zato uporabnikom ne obljubljate drugače.
• Ni ocena cenilca. Ocene vrednosti so statistične, z izmerjeno napako, in se ne predstavljajo kot cenitev pooblaščenega cenilca.
• Ključi so zaupni. Ob sumu razkritja nas takoj obvestite in ključ prekličemo.

Zahteva za integracijo

Pišite na info@bloki.si z zadevo »Integracija«. Odgovorimo z navodili in predlogom paketa.

Za lastno uporabo integracija ni potrebna: svojega AI asistenta povežete brezplačno v dveh minutah — glejte namestitev.