Monitor przetargów

Pojęcia

Cztery terminy, które napotkasz we wszystkich punktach końcowych:

• Tender — pojedyncze zamówienie z portalu (NEN, VVZ, E-ZAK, TenderArena itp.). Identyfikowane za pomocą numerycznego ID.
• Filter — zapisany zestaw kryteriów (region, branża, słowa kluczowe, wartość). Gdy nowe zamówienie spełnia kryteria, generowane jest dopasowanie.
• Match — nowe zamówienie, które spełniło warunki Twojego filtra. Reprezentuje powiązanie (zamówienie × filtr) + znacznik czasu + Twój stan (oznaczone gwiazdką / wykluczone / wyświetlone).
• Taxonomy — kontrolowane słowniki dla regionów (NUTS), branż (tagi branżowe) i kodów CPV używanych do klasyfikacji zamówień.

Szybki start

Filtry można skonfigurować na dwa sposoby — efekt jest identyczny, a filtr można edytować dowolną metodą w dowolnym momencie.

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

Powyższe to wyszukiwanie ad hoc. Do ciągłego monitorowania (nowe zamówienia spełniające Twoje kryteria) użyj filtrów + webhook/email digest — patrz poniżej.

Wyszukiwanie zamówień (ad hoc)

Do jednorazowych wyszukiwań wśród wszystkich aktywnych zamówień. Nie używa zapisanego filtra — parametry są przekazywane bezpośrednio w ciągu zapytania.

Parametry zapytania

Przykład

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

Odpowiedź: { data: { id, title, description, estimatedValue, deadlineAt, contractingAuthority, documents[], starred, excluded } }.

Body może zawierać recipientEmail w celu przekazania wiadomości na inny adres e-mail. Domyślnie użytkownik user.email.

Zapytanie: ?url=:original&kind=docx|xlsx. Dozwolone hosty: 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)

Katalog i autouzupełnianie (publiczne, bez klucza)

Do list rozwijanych interfejsu i tworzenia filtrów. Pamięć podręczna po stronie serwera: 1 godz. Publiczne, bez wymaganego uwierzytelnienia.

Pola filtrów i dozwolone wartości

Filtr składa się z poniższych pól. Wszystkie są opcjonalne z wyjątkiem `name`. Puste pole oznacza brak ograniczenia dla danego wymiaru.

regions string[]

Regiony NUTS dla wybranego kraju (?country=CZ) z etykietami uwzględniającymi język.

Aby uzyskać pełne drzewo NUTS dla konkretnego kraju, użyj:

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[] Zalecane

Wielotagowa klasyfikacja branżowa. Przetarg może mieć wiele tagów (np. 'stav_pozemni' + 'stav_remesla' dla remontu). Filtr dopasowuje przetarg, jeśli ustawiony jest co najmniej jeden z żądanych tagów (JSON_OVERLAPS).

Dlaczego preferować industryTags zamiast CPV: Nasze industryTags łączą klasyfikację LLM tytułu/opisu przetargu z mapowaniem CPV i wskazówkami regex — wychwytują istotne przetargi nawet wtedy, gdy instytucja zamawiająca przypisała CPV niestarannie. Czysty filtr CPV jest precyzyjny, ale zależy od dyscypliny instytucji zamawiającej, która w CZ jest niska.

categories string[] Mniej dokładne

Prefiksy CPV (Wspólny Słownik Zamówień) o dowolnej długości — dopasowywane przez `LIKE 'prefix%'`. Tak więc '45' obejmuje wszystkie działy budowlane, '4523' tylko inżynierię lądową, '45316110' tylko oświetlenie ulic.

keywords string[]

Dopasowanie LIKE w tytule i opisie zamówienia. Bez rozróżniania wielkości liter. Operator OR między elementami. Przydatne jako siatka bezpieczeństwa, gdy industryTags/CPV nie wychwytują wszystkiego (np. określony typ zamówienia widoczny tylko w treści).

