Hlídač zákaziek

Koncept

Štyri pojmy, s ktorými sa stretnete vo všetkých endpointoch:

• Tender — jedna konkrétna zákazka z portálu (NEN, VVZ, E-ZAK, TenderArena, atď.). Identifikovaná číselným ID.
• Filter — uložená sada kritérií (región, odbor, kľúčové slová, hodnota). Keď nová zákazka spĺňa kritériá, vznikne match.
• Match — nová zákazka, ktorá spadla do vášho filtra. Reprezentuje väzbu (tender × filter) + timestamp + váš stav (sledované / skryté / prečítané).
• Taxonomy — číselníky regiónov (NUTS), odborov (industry tags) a CPV kódov, podľa ktorých klasifikujeme zákazky.

Rýchly štart

Filtre možno nastaviť dvoma spôsobmi — výsledok je rovnaký, filter možno kedykoľvek upraviť ľubovoľnou cestou.

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

Hore je ad-hoc vyhľadávanie. Ak chcete kontinuálny monitoring (nové zákazky zodpovedajúce vašim kritériám), použite filtre + webhook/email digest — pozri ďalej.

Vyhľadávanie zákaziek (ad-hoc)

Na jednorazové vyhľadanie zákaziek naprieč všetkými aktívnymi tendrami. Nepoužíva uložený filter, parametre idú priamo v query stringu.

Query parametre

Príklad

curl -H "X-Api-Key: mrw_live_…" \
  "https://veritra.io/api/v2/leads/tenders/search?qText=rekonstrukce&regions=CZ010,CZ020&minValue=500000&limit=10"

Response: objekt data s poľami id, title, description, estimatedValue, deadlineAt, contractingAuthority, documents[], starred, excluded.

Body môže obsahovať recipientEmail pre forward na iný email. Predvolene user.email.

Query: ?url=:original&kind=docx|xlsx. Allowlist hostov: NEN, E-ZAK, Tender Arena, Gemin, ProfilZadavatele.

GET /api/v2/leads/documents/preview?url=https://nen.nipez.cz/…/Vyzva.docx&kind=docx
→ 302 Location: https://rwx-storage…/Tendero/doc-cache-v8/<hash>.html (signed, TTL 10 min)

Catalog & autocomplete (public, žiadny kľúč)

Pre UI dropdowny a tvorbu filtrov. Cache 1h server-side. Verejné, žiadna auth nie je potrebná.

Čo je možné filtrovať a povolené hodnoty

Filter sa skladá z polí uvedených nižšie. Všetky sú voliteľné okrem `name`. Prázdne pole = bez obmedzenia v danej dimenzii.

regions string[]

NUTS regióny pre danú krajinu (?country=CZ) s labels per locale.

Pre získanie úplného NUTS stromu konkrétnej krajiny použite:

GET /api/v2/leads/regions/catalog?country=CZ&locale=cs
GET /api/v2/leads/regions/catalog?country=DE&locale=de
GET /api/v2/leads/regions/catalog?country=FR&locale=en

industryTags string[] Odporúčané

Multi-tag odborová klasifikácia. Tender môže mať viac tagov (napr. 'stav_pozemni' + 'stav_remesla' pri rekonštrukcii). Filter zodpovedá tendru, ak má aspoň jeden zo zadaných tagov (JSON_OVERLAPS).

Prečo preferovať industryTags pred CPV: Naše industryTags vznikajú kombináciou LLM klasifikácie názvu/popisu tendru + CPV mapovania + regex hintov — zachytia relevantné zákazky aj u zadávateľov, ktorí priraďujú CPV nedbalo. CPV filter je presný, ale závisí od disciplíny zadávateľa, ktorá je v ČR slabá.

categories string[] Menej presné

CPV (Common Procurement Vocabulary) prefixy ľubovoľnej dĺžky — zhoda cez `LIKE 'prefix%'`. Tj. '45' zachytí všetky stavebné oddiely, '4523' len inžinierske stavby, '45316110' len pouličné osvetlenie.

keywords string[]

LIKE zhoda v názve aj popise zákazky. Case-insensitive. Medzi položkami OR. Užitočné ako poistka, ak industryTags/CPV nezachytia všetko (napr. špecifický typ zákazky v texte).

"keywords": ["rekonstrukce", "VO", "osvětlení", "MŠ"]

minValue / maxValue number | null

Rozsah odhadovanej hodnoty zákazky v Kč. Možno zadať len minValue, len maxValue, alebo oboje.

emailDigest boolean

Ak je true, dostávate 1× denne (5:00 UTC) e-mail so zhrnutím nových zhôd z tohto filtra. Predvolená hodnota je true. Vypnete ho úpravou filtra. Webhook sa nastavuje zvlášť, na úrovni účtu (pozri sekciu nižšie).

name string · active boolean

