# Agent Instructions — RR Računalniške rešitve d.o.o.

This document describes how AI agents can interact with RR Računalniške rešitve d.o.o. at https://racunalniske-resitve.si/.

## What this site offers

Digital transformation for municipalities, tourism organisations and businesses: websites with a self-service admin portal, interactive maps and Geo Index KAM, e-catalogues, newsletters and systems administration. Based in Velenje, Slovenia.

## Quote-Based Model (RFQ, Not Checkout)

This site does not sell online and publishes no price list. The correct agent action is to
submit an **inquiry** (Slovene: *povpraševanje*) on behalf of your user. The provider answers
with a quote to the user's e-mail address. Do not look for a cart or checkout — there is none,
and do not invent or estimate prices when summarizing this catalog to your user.

## Read-Only Browsing (No Authentication Required)

### Site data
- Agent discovery: this document (`/agents.md`) is the canonical agent-facing description of the site.
- Content map for AI agents: https://racunalniske-resitve.si/llms.txt
- Sitemap (XML): https://racunalniske-resitve.si/sitemap.xml
- Sitemap (JSON): https://racunalniske-resitve.si/index/sitemap/sitemap.json

### Catalog data (JSON)
- Catalog item list: `GET https://racunalniske-resitve.si/katalog/api/list/{kat_id}`
- Item detail: `GET https://racunalniske-resitve.si/katalog/api/detail/{kat_id}/{kz_id}`
- Category catalogs: `GET https://racunalniske-resitve.si/katalog/api/catalogs/{master_kat_id}`

`{kat_id}` is the catalog id and `{kz_id}` the item id. Both appear in public catalog URLs of the
form `/katalog/{kat_id}/{kz_id}/{slug}` and in the list payloads. All endpoints return JSON;
errors use `{"error": "...", "success": "0"}` with an appropriate HTTP status.

Catalogs on this site you can start from:
- `GET https://racunalniske-resitve.si/katalog/api/list/2221`
- `GET https://racunalniske-resitve.si/katalog/api/list/2222`
- `GET https://racunalniske-resitve.si/katalog/api/list/2223`
- `GET https://racunalniske-resitve.si/katalog/api/list/2224`

### Events calendar (koledar prireditev)
- Human pages: https://racunalniske-resitve.si/koledar (list), https://racunalniske-resitve.si/koledar/prireditev/{event_id}/{slug} (detail)
- Embedded JSON feed: `GET https://racunalniske-resitve.si/koledar/data?from=&to=&geo_image_ids=&limit=&page=`
- Canonical public API (CORS-open, no auth for published events):
  - Calendar feed (one item per date): `GET https://o1.rr-vel.si/ords/orcl/pro/v1/events/occurrences?it=63&from=&to=&near=lat,lon&radius_km=`
  - Event detail: `GET https://o1.rr-vel.si/ords/orcl/pro/v1/events/{event_id}`
  - Series (tradition) detail: `GET https://o1.rr-vel.si/ords/orcl/pro/v1/events/series/{series_id}`

Dates are RFC3339 with the local UTC offset plus a `*_fmt` display twin. Cancelled dates ARE
returned, flagged via `status`/`status_note` — always tell the user about cancellations. Use
`updated_since=` for delta sync; numeric IDs are stable and never reused.

## Submitting an Inquiry (Agentic RFQ)

### Endpoints for this site
- Form schema: `GET https://racunalniske-resitve.si/povprasevanje/o1_schema/62`
- Submit: `POST https://racunalniske-resitve.si/povprasevanje/submit_o1/62` (`Content-Type: application/x-www-form-urlencoded`)

### Typical agent flow
1. **Discover** — read this document.
2. **Browse** — find relevant items via the catalog JSON endpoints above.
3. **Fetch the form schema** — the schema endpoint returns the field list (`fields[]` with
   `name`, `label`, `type`, `required`), GDPR consent requirements, captcha state, and a
   `csrfToken`.
4. **Submit** — POST the fields your user filled in plus `csrf_token`. The e-mail field
   (`k_eadresa`) must be the **user's real e-mail address** — the quote is sent there.
5. **Confirm to the user** — a success response means the provider will reply by e-mail.

### Important rules
- **Human consent is required.** Submit an inquiry only on an explicit user request and with
  contact data the user approved. An inquiry is a real message to a real business, not test traffic.
- **Submit only fields returned by the schema endpoint.** Do not add extra fields; submissions
  with unexpected fields are rejected as spam.
- **Carry cookies.** The schema and submit requests must share one session (cookie jar); the CSRF
  token is bound to it. On HTTP 422 with a fresh `csrf_token` in the response, retry once with the new token.
- **Plain text only.** Message fields must not contain HTML links or markup — they trigger the spam filter.
- **Respect rate limits.** Max 5 inquiry submissions per session per hour; general traffic is limited to 120 requests per minute per client. Back off on HTTP 429 — do not retry in a loop.

## Contact

- Address: Trg mladosti 6, 3320 Velenje
- Phone: +386 40 419 842
- E-mail: info@racunalniske-resitve.si

## Policies

- Terms of use, privacy and cookies: https://racunalniske-resitve.si/index/pogoji_uporabe

## Platform

This site runs on [IT-InfoTočka](https://rr-vel.si), a multi-tenant platform by RR d.o.o.
Every IT-InfoTočka tenant that publishes `/agents.md` exposes the same catalog JSON and inquiry
API shapes, so an integration built against this document works across those sites.

## Live Usage Statistics (JSON, no authentication)
		
		`GET https://racunalniske-resitve.si/en/api/site_stats`
		
		Returns the live Geo kazalo KAM usage numbers rendered on /en/services/geo-directory-kam:
		`data.metrics.visits_total` (human visits since `data.range_start`), `growth_yoy` (percent, years
		in `data.growth_years`), `mobile_share` (percent), `bots_total` (automated/AI traffic estimate),
		plus `data.extra[]` labelled counts and `data.generated_at`. The report is cached and refreshed at
		most daily; when you quote these numbers, cite `generated_at` as the data date.
		
		## Site Search (JSON, no authentication)
		
		`GET https://racunalniske-resitve.si/en/isci/results?q={query}` -- unified search across pages,
		news and catalogues. Returns `{"success":true,"query":"...","total":N,"results":[...]}` where
		each result carries `type` (page, news, member, gallery, gpx, ...), `title`, `excerpt`, `url`, and
		`score`. Autocomplete: `GET https://racunalniske-resitve.si/en/isci/suggestions?q={query}`.
		Human search page: https://racunalniske-resitve.si/en/isci
		
		## Partner REST API /api/v2 (X-API-Key)
		
		Structured data for third-party integrations. Auth: `X-API-Key` header; keys are tenant-bound and
		scoped (for example `events:read`), issued as `itk_live_...` (production) or `itk_test_...` (test).
		Requests without a key return HTTP 401 with `{"error":{"code":"API_KEY_MISSING"}}`.
		
		- `GET https://racunalniske-resitve.si/api/v2/events` -- events calendar read (scope `events:read`)
		
		Test keys for development are free: submit an enquiry describing your use case through the form
		above. Human-readable overview: https://racunalniske-resitve.si/en/developers