Iniziare

1. Crea il tuo account

Vai su /register e inserisci e-mail, nome e facoltativamente la partita IVA dell'azienda. Se si inserisce la partita IVA, la ragione sociale, il codice fiscale e l'indirizzo vengono recuperati automaticamente dal registro ARES.

La password non viene impostata in questa fase — la configurerete nel passaggio successivo dopo aver cliccato sul link di verifica ricevuto via e-mail.

2. Verifica l'e-mail e imposta la password

Entro pochi secondi riceverete un'e-mail con il link di verifica. Cliccateci sopra. Si aprirà una pagina in cui potrete impostare la password (min. 8 caratteri).

Dopo aver impostato la password, sarete autenticati e potrete procedere direttamente alla dashboard.

3. Crea il tuo primo filtro gare

Nella dashboard, clicca su Gare → Nuovo filtro. Il filtro è un insieme salvato di criteri in base ai quali il sistema invia le gare:

1. Regione — una o più regioni (Roma, Lombardia, …)
2. Settore — categoria di gare (Edilizia, Sviluppo IT, …) o codice CPV
3. Parole chiave — termini che devono essere presenti nel titolo o nella descrizione (es. "ristrutturazione ponte")
4. Valore — valore stimato minimo/massimo dell'appalto

La descrizione dettagliata di tutti i parametri del filtro è nella documentazione di Veritra.

4. Attivate l'email digest

Per ogni filtro è possibile attivare un email digest giornaliero. Ogni giorno alle 7:00 riceverete un'email con le gare d'appalto aggiunte in quella giornata che corrispondono al vostro filtro.

Il digest si attiva direttamente nel dettaglio del filtro — interruttore "Email digest" nella parte superiore. È possibile avere più filtri, ciascuno con la propria impostazione digest.

Hello world

Una volta ottenuta la chiave, si chiama l'API nel seguente modo:

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

Restituisce un JSON con le gare d'appalto aperte più recenti. I parametri di ricerca completi sono nella documentazione di Veritra.

Come ottenere la chiave

La prima chiave API viene creata tramite la dashboard: registratevi sul sito, verificate l'e-mail e nella sezione Impostazioni → Integrazioni cliccate su "Genera chiave". La chiave viene visualizzata una sola volta — salvatela immediatamente (ad es. in env / secrets store). In caso di smarrimento, potrete generarne una nuova ed eliminare quella precedente.

Utilizzo con client MCP (Claude Desktop, Cursor, …)

La chiave è la stessa utilizzata per il REST API. Cambia solo il modo in cui il client la invia: il server MCP è in esecuzione su /api/mcp e la chiave viene inserita nell'header X-Api-Key dell'handshake. La configurazione completa per Claude Desktop, Cursor e client HTTP generici è nella documentazione MCP.

Autenticazione

Tutti gli endpoint /api/v2 vengono autenticati con un'unica chiave API (formato mrw_live_HEX64). La chiave può essere inviata come header X-Api-Key oppure come Bearer token:

# 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

La chiave porta l'identità dell'utente. I servizi che può invocare sono determinati dall'abbonamento attivo (cfr. sezione Subscriptions). È possibile avere fino a 5 chiavi attive contemporaneamente — utile per separare gli ambienti prod / dev / per-sistema.

Response envelope

Tutti gli endpoint v2 restituiscono un JSON envelope uniforme. Singola risorsa sotto data, liste paginate sotto data + pagination, errori sotto error.

Successo

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

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

Errore

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

Error code stabili: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, ENTITLEMENT_REQUIRED, INTERNAL. Il client deve ramificare sul code, non sul message — lo stato HTTP viene mappato automaticamente sul codice.

Limiti di frequenza (Rate limit)

In caso di superamento, l'API restituisce HTTP 429 e l'intestazione Retry-After (secondi).

Periodo di prova e fatturazione

Dopo la creazione dell'account si dispone di 1 giorno di prova gratuita per il Monitoraggio Gare d'Appalto — senza carta, senza profilo di fatturazione. Successivamente è necessario disporre di una carta collegata o di una fattura di acconto già pagata, altrimenti il servizio passerà in modalità SUSPENDED e le chiamate successive restituiranno 403. Nessun pacchetto a livelli — si paga per il singolo servizio, con possibilità di disdetta in qualsiasi momento.

Account API

Gestione dell'account, delle chiavi, della fatturazione e dei webhook. Tutti gli endpoint /api/v2/account/* richiedono l'autenticazione tramite chiave.

Equivalente di /profile + /subscriptions + informazioni apiKey. Adatto al caricamento iniziale nei client 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 }
  }
}

Password e sessione

Chiavi API

La chiave autentica l'accesso all'intero API. È possibile avere fino a 5 chiavi attive. La chiave raw viene restituita solo al momento della creazione o della rotazione — in seguito è recuperabile esclusivamente creandone una nuova.

{ "label": "Production ERP" }

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

La chiave nella response è in forma completa solo qui. Il server conserva solo l'hash SHA-256; la raw key non è recuperabile in seguito. In caso di perdita, crearne una nuova ed eliminare la vecchia.

Sottoscrizione dei servizi

Attivazione del trial, panoramica dello stato, annullamento pianificato alla data paidUntil/trialEndsAt. Per le attivazioni a pagamento (con carta) utilizzare /billing/checkout.

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

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

{ "cancelAtPeriodEnd": true }

Utilizzo API

Aggregato giornaliero del numero di chiamate API della chiave negli ultimi N giorni (default 30). Per il monitoraggio del consumo del rate limit.

Fatturazione

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

Esportazione dati (GDPR)

Chiusura dell'account

{ "action": "DEACTIVATE" }

Webhook

Webhook a livello di account — un singolo endpoint copre tutti i filtri e i servizi futuri. Ogni evento porta una firma HMAC-SHA256 in X-Signature-256, chiave di idempotenza in X-Idempotency-Key e tipo in X-Event-Type. Retry con backoff esponenziale fino a ~33 h.

Max 5 endpoint per account. Gli eventi supportati e gli schemi payload sono disponibili nella documentazione di ciascun servizio.

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

Notifiche

Feedback

Specifiche OpenAPI 3.1

La specifica API completa e leggibile da macchina è disponibile su /openapi.json. Utilizzarla per la generazione automatica di client tipizzati in qualsiasi linguaggio (TypeScript, Python, Go, Rust, …) o per l'importazione in 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

Codici di errore