BASE Contract Opportunity Qualifier

Qualify official procurement notices against explicit customer capability rules.

What you get

BASE Contract Opportunity Qualifier turns Official BASE bulk JSON, Notice and procedure identities, Buyer, CPV, value and deadline into a bounded qualified procurement opportunity batch. The useful product is not a country-labelled scrape. It is an evidence-to-action unit that can be scheduled, called from an API, or placed inside a monitored operations chain.

A successful row gives you Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip. Its stable identity is based on nAnuncio + IdIncm + canonical revision fingerprint. Customer enrichment is limited to customer keywords, CPV prefixes, buyer NIFs, price and deadline rules. That separation matters: the source supplies observed facts; the buyer supplies criteria; the Actor supplies a reproducible rule application.

Product contract

• Country/source context: Portugal; official-public-domain-bulk.
• Buyer: Portuguese public-sector sales and bid operations teams.
• Primary decision noun: qualified procurement opportunity batch.
• Billable event: qualified-opportunity-batch.
• Price per verified event: $0.05.
• Stable identity: nAnuncio + IdIncm + canonical revision fingerprint.
• Accepted private run: pvMmTUcsbqcV3RxTO on build ynzQwbcnX4CQAbAOz; Dataset rows 1; measured platform usage $0.000520.
• Boundary: Verify the current notice and procurement documents before allocating bid resources.

The evidence chain

1. Validate the fixed official/public source route and response semantics.
2. Extract the named business identifiers and domain facts rather than arbitrary links or array positions.
3. Normalize buyer inputs: Keywords and CPV prefixes, Buyer NIF and value rules, Deadline and batch limits.
4. Apply Validate official IDs, Apply deterministic fit rules, Separate partial and stale notices.
5. Deliver Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip with source receipt and disclaimer.
6. Link the Dataset delivery to the named PPE event and reconcile the run in OUTPUT.

The Actor does not convert an HTTP 200 response into a billable row by default. Source-specific type, marker, identity, row-count, unit, chronology, and completeness checks run before a decision can be delivered.

Who uses it

The primary users are Portuguese public-sector sales and bid operations teams. They usually have a concrete operational question: which item needs review, where an observed benchmark differs from policy, whether an official change deserves routing, or how to prioritize a bounded set without losing the supporting evidence.

Good fit

Use this Actor when the question can be expressed using Keywords and CPV prefixes, Buyer NIF and value rules, Deadline and batch limits and the intended downstream states align with Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip. A good workflow can name its human owner, evidence-retention rule, acceptable source period, and response to monitor/review/action outcomes.

Not a good fit

Do not use it as a general-purpose crawler, unrestricted lead database, professional opinion, safety guarantee, credit or eligibility decision, valuation, or proof of customer intent. Do not expand the fixed source boundary with arbitrary URLs, authenticated pages, personal accounts, or silent residential-proxy fallback.

How to run

The workflow below belongs to execution: it maps the validated evidence chain into a run, reconciliation, and downstream automation.

Apify Console

1. Open the Actor Input tab.
2. Start from the bounded public example.
3. Replace the durable requestId or monitorId only when you are creating a genuinely new operation. Keep it unchanged for safe retries.
4. Review source-specific criteria, thresholds, and maximum total charge.
5. Run the Actor.
6. Read both Dataset and KVS OUTPUT. Dataset contains item evidence; OUTPUT contains delivery, payment, withholding, and replay truth.

Exact accepted private-canary input

The following input was read back from Apify KVS INPUT for accepted run pvMmTUcsbqcV3RxTO. Its canonical SHA-256 is 95d24f3da7ca9758dc5db7ae9e1f21872ddc6e784c27a351e5c8b78ef09e9296. IDs are synthetic campaign identities, not secrets.

{
  "requestId": "c20_base_contract_opportunity_qualifier_5604192b8749",
  "year": 2026,
  "asOfDate": "2026-08-01",
  "keywords": [
    "software",
    "serviços digitais"
  ],
  "excludedKeywords": [],
  "cpvPrefixes": [
    "72"
  ],
  "buyerNifs": [],
  "minPriceEur": 10000,
  "maxPriceEur": 5000000,
  "minScore": 50,
  "maxResults": 10,
  "maxTotalChargeUsd": 1
}

API start

curl -X POST \
  "https://api.apify.com/v2/acts/HYhRtMyd7ee3VnWcS/runs?token=$APIFY_TOKEN&waitForFinish=60" \
  -H 'content-type: application/json' \
  --data @input.json

A successful POST only proves that a run was created. Always follow the returned run ID, wait for a terminal state, then read Dataset and OUTPUT. Do not resend an ambiguous POST with a new identity.

Scheduling

Schedule according to the upstream publication cadence, not an arbitrary high-frequency polling loop. Retain the same monitor identity for change products. For one-shot decision products, use a new request identity only for a new buyer decision, criteria set, or source observation that should be independently billed.

Pricing

