cup-cig

name	cup-cig
description	Guide users monitoring Italian public procurement to extract detailed information from lists of CUP (Codice Unico di Progetto) and CIG (Codice Identificativo Gara). Use when the user wants to look up project metadata, financial status, or tender details for Italian public contracts.

CUP-CIG

Use this skill to retrieve detailed information on Italian public projects and tenders from CUP and CIG codes using open data sources.

IMPORTANT: Always write curl commands on a single line. Multi-line \ continuation breaks argument parsing in agent environments and will cause errors.

---

Decision Tree — Which Source for Which Question?

User has a CUP
  ├─ Project metadata (name, sector, entity, amounts)?
  │    └─ OpenCUP API (or web page if no API key)
  ├─ Financial monitoring / execution status?
  │    └─ OpenBDAP OData
  └─ Associated tenders (CIG)?
       └─ ANAC BDNCP bulk (authoritative CUP↔CIG join)

User has a CIG
  ├─ Full detail (participants, awards, subcontracts, financials) — any CIG type?
  │    └─ ANAC dettaglio-cig → scripts/cig-fetch.sh (requires agent-browser)
  ├─ Starts with Z (e.g. Z063947806)?
  │    └─ Below-threshold direct award → ANAC BDNCP bulk (no live API)
  └─ Alphanumeric (e.g. 8874674CA7) — basic tender list / outcomes?
       └─ SCP-MIT API

---

Environment Variables

export OPENCUP_API_CLIENT_ID='...'
export OPENCUP_API_CLIENT_SECRET='...'

To verify without printing the values:

[[ -n "${OPENCUP_API_CLIENT_ID:-}" ]] && echo "ID is set" || echo "ERROR: OPENCUP_API_CLIENT_ID not set"
[[ -n "${OPENCUP_API_CLIENT_SECRET:-}" ]] && echo "SECRET is set" || echo "ERROR: OPENCUP_API_CLIENT_SECRET not set"

---

Source 1 — OpenCUP: Project Metadata

Base URL: https://api.sogei.it/rgs/opencup/o/extServiceApi/v1/opendataes/cup/{CUP} Auth: IBM API headers (x-ibm-client-id, x-ibm-client-secret)

Look up a single CUP

curl -sS -X GET "https://api.sogei.it/rgs/opencup/o/extServiceApi/v1/opendataes/cup/J87G22000360002" -H "x-ibm-client-id: ${OPENCUP_API_CLIENT_ID}" -H "x-ibm-client-secret: ${OPENCUP_API_CLIENT_SECRET}" -H "Accept: application/json" | jq '.results[0]|{cup:.CUP, anno:.ANNO_DECISIONE, stato:.COD_STATO_PROGETTO, soggetto:.DESC_SOGGETTO, settore:.DESC_SETTORE_INTERVENTO, area:.DESC_AREA_INTERVENTO, importo:.IMPORTO_COSTO_PROGETTO, regione:.LOC_REGIONI}'

Look up a list of CUPs

Given a file cups.txt (one CUP per line):

while IFS= read -r cup; do echo "=== $cup ==="; curl -sS -X GET "https://api.sogei.it/rgs/opencup/o/extServiceApi/v1/opendataes/cup/$cup" -H "x-ibm-client-id: ${OPENCUP_API_CLIENT_ID}" -H "x-ibm-client-secret: ${OPENCUP_API_CLIENT_SECRET}" -H "Accept: application/json" | jq '.results[0]|{cup:.CUP, stato:.COD_STATO_PROGETTO, soggetto:.DESC_SOGGETTO, settore:.DESC_SETTORE_INTERVENTO, importo:.IMPORTO_COSTO_PROGETTO}'; done < cups.txt

Without API credentials (web page fallback)

The project page at https://opencup.gov.it/portale/progetto/-/cup/{CUP} is publicly accessible but returns HTML. Use a browser or a headless fetch tool for scraping.

---

Source 2 — OpenBDAP: Financial Monitoring

Base URL: https://bdap-opendata.rgs.mef.gov.it/ODataProxy/MdData('bda1676b-62ab-44b7-8f9a-ca93b8534488@rgs')/DataRows Auth: None Field name for CUP: Cccodice_cup_1267962549

Query by CUP

curl -sS "https://bdap-opendata.rgs.mef.gov.it/ODataProxy/MdData('bda1676b-62ab-44b7-8f9a-ca93b8534488@rgs')/DataRows?\$filter=Cccodice_cup_1267962549%20eq%20'H87H21003670005'&\$inlinecount=allpages&\$top=10&\$format=json" | jq '[.d.results[]|{cup:.Cccodice_cup_1267962549, descrizione:.Ccdescrizione_cu902475141, stato:.Ccdescrizione_s1176782119, ente:.Ccdescrizione_ti177583083, settore:.Ccsettore_inter1475973826, costo:.Cccosto_lavori_e582037416}]'

