Monitor de licitaciones

Conceptos

Cuatro términos que aparecerán en todos los endpoints:

• Tender — una licitación individual de un portal (NEN, VVZ, E-ZAK, TenderArena, etc.). Identificada por un ID numérico.
• Filter — un conjunto guardado de criterios (región, sector, palabras clave, valor). Cuando una nueva licitación cumple los criterios, se genera una coincidencia.
• Match — una nueva licitación que ha encajado en su filtro. Representa el vínculo (licitación × filtro) + marca de tiempo + su estado (destacada / excluida / vista).
• Taxonomy — vocabularios controlados para regiones (NUTS), sectores (etiquetas de industria) y códigos CPV utilizados para clasificar licitaciones.

Inicio rápido

Los filtros pueden configurarse de dos maneras — el resultado es idéntico y un filtro puede editarse a través de cualquiera de las vías en cualquier momento.

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

Lo anterior es una búsqueda ad hoc. Para la monitorización continua (nuevas licitaciones que coincidan con sus criterios), utilice filtros + webhook/resumen por correo — consulte más adelante.

Búsqueda de licitaciones (ad hoc)

Para búsquedas puntuales en todas las licitaciones activas. No utiliza un filtro guardado — los parámetros se incluyen directamente en la cadena de consulta.

Parámetros de consulta

Ejemplo

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

Respuesta: { data: { id, title, description, estimatedValue, deadlineAt, contractingAuthority, documents[], starred, excluded } }.

El cuerpo puede contener recipientEmail para reenviar a un correo diferente. Por defecto, se usa user.email.

Consulta: ?url=:original&kind=docx|xlsx. Hosts permitidos: 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)

Catálogo y autocompletado (público, sin clave)

Para desplegables de interfaz y creación de filtros. Caché en servidor de 1 h. Público, sin autenticación requerida.

Campos del filtro y valores permitidos

Un filtro está compuesto por los campos que se indican a continuación. Todos son opcionales, excepto `name`. Un campo vacío significa que no hay restricción en esa dimensión.

regions string[]

Regiones NUTS del país indicado (?country=CZ) con etiquetas adaptadas al idioma.

Para obtener el árbol NUTS completo de un país específico, utilice:

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[] Recomendado

Clasificación sectorial por múltiples etiquetas. Una licitación puede tener varias etiquetas (p. ej., 'stav_pozemni' + 'stav_remesla' para una renovación). El filtro coincide con una licitación si al menos una de las etiquetas solicitadas está establecida (JSON_OVERLAPS).

Por qué preferir industryTags frente a CPV: Nuestros industryTags combinan la clasificación por LLM del título/descripción de la licitación con el mapeo CPV y patrones regex, lo que permite detectar licitaciones relevantes incluso cuando la autoridad asignó el CPV de forma descuidada. Un filtro CPV puro es exacto, pero depende del rigor de la autoridad contratante, que es escaso en CZ.

categories string[] Menos preciso

Prefijos CPV (Vocabulario Común de Contratación Pública) de cualquier longitud, comparados mediante `LIKE 'prefix%'`. Así, '45' captura todas las divisiones de construcción, '4523' solo ingeniería civil y '45316110' solo alumbrado público.

keywords string[]

Coincidencia LIKE en el título y la descripción de la licitación. Sin distinción entre mayúsculas y minúsculas. OR entre elementos. Útil como red de seguridad si industryTags/CPV no capturan todo (p. ej., un tipo de licitación específico que solo aparece en el texto).

"keywords": ["reconstruction", "lighting", "kindergarten"]

minValue / maxValue number | null

Rango del valor estimado de la licitación en CZK. Puede establecer solo minValue, solo maxValue o ambos.

emailDigest boolean

Si está activado, recibirá un único correo electrónico diario (5:00 UTC) con un resumen de las nuevas coincidencias de este filtro. Valor predeterminado: true. Desactívelo editando el filtro. Los webhooks se configuran por separado, a nivel de cuenta (véase más abajo).

name string · active boolean

`name` — máx. 120 caracteres, obligatorio. `active` — si es false, el filtro se excluye del cron (sin nuevas coincidencias, sin resumen, sin webhook). Úselo para pausar sin eliminar.

Lógica del filtro

Los campos se combinan de la siguiente manera:

MATCH = (authority.NUTS3 ∈ expand(regions))
     AND (minValue ≤ estimatedValue ≤ maxValue  OR  estimatedValue is null or 0)
     AND (industry_or_cpv  OR  keyword_match)

# expand(regions): los códigos NUTS se expanden hasta las hojas NUTS 3
# (CZ → 14 regiones, CZ01 → CZ010, CZ010 → CZ010).

industry_or_cpv:
   if    industryTags set  →  JSON_OVERLAPS(industryTags, tender.industryTags)
   elif  categories set    →  tender.cpvCode LIKE ANY (categories + "%")
   else                    →  false   (no se aplica filtro de sector)

keyword_match:
   if    keywords set      →  tender.title or description LIKE ANY (%kw%)
   else                    →  false

# Si no establece industryTags / categories / keywords,
# se devuelven todas las licitaciones que coincidan con regions y el rango de valor.

industryTags tiene prioridad sobre categories — si establece ambos, solo se utiliza industryTags (categories se ignora). keywords funcionan de forma independiente (se aplica OR con industry_or_cpv).