This Actor uses Pay Per Event. The named result event is qualified-opportunity-batch, priced at $0.05 per verified qualified procurement opportunity batch. Apify also applies its standard Actor start event according to the published pricing record and memory rules.

What is paid

A result event is charged only when the corresponding verified Dataset row or batch is delivered through linked PPE delivery. The runtime checks the live pricing contract before work, compares both the Apify platform cap and customer input cap, and refuses a result it cannot afford.

What is free at result level

• error
• partial
• duplicate
• withheld

Baselines for stateful monitors are free. A duplicate committed request is free. A pending/uncertain claim is withheld rather than re-delivered. Source validation failures, zero qualifying decisions, and budget stops do not masquerade as paid successes.

Accepted economics evidence

Accepted run pvMmTUcsbqcV3RxTO reports usage $0.000519622 and event counts:

{
  "apify-actor-start": 1,
  "qualified-opportunity-batch": 1
}

This is evidence for that bounded canary, not a promise of future cost, speed, volume, margin, or savings. Source size, platform pricing, memory, and result count can change. Use maxTotalChargeUsd and monitor your own runs.

Input contract

The Input schema rejects unknown fields. Every required field, enum, pattern, minimum, maximum, array bound, and description is part of the public contract. Do not rely on undocumented coercion.

Field	Type	Required	Default	Bounds	Meaning
requestId	string	yes	none	pattern ^[A-Za-z0-9_-]{8,64}$	Stable idempotency key without personal data.
year	integer	yes	none	min 2012; max 2100	Annual anunciosYYYY.json resource to discover in the current official catalogue.
asOfDate	string	yes	none	pattern ^\d{4}-\d{2}-\d{2}$	Explicit YYYY-MM-DD date used for deterministic deadline checks.
keywords	array	yes	none	minItems 1; maxItems 20	At least one keyword must match notice, buyer, CPV, contract type or lot text.
excludedKeywords	array	no	[]	maxItems 20	Any match removes the notice.
cpvPrefixes	array	no	[]	maxItems 20	Optional numeric prefixes from 2 to 8 digits; when supplied at least one must match.
buyerNifs	array	no	[]	maxItems 50	Optional exact nine-digit public entity NIF allowlist.
minPriceEur	number	no	0	min 0	Notices with a known price below this are excluded.
maxPriceEur	number	no	1000000000000	min 0	Notices with a known price above this are excluded.
minScore	number	no	40	min 0; max 100	Transparent score from 0 to 100.
maxResults	integer	no	10	min 1; max 20	Maximum rows embedded in one paid batch.
maxTotalChargeUsd	number	yes	1	min 0.005; max 100	Maximum total run charge in addition to the platform cap.

Input design rules

• IDs are idempotency controls, not labels to randomize on every retry.
• Thresholds must express an operational policy that a reviewer understands.
• Customer facts remain customer facts; the Actor does not pretend the source verified them.
• Lists are bounded to protect source terms, runtime, Dataset size, and customer spend.
• maxTotalChargeUsd is a customer-side ceiling; the platform run option is authoritative when stricter.
• Secrets do not belong in source URLs, criteria text, Dataset fields, or README examples.

Validation before automation

Run one bounded Console example, inspect every Dataset field and OUTPUT, then create the schedule or webhook. If the decision would cause a consequential action, require human approval after the Actor and before the action.

Real happy, partial, and failure output

Accepted Dataset example

The following is an exact Dataset example captured from accepted run pvMmTUcsbqcV3RxTO; Dataset SHA-256 is 3bf8733cc30968026eb3199dcfcf38e3f5e7706b382f04f31a637b10121a21fe.

