Primeros pasos

1. Crear una cuenta

Ve a /register y completa tu correo electrónico, nombre y, opcionalmente, el ID de empresa checo (IČO). Si proporcionas el IČO, el nombre de la empresa, el IVA y la dirección se rellenan automáticamente desde el registro ARES.

No introduzcas una contraseña todavía — la establecerás en el siguiente paso tras hacer clic en el enlace de verificación.

2. Verificar el correo electrónico y establecer una contraseña

En unos segundos recibirás un correo electrónico con un enlace de verificación. Haz clic en él. Accederás a una página donde podrás establecer tu contraseña (mín. 8 caracteres).

Una vez establecida la contraseña, habrás iniciado sesión y podrás ir directamente al panel de control.

3. Crear tu primer filtro de licitaciones

En el panel de control, haz clic en Licitaciones → Nuevo filtro. Un filtro es un conjunto de criterios guardados que el sistema utiliza para enviarte las licitaciones coincidentes:

1. Región — una o varias regiones (Praga, Bohemia Central, …)
2. Sector — categoría de licitación (Edificios, Desarrollo TI, …) o código CPV
3. Palabras clave — palabras que deben aparecer en el título o la descripción (p. ej. "reconstrucción de puente")
4. Valor — valor mínimo/máximo esperado de la licitación

La descripción detallada de todos los parámetros de filtro está en la documentación de Lead Watcher.

4. Activar el resumen por correo electrónico

Cada filtro puede tener un resumen diario por correo electrónico. Cada día a las 7:00 recibirás un correo con las licitaciones añadidas ese día que coincidan con tu filtro.

El resumen se activa en el detalle del filtro — interruptor «Resumen por correo electrónico» en la parte superior. Puedes tener varios filtros, cada uno con su propia configuración de resumen.

Hola mundo

Con una clave, la llamada tiene este aspecto:

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

Devuelve JSON con las últimas licitaciones abiertas. Los parámetros de búsqueda completos están en la documentación de Lead Watcher.

Cómo obtener una clave

Tu primera clave de API se crea desde el panel de control: regístrate en la web, verifica tu correo electrónico y, a continuación, en Configuración → Integraciones haz clic en «Generar clave». La clave se muestra una sola vez — guárdala de inmediato (p. ej. en variables de entorno o en un almacén de secretos). Si la pierdes, crea una nueva y elimina la anterior.

Uso de la clave con clientes MCP (Claude Desktop, Cursor, …)

La clave es la misma que para la REST API. Solo difiere la forma en que el cliente la envía: el servidor MCP se ejecuta en /api/mcp y la clave se incluye en la cabecera de handshake X-Api-Key. La configuración completa para Claude Desktop, Cursor y clientes HTTP genéricos está en la documentación de MCP.

Autenticación

Todos los endpoints de /api/v2 se autentican con una única clave API (formato mrw_live_HEX64). La clave puede enviarse como encabezado X-Api-Key o como token 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

La clave lleva la identidad del usuario. Los servicios a los que puede llamar están determinados por la suscripción (consulte la sección Suscripciones). Puede tener hasta 5 claves activas, lo que resulta útil para separar prod / dev / por sistema.

Envoltorio de respuesta

Todos los endpoints de v2 devuelven un envoltorio JSON unificado. Recurso individual bajo data, listas paginadas bajo data + pagination, errores bajo error.

Éxito

// Recurso individual
{ "data": { "id": "…", "field": "…" } }

// Lista paginada
{
  "data": [{ "…": "…" }],
  "pagination": { "nextCursor": "abc123…", "totalCount": 42 }
}

Error

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

Códigos de error estables: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, ENTITLEMENT_REQUIRED, INTERNAL. Los clientes deben ramificar según code, no según message — el estado HTTP se asigna a code automáticamente.

Límites de velocidad

En caso de exceso, la API devuelve HTTP 429 con un encabezado Retry-After (segundos).

Prueba y facturación

Tras crear una cuenta, obtienes una prueba gratuita de 7 días de Lead Watcher — sin tarjeta ni perfil de facturación. Después necesitas una tarjeta registrada o una factura proforma pagada; de lo contrario, el servicio pasa a SUSPENDED y las llamadas posteriores devuelven 403. Sin paquetes por nivel — paga por servicio, cancela cuando quieras.

API de cuenta

Gestione cuenta, claves, facturación y webhooks. Todos los endpoints /api/v2/account/* requieren autenticación con clave.

Equivalente a /profile + /subscriptions + información de apiKey. Útil para la carga inicial en clientes de interfaz.

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

Contraseña y sesión

Claves API

La clave se autentica contra toda la API. Puede tener hasta 5 claves activas. La clave en texto plano solo se devuelve al crearla o rotarla — posteriormente solo puede obtenerse creando una nueva.

{ "label": "Production ERP" }

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

La clave en la respuesta aparece completa únicamente aquí. El servidor almacena únicamente el hash SHA-256; la clave en texto plano no puede recuperarse posteriormente. Si se pierde, cree una nueva y elimine la antigua.

Suscripciones de servicios

Activación de prueba, resumen de estado y cancelación programada en paidUntil/trialEndsAt. Para activar con tarjeta de pago use /billing/checkout.

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

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

{ "cancelAtPeriodEnd": true }

Uso de la API

Agregado diario de llamadas por clave API durante los últimos N días (por defecto 30). Para monitorizar el consumo del límite de tasa.

Facturación

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

Exportación de datos (RGPD)

Cancelación de cuenta

{ "action": "DEACTIVATE" }

Webhooks

Webhooks a nivel de cuenta — un único endpoint cubre todos los filtros y futuros servicios. Cada evento incluye una firma HMAC-SHA256 en X-Signature-256, una clave de idempotencia en X-Idempotency-Key y el tipo en X-Event-Type. Reintento con retroceso exponencial hasta ~33 h.

Máximo 5 endpoints por cuenta. Los eventos admitidos y los esquemas de carga útil están documentados por servicio.

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

Notificaciones

Comentarios

Especificación OpenAPI 3.1

La especificación completa de la API en formato legible por máquina está en /openapi.json. Úsela para generar automáticamente clientes tipados en cualquier lenguaje (TypeScript, Python, Go, Rust, …) o para importar en 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

Códigos de error