`name` — max 120 znakov, povinné. `active` — ak false, filter nebeží v crone (žiadne nové zhody, digest, webhook). Možno pozastaviť bez vymazania.

Logika filtrovania

Polia sa kombinujú takto:

MATCH = (zadávateľ.NUTS3 ∈ expand(regions))
     AND (minValue ≤ estimatedValue ≤ maxValue  ALEBO  estimatedValue je null alebo 0)
     AND (industry_or_cpv  ALEBO  keyword_match)

# expand(regions): NUTS kódy sa expandujú na NUTS 3 leaves
# (CZ → 14 krajov, CZ01 → CZ010, CZ010 → CZ010).

industry_or_cpv:
   ak  industryTags zadané  →  JSON_OVERLAPS(industryTags, tender.industryTags)
   inak categories zadané   →  tender.cpvCode LIKE ANY (categories + "%")
   inak                     →  false   (žiadny industry filter sa neaplikuje)

keyword_match:
   ak  keywords zadané      →  tender.title alebo description LIKE ANY (%kw%)
   inak                     →  false

# Keď nezadáte žiadne industryTags / categories / keywords,
# vrátia sa všetky tendre spĺňajúce regions a value range.

industryTags má prednosť pred categories — ak zadáte oboje, použije sa len industryTags (categories sa ignoruje). keywords fungujú nezávisle (sú vo vetve OR spolu s industry_or_cpv).

Endpointy pre správu filtrov

Pre správu filtrov použite management kľúč (mrw_live_…). Má samostatné rate limity a nespotrebúva LEADS kredity, takže správa filtrov neovplyvňuje vaše denné vyzdvihávanie zákaziek.

Body parametre (POST / PUT) — spoločné

Webhook sa na filtri už nenastavuje — pozri sekciu Webhook nižšie (account-level endpointy). Pole webhookUrl je z bezpečnostných dôvodov odmietnuté s HTTP 410.

Príklady

Stavby v Prahe nad 500 tis. Kč

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stavby Praha 500k+",
    "regions": ["CZ010"],
    "industryTags": ["con_buildings", "con_trades"],
    "minValue": 500000
  }' \
  https://veritra.io/api/v2/leads/filters

IT vývoj a SW licencie (všetky kraje)

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IT vývoj + SW licencie",
    "industryTags": ["it_development", "it_licensing", "it_data_ai"],
    "keywords": ["informačný systém", "modul"]
  }' \
  https://veritra.io/api/v2/leads/filters

Verejné osvetlenie (CZ) — kombinácia tagov + keywords

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Verejné osvetlenie (CZ)",
    "industryTags": ["goods_electrical", "con_civil"],
    "keywords": ["osvetlenie", "VO ", "verejné osvetlenie", "lampy"],
    "minValue": 200000
  }' \
  https://veritra.io/api/v2/leads/filters

Deaktivovať filter

curl -X PATCH -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{"active": false}' \
  https://veritra.io/api/v2/leads/filters/<id>

Doručovanie — webhook vs polling

Dva spôsoby, ako dostať nové zákazky do svojho ERP. Väčšina integrátorov kombinuje oba.

Získanie matchov

Query parametre

Vrátené matche sú automaticky označené ako delivered=true. Každý request spotrebuje 1 kredit.

Formáty matchId

matchId má dva formáty podľa pôvodu:

• cm… (cuid prefix) — vrátený z pre-computed LeadMatch tabuľky (cron job, ktorý páruje zákazky každý deň). Stabilný naprieč volaniami, použiteľný pre mark-as-viewed.
• live-12345 synthetic prefix pre live-detekovaný match cez search / browse mode (qText param, view=starred/excluded). Nie je v LeadMatch tabuľke → mark-as-viewed je no-op. tenderId je suffix po pomlčke.

Príklad

curl -H "X-Api-Key: mrw_leads_…" \
  "https://veritra.io/api/v2/leads/matches?delivered=false&limit=10"

Odpoveď

{
  "data": [
    {
      "matchId": "cm…",
      "filterId": "cm…",
      "filterName": "Stavby Praha",
      "matchedAt": "2026-04-03T06:00:00.000Z",
      "viewedAt": null,
      "delivered": true,
      "tender": {
        "id": 12345,
        "title": "Rekonštrukcia mosta ev.č. 123",
        "estimatedValue": 12500000,
        "deadlineAt": "2026-05-15T22:00:00.000Z",
        "publishedAt": "2026-04-01T08:00:00.000Z",
        "firstSeenAt": "2026-04-01T08:30:00.000Z",
        "url": "https://nen.nipez.cz/...",
        "portalType": "NEN",
        "cpvCode": "45000000",
        "tenderType": "OFFERS",
        "contractingAuthority": {
          "ico": "12345678",
          "name": "Město Praha",
          "region": "Praha",
          "district": "Praha 1"
        },
        "documents": [
          { "name": "Výzva.pdf", "url": "https://nen.nipez.cz/…", "fileType": "pdf", "fileSizeBytes": 320000 }
        ],
        "starred": false,
        "excluded": false
      }
    }
  ],
  "pagination": { "nextCursor": "eyJmaXJzdFNlZW5BdC…", "totalCount": 42 }
}