[
  {
    "schemaVersion": "1.0",
    "product": "base-contract-opportunity-qualifier",
    "country": "PT",
    "decision": "qualified procurement opportunity batch",
    "stableId": "BASE-BATCH:2026:96eae46dbdaedebb210b",
    "year": 2026,
    "asOfDate": "2026-08-01",
    "matchedCount": 61,
    "returnedCount": 10,
    "opportunities": [
      {
        "id": "18802/2026|419968075|eec31ed0d2e727ad",
        "nAnuncio": "18802/2026",
        "idIncm": "419968075",
        "revisionSha256": "eec31ed0d2e727ad925826411da375fb44b8bca17d61dea795a271ba024c5c63",
        "publishedDate": "2026-07-22",
        "buyerNif": "505993082",
        "buyerName": "Vimágua - Empresa de Água e Saneamento de Guimarães e Vizela, EIM, SA",
        "description": "Aquisição de serviços de evolução tecnológica da plataforma de gestão documental, implementação de soluções de interoperabilidade e modernização dos serviços digitais da Vimágua, por Lotes",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 64230,
        "cpvs": [
          "72267100-0 - Manutenção de software para as tecnologias da infomação"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-06",
        "lots": [
          "Evolução tecnológica da plataforma de gestão documental FutureDoc e GSP",
          "Modernização dos serviços digitais e interoperabilidade"
        ],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/140/419968075.pdf",
        "stableNoticeId": "BASE:1afa6a96851d55cc2fff",
        "score": 90,
        "matchReasons": {
          "keywordMatches": [
            "servicos digitais",
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "17034/2026|419965924|2835c2c78efba86e",
        "nAnuncio": "17034/2026",
        "idIncm": "419965924",
        "revisionSha256": "2835c2c78efba86ed809c6dac33409a4e66353c1bb2b440224c37d11d81477ad",
        "publishedDate": "2026-07-03",
        "buyerNif": "505387131",
        "buyerName": "Município da Maia",
        "description": "Fornecimento, instalação, configuração e desenvolvimento de uma Plataforma de Gestão Urbana – ISI Maia- Inteligente, Sustentável e Inclusiva",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 331557.01,
        "cpvs": [
          "72200000-7 - Serviços de consultoria e de programação de software"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-03",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/127/419965924.pdf",
        "stableNoticeId": "BASE:82d72c2da53b29b94b5b",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "18639/2026|419967532|ed6ce1aa2458a44a",
        "nAnuncio": "18639/2026",
        "idIncm": "419967532",
        "revisionSha256": "ed6ce1aa2458a44a33b756206ed018469626bb493fd081b8cdbdb3ba3904d206",
        "publishedDate": "2026-07-21",
        "buyerNif": "510361242",
        "buyerName": "Instituto de Gestão Financeira e Equipamentos da Justiça, IP",
        "description": "26AS00007967 - Subscrição de solução de segurança de endpoint com Network Traffic Analysis (NTA)",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 215000,
        "cpvs": [
          "72260000-5 - Serviços relacionados com software"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-03",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/139/419967532.pdf",
        "stableNoticeId": "BASE:b683a9bd0eea7e575c69",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "19160/2026|419968478|3aec996a03c49a5b",
        "nAnuncio": "19160/2026",
        "idIncm": "419968478",
        "revisionSha256": "3aec996a03c49a5bd69e002cd4748f2a155aeb26a3c2bed94d6794ae84f2eb15",
        "publishedDate": "2026-07-27",
        "buyerNif": "500745471",
        "buyerName": "Santa Casa da Misericórdia de Lisboa",
        "description": "Prestação de serviços de manutenção ao software de Gestão de Ensino Académico Superior (ESSA)",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 52457,
        "cpvs": [
          "72000000-5 - Serviços de TI: consultoria, desenvolvimento de software, Internet e apoio"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-03",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/143/419968478.pdf",
        "stableNoticeId": "BASE:468a3df2ee055117552b",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "19316/2026|419968730|0af2dc0a60fcdf20",
        "nAnuncio": "19316/2026",
        "idIncm": "419968730",
        "revisionSha256": "0af2dc0a60fcdf203032c6371ae3c5be5b76820f02a4ebb19c6ac099fe117677",
        "publishedDate": "2026-07-28",
        "buyerNif": "600012662",
        "buyerName": "MDN - Direção-Geral da Autoridade Marítima",
        "description": "Serviço Implementação Baseline de Sistema de Informação",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 14666.66,
        "cpvs": [
          "72263000-6 - Serviços de implementação de software"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-03",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/144/419968730.pdf",
        "stableNoticeId": "BASE:0d061383823187f6cdc7",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "18927/2026|419968116|a1921924e2761785",
        "nAnuncio": "18927/2026",
        "idIncm": "419968116",
        "revisionSha256": "a1921924e2761785056252634a1ba17a2cb353386bbb17fdb3d0f8a0841f6fc4",
        "publishedDate": "2026-07-23",
        "buyerNif": "505948605",
        "buyerName": "Município de Guimarães",
        "description": "Aquisição de serviços – Licenciamento de software “Sistema Imunitário para Cybersegurança",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 133200,
        "cpvs": [
          "72910000-2 - Serviços informáticos de segurança"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-04",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/141/419968116.pdf",
        "stableNoticeId": "BASE:5af1a48eec36027f888a",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "19245/2026|419968598|bd44eb24283c5f9e",
        "nAnuncio": "19245/2026",
        "idIncm": "419968598",
        "revisionSha256": "bd44eb24283c5f9e7f032c25f495f02d1450c4fe913db699517c9b1feabba88d",
        "publishedDate": "2026-07-28",
        "buyerNif": "514280956",
        "buyerName": "Empresa Municipal de Ambiente do Porto, EM, SA",
        "description": "Aquisição de serviços de subscrição de licenças de software Microsoft",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 40000,
        "cpvs": [
          "72268000-1 - Serviços de fornecimento de software"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-04",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/144/419968598.pdf",
        "stableNoticeId": "BASE:2016d0d85fd6b8f2d6aa",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "17582/2026|419966520|2f70fe650387209e",
        "nAnuncio": "17582/2026",
        "idIncm": "419966520",
        "revisionSha256": "2f70fe650387209ea815aa877e8a81fff726b245c085083fada5e923a84d69c6",
        "publishedDate": "2026-07-09",
        "buyerNif": "510928374",
        "buyerName": "Agência para o Desenvolvimento e Coesão, IP",
        "description": "Aquisição e renovação de licenciamento da solução da infraestrutura de segurança da informação da Agência, I.P.",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 410725.96,
        "cpvs": [
          "72000000-5 - Serviços de TI: consultoria, desenvolvimento de software, Internet e apoio"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-06",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/131/419966520.pdf",
        "stableNoticeId": "BASE:a218a1643c4f4cc5ce0e",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "18785/2026|419968117|7848e5f2fd690e23",
        "nAnuncio": "18785/2026",
        "idIncm": "419968117",
        "revisionSha256": "7848e5f2fd690e23eff99ce07f90615d0d5e2c70749cc27b162bdabb2b3232cc",
        "publishedDate": "2026-07-22",
        "buyerNif": "501442600",
        "buyerName": "Centro de Emprego e Formação Profissional de Braga",
        "description": "Aquisição de serviços especializados para Sistemas de Informação de Base Oracle, pelo período de 12 meses",
        "noticeType": "Anúncio de procedimento",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 86560,
        "cpvs": [
          "72000000-5 - Serviços de TI: consultoria, desenvolvimento de software, Internet e apoio"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-06",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/140/419968117.pdf",
        "stableNoticeId": "BASE:8e5ec2599c2bece56634",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      },
      {
        "id": "17465/2026|419966433|d9ec16d3b04431a4",
        "nAnuncio": "17465/2026",
        "idIncm": "419966433",
        "revisionSha256": "d9ec16d3b04431a48e17ee02f2800b5d9bafa779530ad48babfcab901617271a",
        "publishedDate": "2026-07-08",
        "buyerNif": "600084973",
        "buyerName": "Direção-Geral de Recursos Naturais, Segurança e Serviços Marítimos",
        "description": "Aquisição serviços manutenção pontual dos sistemas DW/BMAR/SIFICAP ",
        "noticeType": "Anúncio de Alteração",
        "contractTypes": [
          "Aquisição de serviços"
        ],
        "priceBaseEur": 73500,
        "cpvs": [
          "72267100-0 - Manutenção de software para as tecnologias da infomação"
        ],
        "procedureModel": "Concurso público",
        "environmentalCriterion": "Não",
        "deadline": "2026-08-07",
        "lots": [],
        "sourceUrl": "https://files.diariodarepublica.pt/cp_hora/2026/07/130/419966433.pdf",
        "stableNoticeId": "BASE:de89fc71bad631e27c44",
        "score": 70,
        "matchReasons": {
          "keywordMatches": [
            "software"
          ],
          "cpvMatches": [
            "72"
          ],
          "buyerMatched": false,
          "priceKnown": true,
          "deadlineOpen": true
        }
      }
    ],
    "criteriaSha256": "9c5ca152b729e23fe42f668fb07ca03d7ec509372fc95bd51cea81406f8ab9ad",
    "source": {
      "catalog": {
        "url": "https://dados.gov.pt/api/1/datasets/66d72fbc58cd7a63dae28712/",
        "bytes": 46640,
        "sha256": "333586f44e378828145d54b5bd5abaf0585ff8b941a585f6796325224d9e2657",
        "retrievedAt": "2026-08-14T10:00:22.517Z"
      },
      "resource": {
        "url": "https://dados.gov.pt/s/resources/contratos-publicos-portal-base-impic-anuncios-de-2012-a-2026/20260809-090453-09c1b9a5/anuncios2026.json",
        "bytes": 18623443,
        "sha256": "2824c9b101342d47fb3f695354acdac03101fd1b09bfdb5d3f7585cf692f2404",
        "retrievedAt": "2026-08-14T10:00:26.483Z",
        "resourceId": "1002987e-8985-492f-9215-e732fffdbc83",
        "lastModified": "2026-08-09T09:04:53.411000+00:00",
        "checksum": {
          "type": "sha1",
          "value": "55f06c6bc3007fd9a5d949e5ae59b59ccf823f2e"
        }
      }
    },
    "attribution": "Source: IMPIC Portal BASE via dados.gov.pt — Outra (Domínio Público)",
    "disclaimer": "Public-procurement lead qualification from a versioned bulk snapshot; verify the official notice and deadline before bidding.",
    "baseline": false,
    "billable": true
  }
]

Accepted terminal OUTPUT

This exact KVS OUTPUT was captured from the same accepted run; OUTPUT SHA-256 is 4b06c651c9e433611c340817baa105fdfdac5c2854a2a14805a40b6cd449b6bb.

{
  "schemaVersion": "1.0",
  "status": "ok",
  "product": "base-contract-opportunity-qualifier",
  "delivered": 1,
  "paid": 1,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "finishedAt": "2026-08-14T10:00:27.698Z"
}

Partial contract shape

The runtime uses a free partial/withheld state when source completeness or delivery certainty is insufficient. This is a contract illustration, not claimed as an additional accepted run:

{
  "schemaVersion": "1.0",
  "status": "partial",
  "product": "base-contract-opportunity-qualifier",
  "delivered": 0,
  "paid": 0,
  "withheld": 1,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "source-specific validation stopped before verified delivery"
}

Failure contract shape

A bounded source or input failure is free at result level and never claims replay safety unless the runtime can prove it. This is a contract illustration:

{
  "schemaVersion": "1.0",
  "status": "failed",
  "product": "base-contract-opportunity-qualifier",
  "delivered": 0,
  "paid": 0,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "bounded source or input contract failure"
}

Reading terminal truth

• delivered must reconcile to Dataset rows.
• paid must reconcile to billable rows and the named event count.
• withheld signals that a row or operation was intentionally not repeated or delivered.
• replaySafe is true only for states the runtime can safely replay.
• publicationAuthorized is a release boundary, not a customer decision field.

Field dictionary

Dataset

Dataset field	Type	Operational meaning
schemaVersion	string	Verified schemaVersion field in the accepted qualified procurement opportunity batch row.
product	string	Verified product field in the accepted qualified procurement opportunity batch row.
country	string	Verified country field in the accepted qualified procurement opportunity batch row.
stableId	string	Verified stableId field in the accepted qualified procurement opportunity batch row.
decision	string	Verified decision field in the accepted qualified procurement opportunity batch row.
year	integer	Verified year field in the accepted qualified procurement opportunity batch row.
asOfDate	string	Verified asOfDate field in the accepted qualified procurement opportunity batch row.
matchedCount	integer	Verified matchedCount field in the accepted qualified procurement opportunity batch row.
returnedCount	integer	Verified returnedCount field in the accepted qualified procurement opportunity batch row.
opportunities	array	Verified opportunities field in the accepted qualified procurement opportunity batch row.
source	object	Verified source field in the accepted qualified procurement opportunity batch row.
attribution	string	Verified attribution field in the accepted qualified procurement opportunity batch row.
disclaimer	string	Verified disclaimer field in the accepted qualified procurement opportunity batch row.
baseline	boolean	Verified baseline field in the accepted qualified procurement opportunity batch row.
billable	boolean	Verified billable field in the accepted qualified procurement opportunity batch row.

Cross-product evidence fields

• stableId — domain identity derived from nAnuncio + IdIncm + canonical revision fingerprint; never a source array position.
• source — route, official IDs, period, byte/hash receipt, and retrieval time needed to audit the observation.
• action — the explicit routing result after applying buyer criteria to validated source facts.
• criteriaSha256 — integrity fingerprint for normalized criteria; it is not a score.
• baseline — true only when a stateful monitor stores its first comparable snapshot for free.
• billable — true only when the row is eligible for the named linked delivery event.
• attribution/disclaimer — reuse credit and decision boundary that downstream systems should retain.

KVS OUTPUT

OUTPUT is the authoritative run-level receipt. It should be stored beside a workflow execution ID. It does not replace Dataset evidence, and Dataset evidence does not replace OUTPUT billing/replay truth. A robust integration rejects mismatched counts rather than guessing.

Evidence and boundaries

Evidence preserved

The adapter retains the official identity and observed facts required for qualified procurement opportunity batch. It also retains source URL/route, source period or publication identity, retrieval timestamp, response or release hash, normalized criteria fingerprint, and the exact action reason exposed by the domain adapter.

Semantic source validation

The source contract is official-public-domain-bulk on route direct. Validation is domain-specific: expected content type, fixed host/path or official catalog relationship, required identifiers, bounded bytes, structural fields, chronology, duplicate identity, and semantic error bodies are checked before delivery. An upstream login page, generic app shell, consent page, empty report, or malformed file must fail closed.

Security boundary

Network destinations are fixed to approved official/public hosts. Redirects are either disabled or independently revalidated. DNS and address checks reject local/private targets. Responses are streamed under declared byte limits. Buyer input cannot turn the Actor into SSRF, an open proxy, an authenticated crawler, or a credential relay.

Interpretation boundary

Verify the current notice and procurement documents before allocating bid resources. The Actor reports observed evidence plus a deterministic rule application. It does not prove causality, future behavior, legal status beyond the cited publication, quality, solvency, safety, intent, or permission to contact.

Privacy boundary

Submit only operationally necessary criteria. Do not provide passwords, access tokens, private correspondence, sensitive personal data, or arbitrary URLs. If the official source exposes public entity facts, retain them only for the documented decision and according to your own legal basis and retention policy.

Decision routing

Route states

• Monitor — evidence is valid but does not cross a review threshold. Store the receipt and wait for the next comparable observation.
• Review — evidence crosses a bounded review rule or needs professional confirmation. Create a queue item with source and factors.
• Action-oriented state — the explicit rule crosses the action threshold. Require the owner and safeguards appropriate to the domain.
• Partial — source completeness is insufficient. Do not interpret missing rows as negative evidence.
• Withheld/uncertain — the runtime will not repeat a potentially delivered item. Reconcile by run ID.
• Failed — no decision claim was made. Fix the input/source boundary or wait for the official source; do not randomize the request ID.

Routing record

Every downstream task should carry stableId, action, factors, source identity, reference period, criteria fingerprint, run ID, Dataset ID, and a link to OUTPUT. This makes it possible to answer “what did we know, which rule ran, and what happened to delivery?” without reconstructing the workflow from logs.

Human review

Human review is not a vague disclaimer. Define the reviewer role, response time, evidence they must inspect, allowed dispositions, and whether a changed source observation is required before action. Keep the reviewer decision separate from the Actor row.

Commercial playbooks

1. Qualification desk

Use Keywords and CPV prefixes, Buyer NIF and value rules, Deadline and batch limits to decide which records deserve analyst time. Preserve the cited source fields beside the action so a reviewer can reproduce why the row was routed.

2. Scheduled monitor

Run on the cadence of the official source, keep the same durable request or monitor identity where the product supports state, and send only verified changes or decision rows downstream.

3. CRM enrichment

Map Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip into evidence fields instead of overwriting customer master data. Keep the source URL, observation period, stable ID, and disclaimer visible.

4. Operational review queue

Treat “review” as a routing state. Assign an owner, retain the evidence receipt, confirm the current source state, and record the human disposition outside the Actor.

5. Portfolio comparison

Run the same bounded criteria over comparable customer items. Compare factors and source periods, not a bare score detached from its evidence and limitations.

6. Audit export

Export Dataset rows and the KVS OUTPUT receipt together. The Dataset explains each delivered item; OUTPUT explains paid, free, withheld, partial, and replay state for the run.

Integration recipes

JavaScript client

const actorId = 'HYhRtMyd7ee3VnWcS';
const input = {
  "requestId": "c20_base_contract_opportunity_qualifier_5604192b8749",
  "year": 2026,
  "asOfDate": "2026-08-01",
  "keywords": [
    "software",
    "serviços digitais"
  ],
  "excludedKeywords": [],
  "cpvPrefixes": [
    "72"
  ],
  "buyerNifs": [],
  "minPriceEur": 10000,
  "maxPriceEur": 5000000,
  "minScore": 50,
  "maxResults": 10,
  "maxTotalChargeUsd": 1
};
const start = await fetch(`https://api.apify.com/v2/acts/${actorId}/runs?waitForFinish=60&token=${process.env.APIFY_TOKEN}`, {
  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input),
});
const run = (await start.json()).data;
if (!['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'].includes(run.status)) throw new Error('poll run to terminal');
const [rowsResponse, outputResponse] = await Promise.all([
  fetch(`https://api.apify.com/v2/datasets/${run.defaultDatasetId}/items?clean=true&token=${process.env.APIFY_TOKEN}`),
  fetch(`https://api.apify.com/v2/key-value-stores/${run.defaultKeyValueStoreId}/records/OUTPUT?token=${process.env.APIFY_TOKEN}`),
]);
const rows = await rowsResponse.json();
const terminal = await outputResponse.json();
if (terminal.delivered !== rows.length) throw new Error('delivery reconciliation failed');

Python client

import os, requests
actor_id = 'HYhRtMyd7ee3VnWcS'
input_payload = {
  "requestId": "c20_base_contract_opportunity_qualifier_5604192b8749",
  "year": 2026,
  "asOfDate": "2026-08-01",
  "keywords": [
    "software",
    "serviços digitais"
  ],
  "excludedKeywords": [],
  "cpvPrefixes": [
    "72"
  ],
  "buyerNifs": [],
  "minPriceEur": 10000,
  "maxPriceEur": 5000000,
  "minScore": 50,
  "maxResults": 10,
  "maxTotalChargeUsd": 1
}
run = requests.post(
    f'https://api.apify.com/v2/acts/{actor_id}/runs',
    params={'token': os.environ['APIFY_TOKEN'], 'waitForFinish': 60},
    json=input_payload, timeout=75,
).json()['data']
rows = requests.get(
    f"https://api.apify.com/v2/datasets/{run['defaultDatasetId']}/items",
    params={'token': os.environ['APIFY_TOKEN'], 'clean': 'true'}, timeout=30,
).json()
output = requests.get(
    f"https://api.apify.com/v2/key-value-stores/{run['defaultKeyValueStoreId']}/records/OUTPUT",
    params={'token': os.environ['APIFY_TOKEN']}, timeout=30,
).json()
assert output['delivered'] == len(rows)

n8n

1. Schedule Trigger or Webhook receives the bounded buyer criteria.
2. HTTP Request starts the Actor with an Apify credential stored in n8n credentials, never in the input URL committed to source control.
3. Wait/Poll follows the returned run ID to terminal state.
4. Two HTTP Request nodes read Dataset and OUTPUT.
5. Code checks delivered/paid counts, allowed status, stableId, source period, and action.
6. Switch routes monitor, review, action, partial, withheld, and failed states separately.
7. Destination nodes write to Sheets/CRM/ticketing while preserving evidence and disclaimer.

Google Sheets

Use one sheet for decision rows keyed by stableId, and a second run ledger keyed by runId. Recommended decision columns are source period, action, factors, source URL, criteria hash, observation time, and reviewer disposition. Recommended run columns are Dataset ID, delivered, paid, withheld, replaySafe, usage, and OUTPUT link.

CRM

Create an evidence/enrichment activity rather than replacing the CRM’s authoritative legal name, valuation, risk status, or account owner. Store the source identity and observation date. Route review/action states into a task with a named owner; leave monitor states as timeline evidence unless policy says otherwise.

Webhooks

Use an Apify run-succeeded webhook only as a wake-up signal. Fetch the terminal run, Dataset, and OUTPUT using their IDs, then reconcile. Do not trust arbitrary webhook body fields as the complete decision record, and make the receiver idempotent by run ID plus stableId.

Operating guide

Before launch

• Confirm the official source route and reuse boundary remain current.
• Validate public Input schema descriptions and bounded defaults in the rendered Console.
• Run the small example and retain INPUT, Dataset, OUTPUT, build ID, pricing events, and usage.
• Confirm the source observation period is appropriate for the buyer decision.
• Define downstream owners and allowed dispositions.
• Set a customer cap and monitor actual spend.

Daily or scheduled operation

Check terminal status, Dataset count, OUTPUT reconciliation, source period, source hash change, partial flags, and review backlog. When the source has not published a new comparable period, do not fabricate change by rotating an identity. When a source revision changes a prior period, keep both the revision evidence and customer decision history.

Incident runbook

1. Stop automatic consequential actions while preserving monitor collection.
2. Identify the exact run, build, INPUT hash, Dataset hash, OUTPUT hash, and source receipt.
3. Determine whether the fault is input validation, source availability, semantic source drift, budget, linked delivery, or downstream mapping.
4. For an ambiguous POST or pending delivery, reconcile the existing run; never start a replacement with a new identity merely to obtain a clean status.
5. For source schema drift, update source-specific fixtures and validators, build a new immutable candidate, and rerun acceptance.
6. Restore automation only after a bounded canary and replay test prove the corrected path.

Change management

Treat input/output schemas, identity basis, decision rules, source URLs, legal boundary, and pricing noun as product contracts. Version changes deliberately. A README-only edit must not silently redefine runtime behavior, and a runtime change must update examples and field dictionary before release.

Quality checklist

For this product the release gate verifies: Keywords and CPV prefixes, Buyer NIF and value rules, Deadline and batch limits; Official BASE bulk JSON, Notice and procedure identities, Buyer, CPV, value and deadline; Validate official IDs, Apply deterministic fit rules, Separate partial and stale notices; and Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip. It also checks private candidate provenance, exact build source, PPE configuration, bounded accepted run, free error/duplicate behavior, replay and concurrency safety, two immutable diagrams, README length/sections, rendered Store/Input pages, and all-20 wave balance.

FAQ

Is this a generic country scraper?

No. It is the BASE Contract Opportunity Qualifier, designed around qualified procurement opportunity batch and the named official/public source contract. Geography explains the source, not the product category.

Does it crawl accounts or private pages?

No. The implementation is pinned to the source routes documented below. It does not log in, bypass an account, collect messages, or broaden itself to arbitrary customer URLs.

Can a customer supply an arbitrary URL?

No. Source hosts and paths are fixed or derived only through bounded official catalog routes. Buyer inputs select criteria and customer facts; they do not turn the Actor into an open proxy.

What is the primary billable unit?

The single pricing noun is qualified procurement opportunity batch, charged through the named event qualified-opportunity-batch only when a verified billable Dataset item is linked to delivery.

Are errors charged as result events?

No. The contract identifies error, partial, duplicate, withheld as free result states. Apify platform start charges are separate and visible in the run pricing record.

What makes an ID stable?

The identity basis is: nAnuncio + IdIncm + canonical revision fingerprint. Mutable ranking, source position, or array offset is not treated as the business identity.

Is the score a random hash?

No. The production adapter parses named source fields and applies the explicit rules described in the output. Hashes are used for integrity, criteria fingerprints, and idempotency—not as business scores.

Can I treat an action as a professional conclusion?

No. Verify the current notice and procurement documents before allocating bid resources.

How fresh is the data?

Freshness follows the official source and the observation/reference period in the Dataset row. The Actor does not invent a real-time claim when the upstream source is monthly, daily, or a published report.

Why preserve a source hash?

It proves which response or release was used and helps distinguish a changed upstream publication from a changed customer criterion. It does not replace the official source URL.

What happens on an upstream HTML challenge or error page?

Semantic validators reject the body before decision delivery. A 2xx status alone is not enough; required columns, identifiers, counts, content type, and source-specific markers must pass.

Does this require a local proxy?

The accepted product route is the route in the contract: direct. A proxy is never a silent fallback and cannot change a legal or reuse boundary.

How do retries work?

Reuse the same durable request/monitor identity. A committed request returns a free duplicate state; an uncertain pending delivery is withheld rather than repeated blindly. Inspect OUTPUT before authorizing any new request ID.

Can two concurrent runs double-deliver?

The runtime claims a tenant-scoped durable operation before linked delivery. A competing claim is returned as duplicate or withheld. The release gate separately stress-tests this behavior before publication.

Where is the authoritative run summary?

KVS record OUTPUT. Dataset rows carry item evidence; OUTPUT carries run-wide counts and replay safety. Store both when the workflow needs auditability.

Can I remove the disclaimer downstream?

Do not. Preserve attribution, the product disclaimer, source URL, reference period, and the human-review boundary in any CRM, report, or webhook payload.

Does the Actor predict the future?

No. It converts observed official/public evidence and customer criteria into an operational benchmark, monitor, or routing decision. It is not marketed as a forecast unless the product contract explicitly says so—which this one does not.

Does it contain personal data?

The product scope is limited to the documented public/aggregate fields and buyer-supplied operational criteria. Do not submit secrets or unnecessary personal data. Review Dataset examples before connecting another system.

How should I choose thresholds?

Start with the bounded public example, compare decisions against your own review policy, and change one rule at a time. The Actor exposes Qualified opportunity batch, Matched rules and evidence, Bid research, review or skip so threshold effects remain visible.

Why is publicationAuthorized false in canary OUTPUT?

Private acceptance runs deliberately hard-code the publication boundary. Public release is a separate all-20 transaction after source, billing, replay, visual, Store, and anonymous-page gates pass.

What sources are contacted?

https://dados.gov.pt/api/1/datasets/66d72fbc58cd7a63dae28712/

Can n8n or Make call it?

Yes. Start a run through the Apify API, wait for terminal status, read Dataset items and OUTPUT, then branch on explicit action/status fields. Never branch only on HTTP 201 from the run-start request.

Can I write results to Google Sheets?

Yes. Use stableId as the row key, source reference period as the observation column, and action as a review-routing column. Keep OUTPUT in a separate run ledger sheet.

Can I push into a CRM automatically?

Yes, but write evidence into a dedicated enrichment object or timeline entry. Do not silently overwrite authoritative customer fields, and require human review for consequential actions.

What should support requests include?

Provide the Actor name, run ID, build number, OUTPUT, source receipt/hash, and a redacted input. Never paste the Apify token or another secret.

How do I audit a threshold change?

Keep the old and new normalized criteria, their fingerprints, the same comparable source period, and both decision rows. Explain which of Keywords and CPV prefixes, Buyer NIF and value rules, Deadline and batch limits changed and why the new policy is authorized.

Can I compare different source periods?

Yes, when the domain adapter exposes comparable periods and units. Keep revision and seasonality caveats visible. Never compare ranks or scores across changed definitions without documenting the break.

What if the official source revises history?

Retain both source hashes and observation timestamps. A revision is new evidence, not proof that the earlier Actor run was defective. Re-run only under an authorized identity/revision policy.

What if the source removes a record?

A stateful product reports removal only when the source contract and completeness checks can distinguish a real removal from a partial response. Otherwise the run is partial or withheld.

Should I schedule it every minute?

Usually no. Match the upstream publication cadence and buyer response time. Excess polling adds cost and load without creating fresher official evidence.

Sources and rights

Exact source routes

• https://dados.gov.pt/api/1/datasets/66d72fbc58cd7a63dae28712/

The implementation uses only the route family defined in contract.json: kind official-public-domain-bulk, host dados.gov.pt, route direct. Source metadata, licence/reuse labels, attribution, and product-specific exclusions must be rechecked at production acceptance because public terms and endpoints can change.

Reuse and attribution

This is an unofficial Actor, not affiliated with or endorsed by any named source publisher. Preserve emitted attribution and official disclaimers. Do not broaden reuse rights to excluded content, accounts, listings, messages, or customer data.

Termos da fonte em português

Search/source terms: dados oficiais, prova da fonte, sinal de decisão, monitorizar, rever, agir.

Os registos da fonte são preservados como prova; o resultado não constitui parecer jurídico, financeiro ou garantia de resultado.

The local-language labels help operators find and verify the official source. The binding product contract, input schema, field dictionary, pricing noun, and safety boundary remain the English Store documentation above.

Product-specific boundary

• Source evidence: Official BASE bulk JSON; Notice and procedure identities; Buyer, CPV, value and deadline.
• Transformation: Validate official IDs; Apply deterministic fit rules; Separate partial and stale notices.
• Delivered fields: Qualified opportunity batch; Matched rules and evidence; Bid research, review or skip.
• Required interpretation: Verify the current notice and procurement documents before allocating bid resources.
• Excluded expansion: arbitrary URLs, account access, messages, private datasets, silent proxy fallback, and claims not supported by cited evidence.

Support evidence

When reporting a source or decision issue, provide run ID pvMmTUcsbqcV3RxTO-style identifiers, build number, redacted INPUT, Dataset and OUTPUT hashes, source period and source receipt. Never send an Apify token, password, private correspondence, or unnecessary personal data.