Aanbestedingsmonitor

Concepten

Vier begrippen die u in alle eindpunten tegenkomt:

• Tender — een enkele aanbesteding van een portaal (NEN, VVZ, E-ZAK, TenderArena, enz.). Geïdentificeerd door een numeriek ID.
• Filter — een opgeslagen set criteria (regio, sector, trefwoorden, waarde). Wanneer een nieuwe aanbesteding aan de criteria voldoet, wordt een treffer gegenereerd.
• Match — een nieuwe aanbesteding die binnen uw filter valt. Vertegenwoordigt de koppeling (aanbesteding × filter) + tijdstempel + uw status (gemarkeerd / uitgesloten / bekeken).
• Taxonomy — gecontroleerde vocabulaires voor regio's (NUTS), sectoren (sectortags) en CPV-codes die worden gebruikt om aanbestedingen te classificeren.

Snel starten

Filters kunnen op twee manieren worden ingesteld — het resultaat is identiek en een filter kan op elk moment via beide wegen worden bewerkt.

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

Bovenstaande is een ad-hoczoekactie. Voor continue monitoring (nieuwe aanbestedingen die aan uw criteria voldoen) gebruikt u filters + webhook/e-maildigest — zie hieronder.

Aanbesteding zoeken (ad hoc)

Voor eenmalige zoekopdrachten door alle actieve aanbestedingen. Maakt geen gebruik van een opgeslagen filter — parameters worden rechtstreeks in de querystring meegegeven.

Queryparameters

Voorbeeld

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

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

De body mag recipientEmail bevatten om door te sturen naar een ander e-mailadres. Standaard is user.email.

Query: ?url=:original&kind=docx|xlsx. Toegestane hosts: 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)

Catalogus & automatisch aanvullen (openbaar, geen sleutel vereist)

Voor UI-dropdowns en het aanmaken van filters. Servercache van 1 uur. Openbaar, geen authenticatie vereist.

Filtervelden en toegestane waarden

Een filter bestaat uit de onderstaande velden. Alle zijn optioneel, behalve `name`. Een leeg veld betekent geen beperking op die dimensie.

regions string[]

NUTS-regio's voor het opgegeven land (?country=CZ) met gelokaliseerde labels.

Gebruik het volgende om de volledige NUTS-boom voor een specifiek land op te halen:

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

Brancheclassificatie met meerdere tags. Een aanbesteding kan meerdere tags hebben (bijv. 'stav_pozemni' + 'stav_remesla' voor een renovatie). Het filter matcht een aanbesteding als ten minste één van de gevraagde tags is ingesteld (JSON_OVERLAPS).

Waarom de voorkeur geven aan industryTags boven CPV: Onze industryTags combineren LLM-classificatie van de aanbestedingstitel/-beschrijving met CPV-koppeling en regex-hints — ze vangen relevante aanbestedingen ook wanneer de aanbestedende dienst CPV-codes onzorgvuldig heeft toegewezen. Een puur CPV-filter is exact maar afhankelijk van de discipline van de aanbestedende dienst, die in CZ beperkt is.

categories string[] Minder nauwkeurig

CPV-prefixen (Common Procurement Vocabulary) van willekeurige lengte — gematcht via `LIKE 'prefix%'`. '45' dekt alle bouwdivisies, '4523' alleen civiele techniek, '45316110' alleen straatverlichting.

keywords string[]

LIKE-overeenkomst in tendertitel en -beschrijving. Hoofdletterongevoelig. OR tussen items. Handig als vangnet als industryTags/CPV niet alles detecteren (bijv. een specifiek tendertype dat alleen in de tekst verschijnt).

"keywords": ["reconstructie", "verlichting", "kleuterschool"]

minValue / maxValue number | null

Geschatte tenderwaardebereik in CZK. U kunt alleen minValue, alleen maxValue of beide instellen.

emailDigest boolean

Indien ingeschakeld, ontvangt u dagelijks één e-mail (05:00 UTC) met een samenvatting van nieuwe overeenkomsten voor dit filter. Standaard ingeschakeld. Uitschakelen via filterbewerking. Webhooks worden afzonderlijk geconfigureerd op accountniveau (zie hieronder).

name string · active boolean

`name` — max. 120 tekens, verplicht. `active` — indien false wordt het filter uitgesloten van de cron (geen nieuwe overeenkomsten, geen digest, geen webhook). Gebruik dit om te pauzeren zonder te verwijderen.

Filterlogica

Velden worden als volgt gecombineerd:

OVEREENKOMST = (authority.NUTS3 ∈ expand(regions))
     AND (minValue ≤ estimatedValue ≤ maxValue  OF  estimatedValue is null of 0)
     AND (industry_or_cpv  OF  keyword_match)

# expand(regions): NUTS-codes worden uitgebreid naar NUTS 3-bladeren
# (CZ → 14 regio's, CZ01 → CZ010, CZ010 → CZ010).

industry_or_cpv:
   if    industryTags ingesteld  →  JSON_OVERLAPS(industryTags, tender.industryTags)
   elif  categories ingesteld    →  tender.cpvCode LIKE ANY (categories + "%")
   else                          →  false   (geen industriefilter toegepast)

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

# Als u geen industryTags / categories / keywords instelt,
# worden alle tenders geretourneerd die overeenkomen met regio's en waardebereik.

industryTags heeft voorrang op categories — als u beide instelt, wordt alleen industryTags gebruikt (categories wordt genegeerd). keywords werken onafhankelijk (ze worden met OR gecombineerd met industry_or_cpv).