"keywords": ["rekonstrukcja", "oświetlenie", "przedszkole"]

minValue / maxValue number | null

Zakres szacowanej wartości zamówienia w CZK. Można ustawić tylko minValue, tylko maxValue lub oba.

emailDigest boolean

Jeśli true, otrzymujesz jeden codzienny e-mail (5:00 UTC) z podsumowaniem nowych dopasowań dla tego filtra. Domyślnie true. Można wyłączyć, edytując filtr. Webhooki konfiguruje się oddzielnie, na poziomie konta (patrz poniżej).

name string · active boolean

`name` — maks. 120 znaków, wymagane. `active` — jeśli false, filtr jest wykluczony z harmonogramu cron (brak nowych dopasowań, brak podsumowania, brak webhooka). Używaj do wstrzymania bez usuwania.

Logika filtra

Pola łączą się w następujący sposób:

MATCH = (authority.NUTS3 ∈ expand(regions))
     AND (minValue ≤ estimatedValue ≤ maxValue  OR  estimatedValue is null or 0)
     AND (industry_or_cpv  OR  keyword_match)

# expand(regions): kody NUTS są rozwijane do liści NUTS 3
# (CZ → 14 regionów, CZ01 → CZ010, CZ010 → CZ010).

industry_or_cpv:
   if    industryTags set  →  JSON_OVERLAPS(industryTags, tender.industryTags)
   elif  categories set    →  tender.cpvCode LIKE ANY (categories + "%")
   else                    →  false   (brak filtra branżowego)

keyword_match:
   if    keywords set      →  tender.title or description LIKE ANY (%kw%)
   else                    →  false

# Jeśli nie ustawiono industryTags / categories / keywords,
# zwracane są wszystkie zamówienia pasujące do regions i zakresu wartości.

industryTags ma pierwszeństwo przed categories — jeśli ustawiono oba, używany jest tylko industryTags (categories jest ignorowane). keywords działają niezależnie (są połączone operatorem OR z industry_or_cpv).

Endpointy zarządzania filtrami

Użyj klucza zarządzającego (mrw_live_…) do zarządzania filtrami. Posiada osobne limity żądań i nie zużywa kredytów LEADS, dzięki czemu zarządzanie filtrami nie wpływa na dzienny limit pobierania leadów.

Parametry body (POST / PUT) — wspólne

Webhooki nie są już konfigurowane per filtr — patrz sekcja Webhook poniżej (endpointy na poziomie konta). Pole webhookUrl jest odrzucane z kodem HTTP 410 ze względów bezpieczeństwa.

Przykłady

Budownictwo w Pradze powyżej 500 tys. CZK

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

Rozwój IT i licencje SW (wszystkie regiony)

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rozwój IT + licencje SW",
    "industryTags": ["it_development", "it_licensing", "it_data_ai"],
    "keywords": ["system informatyczny", "moduł"]
  }' \
  https://veritra.io/api/v2/leads/filters

Oświetlenie publiczne (CZ) — kombinacja tagów i słów kluczowych

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Oświetlenie publiczne (CZ)",
    "industryTags": ["goods_electrical", "con_civil"],
    "keywords": ["oświetlenie", "latarnia uliczna", "oświetlenie publiczne", "lampy"],
    "minValue": 200000
  }' \
  https://veritra.io/api/v2/leads/filters

Dezaktywuj filtr

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>

Dostarczanie — webhook a polling

Dwa sposoby pobierania nowych przetargów do systemu ERP. Większość integratorów łączy oba.

Pobieranie dopasowań

Parametry zapytania

Zwrócone dopasowania są automatycznie oznaczane delivered=true. Każde żądanie zużywa 1 kredyt.

Formaty matchId

matchId występuje w dwóch formatach zależnie od źródła:

