入札監視

概念

すべてのエンドポイントで登場する4つの用語：

• Tender — ポータル（NEN、VVZ、E-ZAK、TenderArena など）からの個別の案件。数値IDで識別されます。
• Filter — 保存された条件セット（地域、業種、キーワード、金額）。新しい案件が条件を満たすと、マッチが生成されます。
• Match — フィルターに合致した新規案件。（tender × filter）の紐付け＋タイムスタンプ＋ステータス（監視中 / 非表示 / 既読）を表します。
• Taxonomy — 地域（NUTS）、業種（industryタグ）、CPVコードのコードリスト。案件の分類に使用します。

クイックスタート

フィルターの設定方法は2通りあります。結果はいずれも同じであり、フィルターはいつでもどちらの方法でも編集可能です。

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

上部はアドホック検索です。継続的なモニタリング（条件に合致する新規案件の通知）を希望する場合は、フィルター＋Webhook／メールダイジェストをご利用ください — 後述を参照。

案件検索（アドホック）

すべてのアクティブな入札案件を横断的に一度だけ検索する場合に使用します。保存済みフィルターは使用せず、パラメーターはクエリ文字列で直接指定します。

クエリパラメーター

例

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

レスポンス：id、title、description、estimatedValue、deadlineAt、contractingAuthority、documents[]、starred、excluded フィールドを持つ data オブジェクト。

リクエストボディに recipientEmail を含めることで、別のメールアドレスへ転送できます。デフォルトは user.email です。

クエリ：?url=:original&kind=docx|xlsx。許可ホスト：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)

カタログ・オートコンプリート（公開、認証不要）

UIドロップダウンおよびフィルター作成用。サーバーサイドで1時間キャッシュ。公開エンドポイントのため認証不要。

フィルタリング可能な項目と許容値

フィルターは以下のフィールドで構成されます。`name` を除きすべて任意項目です。空フィールド = 当該ディメンションに制限なし。

regions string[]

指定国のNUTSリージョン（?country=CZ）。ロケールごとのラベル付き。

特定国のNUTSツリー全体を取得するには、以下を使用してください：

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[] 推奨

マルチタグによる業種分類。案件には複数のタグを付与できます（例：改修工事の場合「stav_pozemni」+「stav_remesla」）。指定したタグのうち少なくとも1つに一致する案件をフィルタリングします（JSON_OVERLAPS）。

CPVよりindustryTagsを優先すべき理由： 当社のindustryTagsは、案件名・説明のLLM分類、CPVマッピング、正規表現ヒントを組み合わせて生成されます。CPVコードの割り当てが不正確な発注者の案件も適切に捕捉できます。CPVフィルターは精度が高い反面、発注者の規律に依存しており、チェコ共和国ではその水準が低い傾向にあります。

categories string[] 精度低

任意の長さのCPV（共通調達語彙）プレフィックス — `LIKE 'prefix%'` によるマッチング。例：「45」ですべての建設部門、「4523」で土木工事のみ、「45316110」で街路照明のみに一致します。

keywords string[]

案件名および説明文に対するLIKEマッチング。大文字・小文字を区別しません。項目間はOR条件。industryTags/CPVでは捕捉できない場合（例：テキスト中の特定の案件種別）の補完手段として有効です。

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

minValue / maxValue number | null

案件の推定価格（チェココルナ）の範囲。minValueのみ、maxValueのみ、または両方を指定できます。

emailDigest boolean

trueに設定すると、このフィルターの新規マッチの概要メールが1日1回（UTC 5:00）送信されます。デフォルトはtrueです。フィルターの編集により無効化できます。Webhookはアカウントレベルで個別に設定します（以下のセクションを参照）。

name string · active boolean

`name` — 最大120文字、必須。`active` — falseにすると、フィルターがcronで実行されません（新規マッチ、ダイジェスト、Webhookなし）。削除せずに一時停止できます。

フィルタリングロジック

フィールドは以下のように組み合わされます：

MATCH = (発注者.NUTS3 ∈ expand(regions))
     AND (minValue ≤ estimatedValue ≤ maxValue  または  estimatedValueがnullまたは0)
     AND (industry_or_cpv  または  keyword_match)

# expand(regions): NUTSコードはNUTS 3のリーフノードに展開されます
# (CZ → 14州、CZ01 → CZ010、CZ010 → CZ010)。

industry_or_cpv:
   industryTags指定あり  →  JSON_OVERLAPS(industryTags, tender.industryTags)
   それ以外でcategories指定あり  →  tender.cpvCode LIKE ANY (categories + "%")
   それ以外                       →  false   （業種フィルターなし）

keyword_match:
   keywords指定あり      →  tender.title または description LIKE ANY (%kw%)
   それ以外              →  false

# industryTags / categories / keywords をいずれも指定しない場合、
# regionsおよび価格範囲を満たすすべての案件が返されます。

industryTagsはcategoriesより優先されます — 両方指定した場合、industryTagsのみが使用されます（categoriesは無視されます）。keywordsはindustry_or_cpvとOR条件として独立して機能します。

フィルター管理エンドポイント