Filterbeheer-endpoints

Gebruik de beheersleutel (mrw_live_…) om filters te beheren. Dit heeft afzonderlijke snelheidslimieten en verbruikt geen LEADS-credits, zodat filterbeheer geen invloed heeft op het dagelijks ophalen van leads.

Bodyparameters (POST / PUT) — gedeeld

Webhooks worden niet langer per filter geconfigureerd — zie de Webhook sectie hieronder (endpoints op accountniveau). Het webhookUrl veld wordt geweigerd met HTTP 410 om veiligheidsredenen.

Voorbeelden

Bouw in Praag boven 500k CZK

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

IT-ontwikkeling en SW-licenties (alle regio's)

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IT-ontwikkeling + SW-licenties",
    "industryTags": ["it_development", "it_licensing", "it_data_ai"],
    "keywords": ["informatiesysteem", "module"]
  }' \
  https://veritra.io/api/v2/leads/filters

Openbare verlichting (CZ) — combinatie van tags en trefwoorden

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Openbare verlichting (CZ)",
    "industryTags": ["goods_electrical", "con_civil"],
    "keywords": ["verlichting", "straatlantaarn", "openbare verlichting", "lampen"],
    "minValue": 200000
  }' \
  https://veritra.io/api/v2/leads/filters

Een filter deactiveren

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>

Levering — webhook vs. polling

Twee manieren om nieuwe aanbestedingen in uw ERP te ontvangen. De meeste integrators combineren beide.

Overeenkomsten ophalen

Queryparameters

Geretourneerde overeenkomsten worden automatisch gemarkeerd als delivered=true. Elke aanvraag verbruikt 1 credit.

matchId-formaten

matchId heeft twee formaten op basis van herkomst:

• cm… (cuid-prefix) — geretourneerd vanuit de voorberekende LeadMatch-tabel (dagelijkse cron). Stabiel over aanroepen heen, bruikbaar voor markeren-als-bekeken.
• live-12345 Synthetische prefix voor live-gedetecteerde overeenkomsten via zoek-/browsemodus (parameter qText, view=starred/excluded). Niet aanwezig in de LeadMatch-tabel → markeren-als-bekeken heeft geen effect. tenderId is het achtervoegsel na het streepje.

Voorbeeld

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

Respons

{
  "data": [
    {
      "matchId": "cm…",
      "filterId": "cm…",
      "filterName": "Bouw in Praag",
      "matchedAt": "2026-04-03T06:00:00.000Z",
      "viewedAt": null,
      "delivered": true,
      "tender": {
        "id": 12345,
        "title": "Brugreconstructie reg.nr. 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 }
}

Geef voor de volgende pagina pagination.nextCursor door als ?cursor=-parameter.

Matchacties

Ster (favoriet), uitsluiten (verbergen) en bekijken (markeren als gelezen) zijn aanbestedingsspecifieke voorkeuren opgeslagen in UserTenderPreference.

Respons: zelfde structuur als het lijstitem van matches.

{ "starred": true }

{ "excluded": true }

Geen actie voor synthetische live-:id-matches (geen rij om te markeren).

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

Taxonomie

Statische referentiecatalogi voor filterwaarden. Taalafhankelijke labels.

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

Respons: boomstructuur divisies → groepen → klassen → categorieën → subcategorieën.

Webhook

Webhook-eindpunten (CRUD, geheimrotatie) zijn op accountniveau — eenmalig gedocumenteerd in Account-API → Webhooks. Dit gedeelte behandelt alleen de leads-specifieke eventpayload (leads.match.created) en HMAC-verificatie.

Eventlevering

Bij een nieuwe match sturen wij een event van het type leads.match.created met een HMAC-SHA256-handtekening in de X-Signature-256 header, idempotentiesleutel in X-Idempotency-Key, en het type in X-Event-Type. Bij een fout proberen we het opnieuw met exponentiële backoff gedurende maximaal ~33 uur.

Herhaalpolicy

Als uw eindpunt een niet-2xx-respons retourneert (of niet binnen 10 s reageert), probeert Veritra het opnieuw met exponentiële backoff: 1 min, 5 min, 30 min, 2 u, 12 u, 24 u. Na 6 mislukte pogingen wordt de webhook als mislukt gemarkeerd en gemarkeerd in het dashboard. De Idempotency-key blijft gelijk bij elke poging — uw eindpunt MOET dedupliceren (anders wordt dezelfde overeenkomst 6× verwerkt).

Eindpunten beheren via API

U kunt webhookeindpunten beheren zonder het dashboard te openen. Limiet: 5 eindpunten per account.

HMAC-handtekeningverificatie

De server ondertekent de payload als HMAC-SHA256(secret, raw_body) en stuurt dit mee in de header X-Signature-256 in het formaat sha256=hex. Verifieer dit in constante tijd, anders is de integratie kwetsbaar voor timing-aanvallen.

// 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": "Bouw in Praag",
    "matchId": "cm…",
    "tender": { "id": "12345", "title": "…", "estimatedValue": 12500000 }
  }
}

E-maildigest

Met emailDigest: true ontvangt u dagelijks een e-mail met een samenvatting van nieuwe aanbestedingen. De digest wordt 's ochtends (05:00 UTC) verzonden naar het e-mailadres van uw account. U kunt deze uitschakelen door het filter te bewerken.

Limieten

Bij overschrijding van de maandlimiet retourneert de API 429 met een Retry-After-header. De limiet wordt op de 1e van de maand gereset.