• cm… (prefiks cuid) — zwracany z wstępnie obliczonej tabeli LeadMatch (cron dzienny). Stabilny między wywołaniami, można używać do oznaczania jako wyświetlone.
• live-12345 Prefiks syntetyczny dla dopasowań wykrytych na żywo przez wyszukiwanie / tryb przeglądania (parametr qText, view=starred/excluded). Nie znajduje się w tabeli LeadMatch → oznaczenie jako wyświetlone nie wywołuje żadnej akcji. tenderId to sufiks po myślniku.

Przykład

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

Odpowiedź

{
  "data": [
    {
      "matchId": "cm…",
      "filterId": "cm…",
      "filterName": "Budownictwo w Pradze",
      "matchedAt": "2026-04-03T06:00:00.000Z",
      "viewedAt": null,
      "delivered": true,
      "tender": {
        "id": 12345,
        "title": "Przebudowa mostu nr ref. 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 }
}

Aby przejść do następnej strony, przekaż pagination.nextCursor jako parametr ?cursor=.

Akcje dopasowań

Oznaczenie gwiazdką (ulubione), wykluczenie (ukrycie) i wyświetlenie (oznaczenie jako przeczytane) to preferencje per-przetarg przechowywane w UserTenderPreference.

Odpowiedź: taka sama struktura jak element listy dopasowań.

{ "starred": true }

{ "excluded": true }

Brak operacji dla syntetycznych dopasowań live-:id (brak wiersza do oznaczenia).

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

Taksonomia

Statyczne katalogi referencyjne dla wartości filtrów. Etykiety uwzględniające ustawienia regionalne.

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

Odpowiedź: struktura drzewiasta: działy → grupy → klasy → kategorie → podkategorie.

Webhook

Punkty końcowe webhooków (CRUD, rotacja klucza tajnego) są na poziomie konta — udokumentowane raz w Account API → Webhooks. Ta sekcja dotyczy wyłącznie ładunku zdarzenia specyficznego dla leadów (leads.match.created) oraz weryfikacji HMAC.

Dostarczanie zdarzeń

Po nowym dopasowaniu wysyłamy zdarzenie typu leads.match.created z podpisem HMAC-SHA256 w nagłówku X-Signature-256 klucz idempotentności w X-Idempotency-Key, a typ w X-Event-Type. W przypadku błędu ponawiamy próbę z wykładniczym opóźnieniem przez maksymalnie ~33 godziny.

Polityka ponownych prób

Jeśli Twój punkt końcowy zwróci kod spoza zakresu 2xx (lub nie odpowie w ciągu 10 s), Veritra ponawia próbę z wykładniczym opóźnieniem: 1 min, 5 min, 30 min, 2 h, 12 h, 24 h. Po 6 nieudanych próbach webhook jest oznaczany jako niedziałający i sygnalizowany w panelu. Klucz idempotentności pozostaje taki sam dla każdej próby — Twój punkt końcowy MUSI deduplikować żądania (w przeciwnym razie to samo dopasowanie zostanie przetworzone 6×).

Zarządzanie punktami końcowymi przez API

Punktami końcowymi webhooka można zarządzać bez wchodzenia do panelu. Limit: 5 punktów końcowych na konto.

Weryfikacja podpisu HMAC

Serwer podpisuje ładunek jako HMAC-SHA256(secret, raw_body) i przesyła go w nagłówku X-Signature-256 w formacie sha256=hex. Weryfikuj w czasie stałym — w przeciwnym razie integracja jest podatna na ataki czasowe.

// 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": "Budownictwo w Pradze",
    "matchId": "cm…",
    "tender": { "id": "12345", "title": "…", "estimatedValue": 12500000 }
  }
}

Codzienny digest e-mail

Dzięki emailDigest: true otrzymujesz codzienny e-mail z podsumowaniem nowych przetargów. Digest jest wysyłany rano (5:00 UTC) na adres e-mail przypisany do konta. Możesz go wyłączyć, edytując filtr.

Limity

Po przekroczeniu miesięcznego limitu API zwraca kod 429 z nagłówkiem Retry-After. Limit jest resetowany 1. dnia miesiąca.