Erste Schritte

1. Konto anlegen

Gehen Sie auf /register und füllen Sie E-Mail, Name und optional die tschechische Firmen-ID (IČO) aus. Bei Angabe von IČO werden Firmenname, USt-ID und Adresse automatisch aus dem ARES-Register geladen.

Geben Sie noch kein Passwort ein — Sie setzen es im nächsten Schritt nach Klick auf den Bestätigungslink.

2. E-Mail bestätigen und Passwort setzen

Innerhalb weniger Sekunden erhalten Sie eine E-Mail mit einem Bestätigungslink. Klicken Sie ihn an. Sie landen auf einer Seite, auf der Sie Ihr Passwort setzen (mind. 8 Zeichen).

Nach dem Setzen sind Sie angemeldet und können direkt ins Dashboard.

3. Ersten Ausschreibungsfilter anlegen

Klicken Sie im Dashboard auf Ausschreibungen → Neuer Filter. Ein Filter ist ein gespeichertes Kriterien-Set, anhand dessen das System passende Ausschreibungen zuschickt:

1. Region — Region oder mehrere (Prag, Mittelböhmen, …)
2. Branche — Ausschreibungs-Kategorie (Hochbau, IT-Entwicklung, …) oder CPV-Code
3. Schlüsselwörter — Wörter, die im Titel oder in der Beschreibung vorkommen müssen (z. B. „Brückensanierung")
4. Wert — min/max geschätzter Auftragswert

Detaillierte Beschreibung aller Filter-Parameter in der Auftrags-Watcher-Doku.

4. E-Mail-Digest aktivieren

Für jeden Filter können Sie einen täglichen E-Mail-Digest aktivieren. Jeden Tag um 7:00 erhalten Sie eine E-Mail mit den an diesem Tag hinzugekommenen Ausschreibungen, die zu Ihrem Filter passen.

Der Digest wird im Filter-Detail aktiviert — Schalter „E-Mail-Digest" oben. Sie können mehrere Filter haben, jeder mit eigener Digest-Einstellung.

Hello world

Mit Schlüssel sieht der Aufruf so aus:

curl -H "X-Api-Key: mrw_live_…" \
  "https://mrickwood.cz/api/v2/leads/tenders/search?qText=bruecken&limit=5"

Gibt JSON mit den neuesten offenen Ausschreibungen zurück. Alle Suchparameter sind in der Auftrags-Watcher-Doku.

Schlüssel erhalten

Den ersten API-Key erhalten Sie über das Dashboard: Registrieren Sie sich auf der Website, bestätigen Sie Ihre E-Mail, dann unter Einstellungen → Integrationen auf „Key generieren" klicken. Der Key wird einmalig angezeigt — sofort speichern (z. B. in env / Secrets-Store). Bei Verlust erstellen Sie einen neuen und löschen den alten.

Verwendung mit MCP-Clients (Claude Desktop, Cursor, …)

Der Schlüssel ist derselbe wie für die REST-API. Lediglich die Übergabe unterscheidet sich: Der MCP-Server läuft auf /api/mcp und der Schlüssel geht in den X-Api-Key-Handshake-Header. Vollständige Einrichtung für Claude Desktop, Cursor und generische HTTP-Clients in der MCP-Dokumentation.

Authentifizierung

Alle /api/v2-Endpoints authentifizieren sich mit einem einzelnen API-Schlüssel (Format mrw_live_HEX64). Der Schlüssel kann als X-Api-Key-Header oder als Bearer-Token gesendet werden:

# 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

Der Schlüssel trägt die Benutzeridentität. Welche Services er aufrufen darf, bestimmt das Abonnement (siehe Abschnitt Abonnements). Bis zu 5 aktive Schlüssel möglich — nützlich zur Trennung von Prod / Dev / pro System.

Response-Envelope

Alle v2-Endpoints liefern einen einheitlichen JSON-Envelope. Einzelne Ressource unter data, paginierte Listen unter data + pagination, Fehler unter error.

Erfolg

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

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

Fehler

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

Stabile Error-Codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, ENTITLEMENT_REQUIRED, INTERNAL. Clients sollten auf code verzweigen, nicht auf message — HTTP-Status mappt automatisch.

Rate Limits

Bei Überschreitung antwortet die API mit HTTP 429 und einem Header Retry-After (Sekunden).

Testphase und Abrechnung

Nach Erstellung des Kontos erhalten Sie eine 1-tägige kostenlose Testphase des Auftrags-Watchers — ohne Karte, ohne Abrechnungsprofil. Danach brauchen Sie eine Karte oder eine bezahlte Vorab-Rechnung, sonst geht der Service in SUSPENDED und weitere Aufrufe geben 403 zurück. Keine Tier-Bundles — Bezahlung pro Service, jederzeit kündbar.

Account-API

Verwaltung von Konto, Schlüsseln, Abrechnung und Webhooks. Alle /api/v2/account/*-Endpoints erfordern Schlüssel-Authentifizierung.

Äquivalent zu /profile + /subscriptions + apiKey-Info. Nützlich für den Initial-Load in UI-Clients.

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

Passwort und Session

API-Schlüssel

Der Schlüssel authentifiziert gegenüber dem gesamten API. Bis zu 5 aktive Schlüssel möglich. Der Raw-Key wird nur bei Erstellung oder Rotation zurückgegeben — danach nur durch Erstellung eines neuen abrufbar.

{ "label": "Production ERP" }

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

Der Schlüssel ist in der Response nur hier vollständig. Der Server speichert nur den SHA-256-Hash; der Raw-Key kann später nicht mehr abgerufen werden. Bei Verlust einen neuen erstellen und den alten löschen.

Service-Abonnements

Test-Aktivierung, Status-Übersicht, geplante Kündigung zu paidUntil/trialEndsAt. Für kostenpflichtige Aktivierung (Karte) nutzen Sie /billing/checkout.

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

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

{ "cancelAtPeriodEnd": true }

API-Nutzung

Tagesweise Aggregation der API-Aufrufe pro Schlüssel für die letzten N Tage (Standard 30). Für Rate-Limit-Monitoring.

Abrechnung

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

Datenexport (DSGVO)

Kontolöschung

{ "action": "DEACTIVATE" }

Webhooks

Account-Level-Webhooks — ein Endpoint deckt alle Filter und zukünftige Services ab. Jedes Event trägt eine HMAC-SHA256-Signatur in X-Signature-256, einen Idempotency-Key in X-Idempotency-Key und den Typ in X-Event-Type. Retry mit exponentiellem Backoff bis zu ~33 h.

Max. 5 Endpoints pro Konto. Unterstützte Events und Payload-Schemas sind in der jeweiligen Service-Doku.

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

Benachrichtigungen

Feedback

OpenAPI-3.1-Spec

Die vollständige maschinenlesbare API-Spec finden Sie unter /openapi.json. Nutzen Sie sie zum Auto-Generieren typisierter Clients in beliebiger Sprache (TypeScript, Python, Go, Rust, …) oder zum Import in Postman / Insomnia / Swagger UI.

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

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

Fehlercodes