pp-openipa

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/developer-tools/openipa/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# IndicePA — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `openipa-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install openipa --cli-only
   ```
2. Verify: `openipa-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/developer-tools/openipa/cmd/openipa-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## Perché openipa?

Il portale IPA richiede navigazione manuale ente per ente. openipa risolve tre problemi concreti per gli agenti che lavorano con la PA italiana:

- **Codice destinatario SDI in un comando** — `fatturazione cf <CF>` restituisce tutti i `cod_uni_ou` abilitati, pronti per la testata XML della fattura PA.
- **Compliance check parallelo** — `cf <CF>` interroga SFE + NSO + domicilio digitale in simultanea e produce una checklist pass/fail.
- **Batch senza loop** — `fatturazione batch` legge centinaia di CF da stdin e torna NDJSON.

## Workflow Recipes

### Emettere una fattura PA

```bash
# Trova il codice IPA dell'ente
openipa-pp-cli enti cerca --nome "comune di Roma" --json | jq '.data.data[0].cod_amm'
# Ottieni cod_uni_ou per la fattura
openipa-pp-cli fatturazione cf --cf 02438750586 --json
# Verifica compliance completa
openipa-pp-cli cf 02438750586
```

### Verificare una PEC prima di inviarci notifiche

```bash
openipa-pp-cli domicilio verifica <pec-ente>
openipa-pp-cli cerca <pec-ente> --json
```

### Navigare la struttura di un ente

```bash
openipa-pp-cli enti tree agid --json
openipa-pp-cli uo list --codice agid --json
```

## When to Use This CLI

Usa openipa quando un agente deve trovare dati anagrafici, PEC, codici destinatario SDI o nodi NSO di enti della PA italiana. È il tool giusto per validare CF contro il registro IPA prima di emettere fatture, verificare se un'amministrazione è abilitata alla fatturazione elettronica, o trovare il domicilio digitale ufficiale a cui inviare notifiche.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Workflow PA in un comando
- **`cf`** — Dato un codice fiscale, verifica in un colpo se l'ente ha SFE attivo, NSO abilitato e domicilio digitale — checklist compliance PA completa.

  _Un agente che verifica la compliance PA deve sapere se un ente è pronto a ricevere fatture, ordini e notifiche digitali in un unico check._

  ```bash
  openipa-pp-cli cf 97735020584 --json
  ```
- **`fatturazione batch`** — Legge CF da stdin, chiama WS01_SFE_CF in parallelo, restituisce NDJSON con CF + cod_uni_ou + stato_canale per pipeline di fatturazione.

  _Un agente che emette fatture PA in batch deve trovare tutti i codici destinatario in un solo passaggio senza loop manuali._

  ```bash
  cat lista_cf.txt | openipa-pp-cli fatturazione batch --json
  ```
- **`enti tree`** — Vista ad albero di un ente con tutte le sue AOO e UO associate — Ente → AOO[N] → UO[M] in output testuale o JSON annidato.

  _Un agente che deve capire la struttura organizzativa di un ente PA ottiene tutto in un comando invece di navigare tre endpoint separati._

  ```bash
  openipa-pp-cli enti tree agid --json
  ```
- **`domicilio verifica`** — Controlla se una PEC è il domicilio digitale attivo di un ente, storico (cessato) o sconosciuta — produce stato classificato.

  _Un agente che invia notifiche PA deve sapere se una PEC è ancora valida prima di usarla — inviare a PEC cessata invalida la comunicazione._

  ```bash
  openipa-pp-cli domicilio verifica <pec-ente> --json
  ```
- **`cerca`** — Dato un indirizzo email o PEC, trova l'ente IPA titolare — AMM, AOO o UO — con cod_amm e tipo entità.

  _Un agente che riceve una PEC in ingresso può risalire all'ente mittente senza conoscere il codice IPA._

  ```bash
  openipa-pp-cli cerca <pec-ente> --json
  ```

## Command Reference