Query by entity fiscal code (without knowing CUPs)

curl -sS "https://bdap-opendata.rgs.mef.gov.it/ODataProxy/MdData('bda1676b-62ab-44b7-8f9a-ca93b8534488@rgs')/DataRows?\$filter=Cccodice_fiscal1934873127%20eq%20'02246660985'&\$inlinecount=allpages&\$top=10&\$format=json" | jq '[.d.results[]|{cup:.Cccodice_cup_1267962549, ente:.Ccdescrizione_ti177583083, stato:.Ccdescrizione_s1176782119}]'

Common OData filters

What	Filter
By CUP	$filter=Cccodice_cup_1267962549 eq '{CUP}'
By fiscal code	$filter=Cccodice_fiscal1934873127 eq '{CF}'
Active projects	$filter=Cccodice_stato_1426672593 eq 'A'
Closed projects	$filter=Cccodice_stato_1426672593 eq 'C'
By sector	$filter=Ccsettore_inter1475973826 eq 'STRADALI'

Combine with and/or. Always add $inlinecount=allpages for total counts.

---

Source 3 — SCP-MIT: Published Tenders (CIG above threshold)

Base URL: https://www.serviziocontrattipubblici.it/WSConsultBandi/rest/ Method: POST + Content-Type: application/x-www-form-urlencoded Note: Use -k flag to skip SSL verification (self-signed certificate). Important: page_limit and offset go as URL query params; all other filters go in the form body. stato values: 1=In corso, 2=Scaduti, 3=Tutti. Use 3 when searching by CIG to avoid missing results.

Search by CIG — tender list (Bandi)

curl -sSkX POST "https://www.serviziocontrattipubblici.it/WSConsultBandi/rest/Bandi/Lista?page_limit=10&offset=0" -H "Content-Type: application/x-www-form-urlencoded" -d "stato=3&cig=8874674CA7" | jq '.'

Search by CIG — award results (Esiti)

curl -sSkX POST "https://www.serviziocontrattipubblici.it/WSConsultBandi/rest/Esiti/Lista?page_limit=10&offset=0" -H "Content-Type: application/x-www-form-urlencoded" -d "stato=3&cig=8874674CA7" | jq '.'

Note: Z-prefix CIG (below-threshold direct awards) appear in Esiti, not in Bandi. Try both endpoints when a CIG returns no results in one of them.

---

Source 4 — ANAC BDNCP: CUP↔CIG Join & Below-Threshold CIGs

Dataset pages:

• CIG: https://dati.anticorruzione.it/opendata/dataset/cig
• CUP: https://dati.anticorruzione.it/opendata/dataset/cup

Access: Bulk CSV/JSON download (no live API — WAF blocks programmatic queries). Live API: Not available.

Workflow

1. Download the dataset CSV from the ANAC portal.
2. Load into DuckDB for fast querying:

duckdb -c "DESCRIBE SELECT * FROM read_csv_auto('cup.csv', HEADER=TRUE) LIMIT 1;"
duckdb -c "SELECT * FROM read_csv_auto('cup.csv', HEADER=TRUE) WHERE cig = 'Z063947806' LIMIT 10;"

Key use cases

• Find CIG(s) associated with a CUP: filter cup column.
• Find details of a Z-prefix CIG (direct award): filter cig column.

---

Source 5 — ANAC dettaglio-cig: Full CIG Detail

Portal: https://dettaglio-cig.anticorruzione.it/cig/{CIG} Method: Browser automation via scripts/cig-fetch.sh Requires: agent-browser, jq Coverage: All CIG types (Z-prefix and alphanumeric). Returns 20+ sections.

The payload is far richer than SCP-MIT: includes bando, stazioneAppaltante, partecipanti, incaricati, aggiudicazione, quadroEconomico, subappalti, varianti, categorieOpera, pubblicazioni, and more.

Fetch full detail for a single CIG

bash scripts/cig-fetch.sh 8874674CA7
# → ./8874674CA7.json

bash scripts/cig-fetch.sh 8874674CA7 /tmp
# → /tmp/8874674CA7.json

Troubleshooting

If the script fails with Invalid response: EOF:

agent-browser close

Then rerun the script.

---

Definition of Done

A task is complete when:

• The correct source is selected based on the decision tree above.
• API call returns data (or a clear "no results" message).
• Output is readable (not a raw JSON blob) — use jq to format.
• For bulk sources: DuckDB query returns and formats results.

---

Common Errors

Error	Cause	Fix
401 Unauthorized on OpenCUP	Wrong credentials or not set	Check OPENCUP_API_CLIENT_ID/SECRET
Empty results on OpenBDAP	CUP not in MOP dataset	Project may not have financial monitoring data
No results on SCP-MIT	Z-prefix CIG	Use ANAC BDNCP bulk instead
SSL error on SCP-MIT	Self-signed certificate	Add -k flag to curl