Začíname

1. Vytvorte si účet

Prejdite na /register a vyplňte e-mail, meno a voliteľne IČO firmy. Ak IČO vyplníte, názov firmy, DIČ aj adresa sa automaticky doplnia z registra ARES.

Heslo zatiaľ nezadávate — nastavíte si ho v ďalšom kroku po kliknutí na overovací odkaz v e-maile.

2. Overte e-mail a nastavte heslo

Do niekoľkých sekúnd dostanete e-mail s overovacím odkazom. Kliknite naň. Otvorí sa stránka, kde si nastavíte heslo (min. 8 znakov).

Po nastavení hesla ste prihlásení a môžete rovno pokračovať do dashboardu.

3. Vytvorte si prvý filter zákaziek

V dashboarde kliknite na Zákazky → Nový filter. Filter je uložená sada kritérií, podľa ktorých vám systém posiela zákazky:

1. Región — kraj alebo viac krajov (Bratislava, Trnavský, …)
2. Odbor — kategórie zákaziek (Pozemné stavby, IT vývoj, …) alebo CPV kód
3. Kľúčové slová — slová, ktoré musia byť v názve alebo popise (napr. „rekonštrukcia mosta")
4. Hodnota — min/max predpokladaná hodnota zákazky

Podrobný popis všetkých parametrov filtra nájdete v dokumentácii Hlídača zákaziek.

4. Zapnite e-mail digest

Pre každý filter môžete zapnúť denný e-mail digest. Každý deň o 7:00 dostanete e-mail so zákazkami, ktoré v daný deň pribudli a zodpovedajú vášmu filtru.

Digest sa zapína priamo v detaile filtra — prepínač „Email digest" v hornej časti. Môžete mať viac filtrov, každý s vlastným nastavením digestu.

Hello world

Keď máte kľúč, voláte API takto:

curl -H "X-Api-Key: mrw_live_…" \
  "https://veritra.io/api/v2/leads/tenders/search?qText=rekonstrukce%20mostu&limit=5"

Vráti JSON s najnovšími otvorenými zákazkami. Úplné parametre vyhľadávania nájdete v dokumentácii Hlídača zákaziek.

Ako získať kľúč

Prvý API kľúč vzniká cez dashboard: zaregistrujte sa na webe, overte e-mail a v Nastavenia → Integrácie kliknite „Vygenerovať kľúč". Kľúč sa zobrazí jedenkrát — uložte si ho ihneď (napr. do env / secrets store). Ak ho stratíte, vytvoríte nový a starý zmažete.

Použitie v MCP klientoch (Claude Desktop, Cursor, …)

Kľúč je rovnaký ako pre REST API. Líši sa len spôsob, akým ho klient posiela: MCP server beží na /api/mcp a kľúč ide do X-Api-Key headera handshaku. Plný setup pre Claude Desktop, Cursor a generické HTTP klienty je v dokumentácii MCP.

Autentifikácia

Všetky /api/v2 endpointy autentifikujete jedným API kľúčom (formát mrw_live_HEX64). Kľúč môžete poslať ako X-Api-Key header alebo ako Bearer token:

# header X-Api-Key
curl -H "X-Api-Key: mrw_live_…" https://veritra.io/api/v2/account/me

# nebo Bearer (kompatibilní s OpenAPI client generators)
curl -H "Authorization: Bearer mrw_live_…" https://veritra.io/api/v2/account/me

Kľúč nesie identitu používateľa. Aké služby môže volať, riadi jeho predplatné (pozri sekciu Subscriptions). Môžete mať až 5 aktívnych kľúčov — užitočné na oddelenie prod / dev / per-systém.

Response envelope

Všetky v2 endpointy vracajú jednotný JSON envelope. Single resource pod data, paginované zoznamy pod data + pagination, chyby pod error.

Úspech

// Single resource
{ "data": { "id": "…", "field": "…" } }

// Paginated list
{
  "data": [{ "…": "…" }],
  "pagination": { "nextCursor": "abc123…", "totalCount": 42 }
}

Chyba

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'url' must be a valid HTTPS URL.",
    "details": { "field": "url" }
  }
}

