はじめに

1. アカウントを作成する

こちらにアクセスしてください：/register メールアドレス、氏名、および任意で法人番号（IČO）を入力してください。IČO を入力すると、会社名・税務番号（DIČ）・住所が ARES レジストリから自動的に取得されます。

この時点ではパスワードを設定しません。メール内の確認リンクをクリックした後の次のステップで設定します。

2. メールアドレスを確認してパスワードを設定する

数秒以内に確認リンク付きのメールが届きます。リンクをクリックすると、パスワード設定ページが開きます（最低8文字）。

パスワードを設定するとログイン状態になり、そのままダッシュボードに進むことができます。

3. 最初の案件フィルターを作成する

ダッシュボードで「案件」→「新しいフィルター」をクリックしてください。フィルターとは、システムが案件を通知する際に使用する保存済み条件セットです：

1. 地域 — 都市または複数の地域（プラハ、中ボヘミア州など）
2. 分野 — 案件のカテゴリー（建築工事、IT開発など）または CPV コード
3. キーワード — 件名または説明に含まれる必要がある語句（例：「橋梁改修」）
4. 金額 — 案件の推定価格の最小値／最大値

フィルターの全パラメーターの詳細については、案件モニタードキュメントをご覧ください。

4. メールダイジェストを有効にする

各フィルターに対して、日次メールダイジェストを有効にすることができます。毎日7:00に、その日に追加されたフィルター条件に一致する案件を記載したメールが届きます。

ダイジェストはフィルターの詳細画面から直接有効化できます。上部にある「Email digest」トグルをオンにしてください。複数のフィルターを設定でき、それぞれに個別のダイジェスト設定が可能です。

Hello world

キーを取得したら、次のようにAPIを呼び出します：

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

最新の公開案件をJSON形式で返します。検索パラメーターの詳細については案件モニタードキュメントをご参照ください。

キーの取得方法

最初のAPIキーはダッシュボードから作成します。Webサイトでアカウント登録後、メールアドレスを確認し、設定 → 連携から「キーを生成」をクリックしてください。キーは一度だけ表示されます。すぐに保存してください（例：環境変数やシークレットストアへ）。紛失した場合は新しいキーを作成し、古いキーを削除してください。

MCPクライアントでの使用（Claude Desktop、Cursor など）

キーはREST APIと共通です。異なるのはクライアントがキーを送信する方法のみです。MCPサーバーは /api/mcp で稼働し、キーはハンドシェイクの X-Api-Key ヘッダーで送信します。Claude Desktop・Cursor・汎用HTTPクライアントの完全なセットアップ手順はMCPドキュメントをご覧ください。

認証

すべての /api/v2 エンドポイントは、単一のAPIキー（形式：mrw_live_HEX64）で認証します。キーは X-Api-Key ヘッダーまたはBearerトークンとして送信できます：

# 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

キーはユーザーの識別情報を保持します。呼び出し可能なサービスは、そのユーザーのサブスクリプション（Subscriptionsセクション参照）によって制御されます。最大5つのアクティブなキーを保持できます。本番/開発/システムごとの分離に便利です。

レスポンスエンベロープ

すべてのv2エンドポイントは統一されたJSONエンベロープを返します。単一リソースは data、ページネーション付きリストは data + pagination、エラーは error の下に格納されます。

成功

// Single resource
{ "data": { "id": "…", "field": "…" } }

// Paginated list
{
  "data": [{ "…": "…" }],
  "pagination": { "nextCursor": "abc123…", "totalCount": 42 }
}

エラー

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'url' must be a valid HTTPS URL.",
    "details": { "field": "url" }
  }
}

固定エラーコード一覧：UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, ENTITLEMENT_REQUIRED, INTERNALクライアントは message ではなく code で分岐処理を行ってください。HTTPステータスはコードに自動的にマッピングされます。

レート制限

制限を超えた場合、API は HTTP 429 およびヘッダー Retry-After（秒）を返します。

トライアルと請求

アカウント作成後、1日間の無料トライアル期間 が Hlídač zakázek でご利用いただけます — カード不要、請求プロファイル不要。その後は、カードの登録または前払い請求書のお支払いが必要です。未対応の場合、サービスは SUSPENDED に移行し、以降の呼び出しは 403 を返します。階層型パッケージはありません — 利用したサービス分のみお支払いいただき、いつでもキャンセル可能です。

アカウント API

アカウント、キー、請求、Webhook の管理。すべての /api/v2/account/* エンドポイントはキーによる認証が必要です。

/profile + /subscriptions + apiKey 情報のまとめ。UI クライアントの初期読み込みに適しています。

{
  "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 }
  }
}

パスワードとセッション

API キー

キーは API 全体に対して認証を行います。最大5つのアクティブなキーを保持できます。生のキーは作成時またはローテーション時にのみ返されます — その後は新しいキーを作成することでのみ再取得できます。

{ "label": "Production ERP" }

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

レスポンス内のキーが完全な形式で返されるのはここだけです。 サーバーは SHA-256 ハッシュのみを保存します。生のキーは後から取得できません。紛失した場合は新しいキーを作成し、古いキーを削除してください。

サービスのサブスクリプション

トライアルの有効化、ステータスの概要、paidUntil/trialEndsAtの日付に基づく解約予約。有料での有効化（カード払い）には /billing/checkout をご利用ください。

{ "service": "LEADS", "scope": "CZ", "mode": "trial" }

{ "service": "LEADS", "scopes": ["CZ","SK","DE"], "mode": "trial" }

{ "cancelAtPeriodEnd": true }

API使用状況

過去N日間（デフォルト30日）のAPIキーの日次呼び出し集計。レートリミット消費のモニタリング用。

請求

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

データエクスポート（GDPR）

アカウントの削除

{ "action": "DEACTIVATE" }

Webhook

アカウントレベルのWebhook — 1つのエンドポイントで全フィルターおよび将来のサービスをカバーします。各イベントはHMAC-SHA256署名を X-Signature-256 に、冪等性キーを X-Idempotency-Key に、イベントタイプを X-Event-Type に含みます。指数バックオフによる最大約33時間のリトライ。

アカウントあたり最大5エンドポイント。 サポートされているイベントとペイロードスキーマは、各サービスのドキュメントをご参照ください。

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

通知

フィードバック

OpenAPI 3.1 仕様

完全な機械可読のAPI仕様は以下でご確認いただけます：/openapi.json。任意の言語（TypeScript、Python、Go、Rust など）での型付きクライアントの自動生成、またはPostman / Insomnia / Swagger UIへのインポートにご利用ください。

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

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

エラーコード