Endpoints de gestión de filtros

Use la clave de gestión (mrw_live_…) para gestionar filtros. Tiene límites de velocidad independientes y no consume créditos LEADS, por lo que la gestión de filtros no afecta a la recuperación diaria de leads.

Parámetros del cuerpo (POST / PUT) — compartidos

Los webhooks ya no se configuran por filtro — consulte la Webhook sección más abajo (endpoints a nivel de cuenta). El webhookUrl campo se rechaza con HTTP 410 por razones de seguridad.

Ejemplos

Construcción en Praga por encima de 500 000 CZK

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

Desarrollo TI y licencias de SW (todas las regiones)

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Desarrollo TI + licencias de SW",
    "industryTags": ["it_development", "it_licensing", "it_data_ai"],
    "keywords": ["sistema de información", "módulo"]
  }' \
  https://veritra.io/api/v2/leads/filters

Alumbrado público (CZ) — combinación de etiquetas y palabras clave

curl -X POST -H "X-Api-Key: mrw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alumbrado público (CZ)",
    "industryTags": ["goods_electrical", "con_civil"],
    "keywords": ["alumbrado", "farola", "alumbrado público", "lámparas"],
    "minValue": 200000
  }' \
  https://veritra.io/api/v2/leads/filters

Desactivar un filtro

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>

Entrega — webhook vs. sondeo

Dos formas de incorporar nuevas licitaciones a su ERP. La mayoría de los integradores combinan ambas.

Obteniendo coincidencias

Parámetros de consulta

Las coincidencias devueltas se marcan automáticamente como delivered=true. Cada solicitud consume 1 crédito.

Formatos de matchId

matchId tiene dos formatos según el origen:

• cm… (prefijo cuid) — devuelto desde la tabla LeadMatch precomputada (cron diario). Estable entre llamadas; permite usar mark-as-viewed.
• live-12345 Prefijo sintético para coincidencias detectadas en tiempo real mediante búsqueda / modo exploración (parámetro qText, view=starred/excluded). No figura en la tabla LeadMatch → mark-as-viewed es una operación sin efecto. tenderId es el sufijo tras el guion.

Ejemplo

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

Respuesta

{
  "data": [
    {
      "matchId": "cm…",
      "filterId": "cm…",
      "filterName": "Construcción en Praga",
      "matchedAt": "2026-04-03T06:00:00.000Z",
      "viewedAt": null,
      "delivered": true,
      "tender": {
        "id": 12345,
        "title": "Reconstrucción del puente n.º de reg. 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 }
}

Para la página siguiente, pase pagination.nextCursor como parámetro ?cursor=.

Acciones sobre coincidencias

Destacar (favorito), excluir (ocultar) y ver (marcar como leído) son preferencias por licitación almacenadas en UserTenderPreference.

Respuesta: misma estructura que el elemento de la lista de coincidencias.

{ "starred": true }

{ "excluded": true }

Sin efecto para coincidencias sintéticas live-:id (no hay fila que marcar).

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

Taxonomía

Catálogos de referencia estáticos para valores de filtro. Labels adaptados al idioma.

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

Respuesta: estructura de árbol divisiones → grupos → clases → categorías → subcategorías.

Webhook

Los endpoints de webhook (CRUD, rotación de secreto) son a nivel de cuenta — documentados una sola vez en API de cuenta → Webhooks. Esta sección cubre únicamente el payload del evento específico de leads (leads.match.created) y la verificación HMAC.

Entrega de eventos

Ante una nueva coincidencia, enviamos un evento de tipo leads.match.created con una firma HMAC-SHA256 en el encabezado X-Signature-256 encabezado, clave de idempotencia en X-Idempotency-Key y el tipo en X-Event-Type. En caso de fallo, reintentamos con retroceso exponencial durante un máximo de ~33 horas.

Política de reintentos

Si su endpoint devuelve un código no 2xx (o no responde en 10 s), Veritra reintenta con retroceso exponencial: 1 min, 5 min, 30 min, 2 h, 12 h, 24 h. Tras 6 fallos, el webhook se marca como fallido y se señala en el panel. La clave de idempotencia permanece igual en cada reintento — su endpoint DEBE deduplicar (de lo contrario, la misma coincidencia se procesa 6 veces).

Gestionar endpoints mediante API

Puede gestionar los endpoints de webhook sin acceder al panel. Límite de 5 endpoints por cuenta.

Verificación de firma HMAC

El servidor firma el payload como HMAC-SHA256(secret, raw_body) y lo envía en la cabecera X-Signature-256 con formato sha256=hex. Verifique en tiempo constante; de lo contrario, la integración es vulnerable a ataques de temporización.

// 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": "Construcción en Praga",
    "matchId": "cm…",
    "tender": { "id": "12345", "title": "…", "estimatedValue": 12500000 }
  }
}

Resumen por correo electrónico

Con emailDigest: true recibirá un correo electrónico diario con un resumen de las nuevas licitaciones. El resumen se envía por la mañana (5:00 UTC) a la dirección de correo electrónico de su cuenta. Puede desactivarlo editando el filtro.

Límites

Al superar el límite mensual, la API devuelve 429 con una cabecera Retry-After. El límite se restablece el día 1 de cada mes.