Integracija TollCalc v lastne aplikacije

TollCalc lahko integrirate v lastno programsko opremo ali AI delovne tokove na tri načine:

REST-API

Celotno dokumentacijo API (OpenAPI 3.0) najdete na:

tollcalc.eu/en/api.html

Hitri začetek

curl -X POST https://app.tollcalc.eu/api/calculate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VAŠ_API_TOKEN" \
  -d '{
    "origin": "Munich, Germany",
    "destination": "Vienna, Austria",
    "vehicle": {
      "weight": 40,
      "axles": 5,
      "emission_class": "euro6",
      "co2_class": "class_1"
    }
  }'

Parametri

Omejitve: Največ 500 točk na zahtevo (origin + via + destination). Pretirano gosti nizi koordinat (gostejši od 1 točke na 500 m) se na strežniku samodejno razredčijo, ORS pa zavrne poti, daljše od 3.000 km – daljše ture razdelite na več zahtev.

Neobvezna glava HTTP:

Avtentikacija

API žetone dobite po registraciji na app.tollcalc.eu. Brez žetona je možnih 10 brezplačnih zahtevkov na mesec (na IP naslov).

Pridobitev porabe in kvote

Ko je API integriran, lahko porabo in kvoto pridobite programsko – oba končni točki sta read-only, sami ne porabljata kvote in sprejemata isti bearer žeton:

Neobvezna parametra poizvedbe: year in month (privzeto: trenutni mesec).

# Poraba po podračunu
curl https://app.tollcalc.eu/api/usage \
  -H "Authorization: Bearer VAŠ_API_TOKEN"
# {"year":2026,"month":9,"total":1000,
#  "sub_accounts":[{"key":"kunde_a","count":500},{"key":"Default","count":320}]}

# Preostala kvota
curl https://app.tollcalc.eu/api/quota \
  -H "Authorization: Bearer VAŠ_API_TOKEN"
# {"year":2026,"month":9,"plan":"api","used":123,"limit":5000,"remaining":4877}

Brez glave X-Subaccount pri izračunu se klici pripišejo ključu Default. Pri neomejenih paketih sta limit in remaining null.

MCP – Integracija v AI asistenta

TollCalc podpira Model Context Protocol (MCP) in se lahko neposredno integrira v AI orodja, kot so Claude Desktop, Cursor ali drugi MCP-združljivi asistenti.

Končna točka

POST https://app.tollcalc.eu/mcp

Razpoložljiva orodja

Konfiguracija v Claude Desktop

V konfiguracijo Claude Desktop (claude_desktop_config.json) dodajte:

Možnost A – OAuth (priporočeno): navedite samo URL, žeton ni potreben.

{
  "mcpServers": {
    "tollcalc": {
      "url": "https://app.tollcalc.eu/mcp"
    }
  }
}

Možnost B – API ključ (za avtomatizacijo): žeton shranite ročno, npr. za integracije med strežniki.

{
  "mcpServers": {
    "tollcalc": {
      "url": "https://app.tollcalc.eu/mcp",
      "headers": {
        "Authorization": "Bearer VAŠ_API_TOKEN"
      }
    }
  }
}

Brez konfiguracije je na voljo 10 brezplačnih zahtevkov na MCP sejo (= na pogovor) – račun ni potreben. Po 10 zahtevkih Claude Desktop samodejno odpre prijavo v brskalniku (OAuth 2.0). Po prijavi velja naročena kvota. API žetone za možnost B dobite na app.tollcalc.eu.

Primer klica prek MCP

Po nastavitvi lahko asistenta vprašate neposredno:

„Koliko stane cestnina za 40-tonski tovornjak iz Münchna na Dunaj?"

Asistent pokliče orodje calculate_toll in vrne strukturiran odgovor.

Stopnje podrobnosti

Orodje calculate_toll podpira tri stopnje podrobnosti prek parametra detail:

Polja odgovora

Vse stopnje podrobnosti vsebujejo naslednja polja:

S detail=detailed countries dodatno vsebuje segments (segmente z road, type, km, toll_eur). S detail=full pridejo koordinate, source_url, matched_geofence in geometrija.

Server Card

Opis MCP (Server Card) je na voljo na:

GET https://app.tollcalc.eu/.well-known/mcp-server

Paket Python tollcalc

Paket Python tollcalc obdaja REST-API in omogoča uporabo iz Python skript ali Jupyter Notebookov.

Namestitev

pip install tollcalc

Uporaba

from tollcalc import calculate_toll, get_usage, get_quota

result = calculate_toll(
    origin="Munich, Germany",
    destination="Vienna, Austria",
    weight=40,
    axles=5,
    emission_class="euro6",
    co2_class="class_1",
    token="VAŠ_API_TOKEN",
)

print(f"Skupna cestnina: {result['total_toll_eur']:.2f} EUR")
print(f"Razdalja:        {result['total_distance_km']:.1f} km")

for country in result["countries"]:
    print(f"  {country['country_name']}: {country['toll_eur']:.2f} EUR ({country['toll_km']:.0f} cestninskih km)")

Poraba in kvota iz Pythona

from tollcalc import get_usage, get_quota

usage = get_usage(token="VAŠ_API_TOKEN")
print(usage["total"], "Calls")
for s in usage["sub_accounts"]:
    print(f"  {s['key']}: {s['count']}")

quota = get_quota(token="VAŠ_API_TOKEN")
print(f"{quota['used']} / {quota['limit']} – ostane: {quota['remaining']}")

Koordinate kot vhod

result = calculate_toll(
    origin="48.1374;11.5755",    # München (lat;lon)
    destination="48.2082;16.3738",  # Dunaj
    weight=40,
    axles=5,
)

Dokumentacija paketa

Celotno dokumentacijo in druge primere najdete na PyPI: pypi.org/project/tollcalc

Cene in kvote

Vse tarife in aktualne cene: tollcalc.eu/de/#pricing

Za vprašanja o integraciji se obrnite na support@tollcalc.eu.