フィルターの管理には管理キーを使用してください（mrw_live_…）。独立したレート制限を持ち、LEADSクレジットを消費しないため、フィルターの管理は毎日の案件取得に影響しません。

ボディパラメータ（POST / PUT）— 共通

Webhookはフィルターに設定されなくなりました — セクションを参照してください Webhook 以下（アカウントレベルのエンドポイント）。フィールド webhookUrl はセキュリティ上の理由によりHTTP 410で拒否されます。

例

プラハの建設案件（50万CZK超）

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

IT開発およびSWライセンス（全地域）

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IT開発 + SWライセンス",
    "industryTags": ["it_development", "it_licensing", "it_data_ai"],
    "keywords": ["informační systém"、"modul"]
  }' \
  https://veritra.io/api/v2/leads/filters

公共照明（CZ）— タグ＋キーワードの組み合わせ

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "公共照明（CZ）",
    "industryTags": ["goods_electrical", "con_civil"],
    "keywords": ["osvětlení"、"VO "、"veřejné osvětlení"、"lampy"],
    "minValue": 200000
  }' \
  https://veritra.io/api/v2/leads/filters

フィルターを無効化する

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>

配信方式 — Webhook vs ポーリング

新規案件を自社ERPに取り込む方法は2種類あります。多くのインテグレーターは両方を組み合わせて使用します。

マッチの取得

クエリパラメータ

返却されたマッチは自動的にdelivered=trueとしてマークされます。リクエストごとに1クレジットを消費します。

matchId のフォーマット

matchId は取得元に応じて2種類のフォーマットがあります：

• cm… （cuid プレフィックス）— 事前計算済み LeadMatch テーブル（毎日マッチ済み案件をペアリングするcronジョブ）から返されます。呼び出し間で安定しており、mark-as-viewed に使用可能です。
• live-12345 synthetic プレフィックスは、search / browse モード（qText パラメータ、view=starred/excluded）経由でライブ検出されたマッチに付与されます。LeadMatch テーブルには存在しないため、mark-as-viewed は無操作（no-op）となります。tenderId はハイフン以降のサフィックスです。

例

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

レスポンス

{
  "data": [
    {
      "matchId": "cm…",
      "filterId": "cm…",
      "filterName": "プラハ建設案件",
      "matchedAt": "2026-04-03T06:00:00.000Z",
      "viewedAt": null,
      "delivered": true,
      "tender": {
        "id": 12345,
        "title": "橋梁No.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 }
}

次のページを取得するには、pagination.nextCursor を ?cursor= パラメータとして送信してください。

マッチに対するアクション

スター（お気に入り登録）、除外（非表示）、閲覧（既読マーク）はテンダー単位の設定であり、UserTenderPreference に保存されます。

レスポンス：matches リストアイテムと同一の構造。

{ "starred": true }

{ "excluded": true }

synthetic live-:id マッチの場合はno-op（マークすべき行が存在しません）。

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

タクソノミー

フィルター値用の静的リファレンスカタログ。ロケール対応ラベル付き。

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

レスポンス: ツリー構造 セクション → グループ → クラス → カテゴリ → サブカテゴリ。

Webhook

Webhookエンドポイント（CRUD、シークレットローテーション）はアカウントレベルの機能です — Account API → Webhook にて一括して説明しています。ここではリード固有のイベントペイロード（leads.match.created）とHMAC検証についてのみ説明します。

イベントの配信

新しいマッチが発生した際、イベントタイプ leads.match.created をヘッダー内のHMAC-SHA256署名とともに送信します。ヘッダー X-Signature-256 にはidempotencyキー、X-Idempotency-Key にはタイプを含めます。X-Event-Type。障害時は最大約33時間、指数バックオフによるリトライを行います。

リトライポリシー

エンドポイントが non-2xx を返した場合（または10秒以内に応答しない場合）、Veritra は指数バックオフでリトライします：1分、5分、30分、2時間、12時間、24時間。6回失敗するとWebhookは failed としてマークされ、ダッシュボードに警告が表示されます。冪等性キーは各試行で同一のため、エンドポイントは重複排除を必ず実装してください（未実装の場合、同一マッチが最大6回処理されます）。

APIを介したエンドポイント管理

Webhookエンドポイントをダッシュボードにアクセスせずに管理できます。アカウントあたり最大5エンドポイントまで。

HMAC署名検証

サーバーは HMAC-SHA256(secret, raw_body) でペイロードに署名し、<code>sha256=hex</code> 形式で <code>X-Signature-256</code> ヘッダーに付与して送信します。タイミング攻撃への脆弱性を防ぐため、定数時間比較（constant-time comparison）で検証してください。

// 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": "プラハ建設案件",
    "matchId": "cm…",
    "tender": { "id": "12345", "title": "…", "estimatedValue": 12500000 }
  }
}

メールダイジェスト

S emailDigest: trueを設定すると、新着案件の概要を記載したメールが毎日届きます。ダイジェストは毎朝（UTC 5:00）アカウントに登録されたメールアドレスへ送信されます。フィルターを編集することで無効化できます。

制限

月次制限を超過すると、APIは Retry-After ヘッダー付きで 429 を返します。制限は毎月1日にリセットされます。