Stabilné error codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, ENTITLEMENT_REQUIRED, INTERNAL. Klient by mal vetviť na code, nie na message — HTTP status sa mapuje na kód automaticky.

Rate limity

Pri prekročení vracia API HTTP 429 a hlavičku Retry-After (sekundy).

Trial a fakturácia

Po vytvorení účtu máte 1 deň skúšobnej doby zadarmo pre Hlídač zakázek — bez karty, bez fakturačného profilu. Potom je potrebné mať pripojenú kartu alebo zaplatenú zálohovú faktúru, inak služba prejde do SUSPENDED a ďalšie volania vrátia 403. Žiadne tier balíčky — platíte za konkrétnu službu, zrušíte kedykoľvek.

Account API

Správa účtu, kľúčov, fakturácie a webhookov. Všetky /api/v2/account/* endpointy vyžadujú autentizáciu kľúčom.

Ekvivalent /profile + /subscriptions + apiKey info. Vhodné pre úvodné načítanie v UI klientoch.

{
  "data": {
    "account": { "email": "…", "name": "…", "company": "…", "ico": "…", "country": "CZ", "locale": "cs", "isComplete": true },
    "subscriptions": [
      { "service": "LEADS", "scope": "CZ", "state": "ACTIVE", "tier": "PAID", "trialEndsAt": null, "paidUntil": "2026-06-30T22:00:00.000Z", "cancelAtPeriodEnd": false }
    ],
    "apiKey": { "keyPrefix": "mrw_live_7fa7785c", "lastUsedAt": "…", "requestsMonth": 120, "requestsLimit": 500 }
  }
}

Heslo a session

API kľúče

Kľúč autentizuje voči celému API. Môžete mať až 5 aktívnych kľúčov. Raw kľúč sa vracia len pri vytvorení alebo rotácii — potom ho možno získať späť len vytvorením nového.

{ "label": "Production ERP" }

{
  "data": {
    "id": "cm…",
    "key": "mrw_live_<hex64>",
    "keyPrefix": "mrw_live_7fa7785c",
    "label": "Production ERP",
    "createdAt": "…"
  }
}

Kľúč v response je v plnej podobe len tu. Server ukladá len SHA-256 hash; raw kľúč potom nie je možné získať späť. Ak ho stratíte, vytvorte nový a starý vymažte.

Predplatné služieb

Aktivácia trialu, prehľad stavu, plánované zrušenie k dátumu paidUntil/trialEndsAt. Pre platené aktivácie (kartou) použite /billing/checkout.

{ "service": "LEADS", "scope": "CZ", "mode": "trial" }

{ "service": "LEADS", "scopes": ["CZ","SK","DE"], "mode": "trial" }

{ "cancelAtPeriodEnd": true }

API usage

Denný agregát počtu volaní API kľúča za posledných N dní (default 30). Pre monitoring rate limit consumption.

Fakturácia

{ "cycle": "MONTHLY", "currency": "CZK", "scopes": ["CZ","SK"] }

Export dát (GDPR)

Zrušenie účtu

{ "action": "DEACTIVATE" }

Webhooky

Account-level webhooky — jeden endpoint pokrýva všetky filtre aj budúce služby. Každý event nesie HMAC-SHA256 podpis v X-Signature-256, idempotency kľúč v X-Idempotency-Key a typ v X-Event-Type. Retry s exponenciálnym backoffom až do ~33 h.

Max 5 endpointov na účet. Podporované eventy a payload schémy má každá služba vo svojej dokumentácii.

{
  "url": "https://yourapp.cz/api/veritra-webhook",
  "enabledEvents": ["leads.match.created"],
  "description": "production"
}

Notifikácie

Spätná väzba

OpenAPI 3.1 spec

Plnú strojovo-čitateľnú špecifikáciu API nájdete na /openapi.json. Použite na auto-generovanie typed klienta v ľubovoľnom jazyku (TypeScript, Python, Go, Rust, …) alebo na import do Postman / Insomnia / Swagger UI.

# Generate TypeScript client
npx openapi-typescript https://veritra.io/openapi.json -o ./veritra-types.ts

# Generate Python client (openapi-python-client)
openapi-python-client generate --url https://veritra.io/openapi.json

Chybové kódy