Začínáme

1. Vytvořte si účet

Jděte na /register a vyplňte email, jméno a volitelně IČO firmy. Když IČO vyplníte, název firmy, DIČ i adresa se automaticky dotáhnou z registru ARES.

Heslo zatím nezadáváte — nastavíte si ho v dalším kroku po kliknutí na ověřovací odkaz v emailu.

2. Ověřte email a nastavte heslo

Do několika sekund dostanete email s ověřovacím odkazem. Klikněte na něj. Otevře se stránka, kde si nastavíte heslo (min. 8 znaků).

Po nastavení hesla jste přihlášení a můžete rovnou pokračovat do dashboardu.

3. Vytvořte si první filtr zakázek

V dashboardu klikněte na Zakázky → Nový filtr. Filtr je uložená sada kritérií, podle kterých vám systém posílá zakázky:

1. Region — kraj nebo více krajů (Praha, Středočeský, …)
2. Obor — kategorie zakázek (Pozemní stavby, IT vývoj, …) nebo CPV kód
3. Klíčová slova — slova co musí být v názvu nebo popisu (např. „rekonstrukce mostu")
4. Hodnota — min/max předpokládaná hodnota zakázky

Detailní popis všech parametrů filtru je v dokumentaci Hlídače zakázek.

4. Zapněte email digest

Pro každý filtr můžete zapnout denní email digest. Každý den v 7:00 dostanete email se zakázkami, které ten den přibyly a odpovídají vašemu filtru.

Digest se zapíná přímo v detailu filtru — přepínač „Email digest" v horní části. Můžete mít víc filtrů, každý s vlastním digest nastavením.

Hello world

Když máte klíč, voláte API takto:

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

Vrátí JSON s nejnovějšími otevřenými zakázkami. Plné parametry vyhledávání jsou v dokumentaci Hlídače zakázek.

Jak získat klíč

První API klíč vzniká přes dashboard: zaregistrujte se na webu, ověřte e-mail, a v Nastavení → Integrace klikněte „Vygenerovat klíč". Klíč se zobrazí jednou — uložte si ho hned (např. do env / secrets store). Pokud ho ztratíte, vytvoříte nový a starý smažete.

Použití v MCP klientech (Claude Desktop, Cursor, …)

Klíč je stejný jako pro REST API. Liší se jen způsob, jak ho klient posílá: MCP server běží na /api/mcp a klíč jde do X-Api-Key headeru handshaku. Plný setup pro Claude Desktop, Cursor a generické HTTP klienty je v dokumentaci MCP.

Autentizace

Všechny /api/v2 endpointy autentizujete jedním API klíčem (formát mrw_live_HEX64). Klíč můžete poslat jako X-Api-Key header nebo jako 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

Klíč nese identitu uživatele. Jaké služby může volat, řídí jeho předplatné (viz sekce Subscriptions). Můžete mít až 5 aktivních klíčů — užitečné pro oddělení prod / dev / per-systém.

Response envelope

Všechny v2 endpointy vrací jednotný JSON envelope. Single resource pod data, paginované listy pod data + pagination, chyby pod error.

Úspěch

// 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 měl větvit na code, ne na message — HTTP status mapuje na kód automaticky.

Rate limity

Při překročení vrací API HTTP 429 a hlavičku Retry-After (sekundy).

Trial a fakturace

Po vytvoření účtu máte 1 den zkušební doby zdarma pro Hlídač zakázek — bez karty, bez fakturačního profilu. Pak je potřeba mít připojenou kartu nebo zaplacenou zálohovou fakturu, jinak služba přejde do SUSPENDED a další volání vrátí 403. Žádné tier balíčky — platíte za konkrétní službu, zrušíte kdykoliv.

Account API

Správa účtu, klíčů, fakturace a webhooků. Všechny /api/v2/account/* endpointy vyžadují autentizaci klíčem.

Ekvivalent /profile + /subscriptions + apiKey info. Vhodné pro úvodní načtení v UI klientech.

{
  "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 klíče

Klíč autentizuje vůči celému API. Můžete mít až 5 aktivních klíčů. Raw klíč se vrací jen při vytvoření nebo rotaci — pak ho lze získat zpět jen vytvořením nového.

{ "label": "Production ERP" }

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

Klíč v response je v plné podobě jen tady. Server si ukládá jen SHA-256 hash; raw klíč pak nelze získat zpět. Pokud ztratíte, vytvořte nový a starý smažte.

Předplatné služeb

Aktivace trial, přehled stavu, plánované zrušení k datu paidUntil/trialEndsAt. Pro placené aktivace (kartou) použijte /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 volání API klíče za posledních N dní (default 30). Pro monitoring rate limit consumption.

Fakturace

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

Export dat (GDPR)

Zrušení účtu

{ "action": "DEACTIVATE" }

Webhooky

Account-level webhooky — jeden endpoint pokrývá všechny filtry i budoucí služby. Každý event nese HMAC-SHA256 podpis v X-Signature-256, idempotency klíč v X-Idempotency-Key a typ v X-Event-Type. Retry s exponenciálním backoffem až do ~33 h.

Max 5 endpointů na účet. Podporované eventy a payload schémata má každá služba ve své dokumentaci.

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

Notifikace

Feedback

OpenAPI 3.1 spec

Plnou strojově-čitelnou specifikaci API najdete na /openapi.json. Použijte pro auto-generování typed clientu v libovolném jazyce (TypeScript, Python, Go, Rust, …) nebo k importu do Postman / Insomnia / Swagger UI.

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

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

Chybové kódy