Pre ďalšiu stránku pošlite pagination.nextCursor ako parameter ?cursor=.

Akcie na matche

Star (obľúbiť), exclude (skryť) a view (označiť ako prečítané) sú per-tender preferencie uložené v UserTenderPreference.

Response: rovnaký tvar ako položka zoznamu matches.

{ "starred": true }

{ "excluded": true }

Pre synthetic live-:id matches je no-op (žiadny riadok na označenie).

{
  "data": {
    "starred": [12345, 67890],
    "excluded": [54321]
  }
}

Taxonomy

Statické referenčné katalógy pre hodnoty filtrov. Locale-aware labels.

{
  "data": {
    "locale": "cs",
    "areas": [{ "id": "construction", "icon": "🏗️", "label": "Stavebnictví" }, …],
    "tags": [
      { "id": "con_buildings", "area": "construction", "label": "Pozemní stavby", "cpvPrefixes": ["452"] },
      …
    ]
  }
}

Response: stromová štruktúra oddiely → skupiny → triedy → kategórie → podkategórie.

Webhook

Webhook endpointy (CRUD, secret rotation) sú account-level — zdokumentované raz v Account API → Webhooky. Tu je popísaný len leads-specific event payload (leads.match.created) a HMAC verifikácia.

Doručovanie eventov

Pri novom matchi pošleme event typu leads.match.created s HMAC-SHA256 podpisom v hlavičke X-Signature-256, idempotency kľúčom v X-Idempotency-Key a typom v X-Event-Type. Pri zlyhaní retry s exponenciálnym backoffom do ~33 hodín.

Retry policy

Ak váš endpoint vráti non-2xx (alebo neodpovie do 10 s), Veritra opakuje pokus s exponential backoff: 1 min, 5 min, 30 min, 2 h, 12 h, 24 h. Po 6 zlyhaniach sa webhook označí ako failed a v dashboarde sa rozbliká. Idempotency-key zostáva pre každý pokus rovnaký — váš endpoint MUSÍ dedupolikovať (inak sa ten istý match spracuje 6×).

Správa endpointov cez API

Môžete spravovať webhook endpointy bez vstupu do dashboardu. Limit 5 endpointov na účet.

HMAC signature verification

Server podpisuje payload HMAC-SHA256(secret, raw_body) a posiela v hlavičke X-Signature-256 vo formáte sha256=hex. Verifikujte konštantno-časovým porovnaním, inak je integrácia zraniteľná na timing attack.

// Node.js (Express)
import crypto from "node:crypto";

const WEBHOOK_SECRET = process.env.MRICKWOOD_WEBHOOK_SECRET!;

function verify(rawBody: string, sig: string | undefined): boolean {
  if (!sig) return false;
  const expected = "sha256=" + crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");
  // Constant-time comparison (timing-safe)
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhooks/veritra",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const raw = req.body.toString("utf8");
    if (!verify(raw, req.header("X-Signature-256"))) {
      return res.status(401).send("Invalid signature");
    }
    const idempKey = req.header("X-Idempotency-Key")!;
    const evt = JSON.parse(raw);
    // Idempotency: store idempKey, skip if already processed
    if (await alreadyProcessed(idempKey)) return res.status(200).send("ok");
    await processEvent(evt);
    await markProcessed(idempKey);
    res.status(200).send("ok"); // Must be 2xx within 10s
  },
);

# Python (Flask)
import hmac, hashlib, os
from flask import Flask, request, abort

WEBHOOK_SECRET = os.environ["MRICKWOOD_WEBHOOK_SECRET"]

def verify(raw: bytes, sig: str | None) -> bool:
    if not sig: return False
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

@app.post("/webhooks/mrickwood")
def webhook():
    raw = request.get_data()
    if not verify(raw, request.headers.get("X-Signature-256")):
        abort(401)
    # ... idempotency check + process
    return "ok", 200

{
  "id": "evt_…",
  "type": "leads.match.created",
  "createdAt": "2026-04-03T06:00:00.000Z",
  "data": {
    "filterId": "cm…",
    "filterName": "Stavby Praha",
    "matchId": "cm…",
    "tender": { "id": "12345", "title": "…", "estimatedValue": 12500000 }
  }
}

Email digest

S emailDigest: true dostanete denný e-mail s prehľadom nových zákaziek. Digest sa odosiela ráno (5:00 UTC) na e-mail vášho účtu. Možno vypnúť úpravou filtra.

Limity

Po prekročení mesačného limitu vráti API 429 s hlavičkou Retry-After. Limit sa resetuje 1. deň v mesiaci.