**aoo** — Aree Organizzative Omogenee degli enti

- `openipa-pp-cli aoo cerca <cod_uni_aoo>` — Dati AOO per codice univoco IPA a 7 caratteri (es. `A463BFE`) — **non** il cod_aoo testuale (es. `agid_aoo`)
- `openipa-pp-cli aoo get` — AOO di un ente con filtro opzionale per codice AOO
- `openipa-pp-cli aoo list` — Lista delle AOO di un ente
- `openipa-pp-cli aoo storico <cod_amm>` — Lista AOO di un ente (attive + cessate); espone `cod_uni_aoo` utile per `aoo cerca`

**cerca** — Ricerca trasversale — trova entità IPA per email

- `openipa-pp-cli cerca` — Trova entità IPA (AMM/AOO/UO) associate a un indirizzo email

**domicilio** — Domicili digitali (PEC e SERC) delle entità IPA

- `openipa-pp-cli domicilio aoo` — Domicilio digitale attivo di una AOO
- `openipa-pp-cli domicilio cf` — Domicilio digitale di un ente per codice fiscale
- `openipa-pp-cli domicilio email` — Cerca entità IPA tramite indirizzo domicilio digitale (PEC)
- `openipa-pp-cli domicilio storico-aoo` — Storico domicili digitali di una AOO (inclusi cessati)
- `openipa-pp-cli domicilio storico-uo` — Storico domicili digitali di una UO (inclusi cessati)
- `openipa-pp-cli domicilio uo` — Domicilio digitale attivo di una UO per codice univoco

**enti** — Ricerca e dettagli degli enti (Pubbliche Amministrazioni)

- `openipa-pp-cli enti cerca` — Cerca enti per nome o descrizione
- `openipa-pp-cli enti get` — Dati anagrafici completi di un ente per codice IPA

**fatturazione** — Servizi di fatturazione elettronica (SFE) — ricerca uffici destinatari

- `openipa-pp-cli fatturazione cf` — Uffici destinatari fattura elettronica per codice fiscale ente
- `openipa-pp-cli fatturazione ente` — Canali SFE attivi di un ente per codice IPA

**nso** — Nodi di Smistamento Ordini (NSO) per ordini elettronici

- `openipa-pp-cli nso cf` — Nodi NSO per codice fiscale ente
- `openipa-pp-cli nso ente` — Canali NSO attivi di un ente per codice IPA

**pec** — Indirizzi PEC degli enti IPA

- `openipa-pp-cli pec ente <cod_amm>` — PEC attive di un ente per codice IPA (WS20)
- `openipa-pp-cli pec storico <cod_amm>` — Storico PEC di un ente, attive e cessate (WS21)
- `openipa-pp-cli pec cerca <indirizzo-pec>` — Storia di un indirizzo PEC specifico nell'IPA (WS22)

**uo** — Unità Organizzative degli enti

- `openipa-pp-cli uo get` — Dettagli di una singola UO per codice univoco
- `openipa-pp-cli uo list` — Lista delle UO di un ente

**servizi** — Servizi digitali pubblicati sul portale IPA (non API pubblica, nessun AUTH_ID richiesto)

- `openipa-pp-cli servizi tipi` — Lista le tipologie di servizi digitali degli enti. Usa questi ID con `servizi ente --tipologia`.
- `openipa-pp-cli servizi tipi --uo` — Lista le categorie dei servizi erogati dalle UO. Usa questi ID con `servizi uo --categoria`.
- `openipa-pp-cli servizi ente` — Cerca servizi online erogati da enti, con URL quando presente: albo pretorio, pagoPA, SUAP, tributi, pratiche edilizie, concorsi, contravvenzioni, appalti.
- `openipa-pp-cli servizi uo` — Cerca UO per categoria o descrizione del servizio erogato, spesso con email e codice UO.

Esempi:

```bash
# Albo pretorio / accesso agli atti del Comune di Bari
openipa