anncsu-sdk 0.0.9.dev17__tar.gz → 0.0.9.dev28__tar.gz

anncsu_sdk-0.0.9.dev28/.speakeasy/out.odonimi.openapi.yaml

@@ -0,0 +1,301 @@
+openapi: "3.0.3"
+info:
+  title: ANNCSU REST API - ODONIMI
+  description: |-
+    API dei servizi REST di ANNCSU su PDND per aggiornamento adonimi
+    Pattern Model applicati:
+    - [AUDIT_REST_02 ] Inoltro dati tracciati nel dominio del Fruitore REST con correlazione
+    - [BLOCK_REST] Blocking REST
+    - [INTEGRITY_REST_02] Integrità del payload messaggio REST in PDND
+  termsOfService: "https://govway.org/documentazione/api/index.html"
+  contact:
+    email: "infopdnd_anncsu@sogei.it"
+  version: "1.0.1"
+  x-api-id: "https://govway.org/apiConfig"
+  x-summary: "Servizi per la configurazione di GovWay"
+servers:
+  - url: https://modipa.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-odonimi/v1
+    description: "l'accesso all'API e' protetta dai controlli di accesso su GovWay"
+  - url: https://modipa-val.agenziaentrate.it/govway/rest/in/AgenziaEntrate-PDND/anncsu-aggiornamento-odonimi/v1
+    description: "l'accesso all'API di validazione e' protetta dai controlli di accesso su GovWay"
+tags:
+  - name: anncsu
+    description: Servizi ANNCSU su PDND
+  - name: status
+security:
+  - bearerAuth: []
+    Agid-JWT-Signature: []
+    Agid-JWT-TrackingEvidence: []
+paths:
+  /odonimi:
+    post:
+      description: Questo endpoint consente di eseguire un'operazione sugli odonimi quali inserimento, aggiornamento e soppressione.
+      operationId: gestioneAnncsuOdonimiPdnd
+      summary: Esegui un'operazione sugli odonimi
+      tags:
+        - "anncsu"
+      requestBody:
+        description: Dati necessari per l'operazione sugli odonimi.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RichiestaOperazione'
+      responses:
+        '200':
+          description: Operazione eseguita con successo
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RispostaOperazione'
+        '400':
+          description: Richiesta non valida
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/RispostaErrore'
+        '404':
+          description: Odonimo non trovato
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/RispostaErrore'
+        '500':
+          description: Errore interno del server
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/RispostaErrore'
+  /status:
+    get:
+      summary: Ritorna lo stato dell'applicazione.
+      description: |
+        Ritorna lo stato dell'applicazione. A scopo
+        di test, su base randomica puo' ritornare
+        un errore.
+      operationId: show_status
+      tags:
+        - "status"
+      responses:
+        '200':
+          description: "Il server ha ritornato lo status. \n"
+          content:
+            application/problem+json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+        '503':
+          description: "Il server non è disponibile. \n"
+          content:
+            application/problem+json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+components:
+  schemas:
+    RichiestaOperazione:
+      type: object
+      properties:
+        richiesta:
+          type: object
+          properties:
+            codcom:
+              type: string
+              description: Codice del comune (obbligatorio)
+              example: "A062"
+            tipo_operazione:
+              type: string
+              enum: [I, R, S]
+              description: Tipo di operazione ('S'=Soppressione, 'I'=Inserimento, 'R'=Aggiornamento)
+              example: "R"
+            progr_nazionale:
+              type: string
+              maxLength: 10
+              description: Progressivo nazionale (obbligatorio per soppressione e aggiornamento)
+              example: "2000449"
+            codice_comunale:
+              type: string
+              maxLength: 30
+              nullable: true
+              description: Codifica comunale dell'odonimo. Non viene applicato l'uppercase
+              example: "75439 d"
+            dug:
+              type: string
+              maxLength: 30
+              description: DUG (obbligatorio per inserimento e aggiornamento, non ammesso per soppressione, non soggetto a controllo di esistenza nel dizionario)
+              example: "VIA"
+            denom_delibera:
+              type: string
+              maxLength: 120
+              description: Denominazione Delibera. Viene applicato l'uppercase
+              example: "DELLE ORCHIDEE"
+            denom_in_lingua_1:
+              type: string
+              maxLength: 150
+              description: Odonimo in lingua, comprensivo della dug, per comuni bi/tri lingue. Viene applicato l'uppercase
+              example: "ODONIMO LINGUA 1"
+            denom_in_lingua_2:
+              type: string
+              maxLength: 150
+              description: Odonimo in ulteriore lingua, comprensivo della dug, per comuni tri lingue. Viene applicato l'uppercase
+              example: "ODONIMO LINGUA 2"
+            denom_localita:
+              type: string
+              maxLength: 151
+              description: Denominazione Località. Viene applicato l'uppercase
+              example: "CASAL PALOCCO"
+            provvedimento:
+              $ref: '#/components/schemas/Provvedimento'
+            aut_prefettura:
+              $ref: '#/components/schemas/AutPrefettura'
+            data_valid_amm:
+              type: string
+              description: Data di validità amministrativa, minore o uguale della data corrente per inserimento e soppressione. Per aggiornamento anche >= della precedente
+              example: "08/10/2024"
+    Provvedimento:
+      type: object
+      properties:
+        data:
+          type: string
+          description: Data del provvedimento
+          example: "10/10/2023"
+        protocollo:
+          type: string
+          maxLength: 70
+          description: Protocollo del provvedimento. Non viene applicato l'uppercase
+          example: "1234567/abc"
+        flag_delibera:
+          type: string
+          description: Flag della delibera (valori numerici da 0 a 4). I valori 0 e 1 rendono obbligatorie le informazioni data e protocollo
+          example: "1"
+    AutPrefettura:
+      type: object
+      properties:
+        data_pref:
+          type: string
+          description: Data della prefettura. Obbligatoria se è presente il protocollo_pref
+          example: "10/10/2023"
+        protocollo_pref:
+          type: string
+          maxLength: 70
+          description: Protocollo della prefettura. Non viene applicato l'uppercase. Obbligatorio se è presente data_pref
+          example: "Prot.Gen.1234567"
+    RispostaOperazione:
+      type: object
+      properties:
+        idRichiesta:
+          type: string
+          maxLength: 15
+          description: Identificativo assegnato alla richiesta
+          example: "5145"
+        esito:
+          type: string
+          description: Esito dell'operazione
+          example: "0"
+        messaggio:
+          type: string
+          description: Messaggio associato all'esito
+          example: "OK"
+        dati:
+          type: array
+          items:
+            type: object
+            properties:
+              codcom:
+                type: string
+                description: Codice del comune
+                example: "A062"
+              progr_nazionale:
+                type: string
+                maxLength: 10
+                description: Progressivo nazionale
+                example: "2000449"
+              codice_comunale:
+                type: string
+                maxLength: 30
+                nullable: true
+                description: Codifica comunale dell'odonimo
+                example: "75439 d"
+              dug:
+                type: string
+                maxLength: 30
+                description: DUG (obbligatorio per inserimento e aggiornamento, non ammesso per soppressione)
+                example: "VIA"
+              denom_delibera:
+                type: string
+                maxLength: 120
+                description: Denominazione Delibera
+                example: "DELLE ORCHIDEE"
+              denom_in_lingua_1:
+                type: string
+                maxLength: 150
+                description: Odonimo in lingua, comprensivo della dug, per comuni bi/tri lingue. Viene applicato l'uppercase
+                example: "ODONIMO LINGUA 1"
+              denom_in_lingua_2:
+                type: string
+                maxLength: 150
+                description: Odonimo in ulteriore lingua, comprensivo della dug, per comuni tri lingue. Viene applicato l'uppercase
+                example: "ODONIMO LINGUA 2"
+              data_inizio:
+                type: string
+                description: Data di inizio validità dell'odonimo per l'area di circolazione, identificata dal progressivo nazionale
+                example: "01/10/2020"
+              data_FINE:
+                type: string
+                description: Data di fine validità dell'odonimo per l'area di circolazione, identificata dal progressivo nazionale
+                example: "08/10/2024"
+              data_ini_valid_amm:
+                type: string
+                nullable: true
+                description: Data di inizio validità amministrativa dell'odonimo
+                example: "01/10/2020"
+              data_fine_valid_amm:
+                type: string
+                nullable: true
+                description: Data di fine validità amministrativa dell'area di circolazione e dell'odonimo
+                example: "08/10/2024"
+    RispostaErrore:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Identificativo dell'operazione.
+          example: "5144"
+        codice:
+          type: string
+          description: Codice di errore indicato nella documentazione del servizio
+          example: "23"
+        messaggio:
+          type: string
+          description: Messaggio di errore.
+          example: "Errore di validazione: [specifica qui il messaggio di errore]"
+  securitySchemes:
+    bearerAuth:
+      type: http
+      description: 'A bearer token in the format of a JWS and conformed to the specifications included in [RFC8725](https://tools.ietf.org/html/RFC8725).'
+      scheme: bearer
+      bearerFormat: JWT
+    Agid-JWT-Signature:
+      type: apiKey
+      in: header
+      name: Agid-JWT-Signature
+      description: |-
+        Header della firma di JWS.
+        Il valore di questo header è una firma JWS.
+        Vedere Modi  [integrity_rest_02] Integrità del payload del messaggio REST in PDND
+    Agid-JWT-TrackingEvidence:
+      type: apiKey
+      in: header
+      name: Agid-JWT-TrackingEvidence
+      description: |-
+        Header della firma di JWS.
+        Il valore di questo header è una firma JWS.
+        Vedere Modi  [audit_rest_02] Inoltro dati tracciati nel dominio del Fruitore REST con correlazione
+        Claim da includere:
+            userID, un identificativo univoco dell'utente interno al dominio del fruitore che ha determinato l'esigenza della request di accesso all'e-service dell'erogatore;
+            userLocation, un identificativo univoco della postazione interna al dominio del fruitore da cui è avviata l'esigenza della request di accesso all'e-service dell'erogatore;
+            LoA, livello di sicurezza o di garanzia adottato nel processo di autenticazione informatica nel dominio del fruitore.

{anncsu_sdk-0.0.9.dev17 → anncsu_sdk-0.0.9.dev28}/.speakeasy/workflow.lock

@@ -1,4 +1,4 @@
-speakeasyVersion: 1.763.2
+speakeasyVersion: 1.764.1
 sources:
     ANNCSU Accessi API:
         sourceNamespace: anncsu-accessi-api
@@ -14,6 +14,13 @@ sources:
         tags:
             - latest
             - 1.0.1
+    ANNCSU Odonimi API:
+        sourceNamespace: anncsu-odonimi-api
+        sourceRevisionDigest: sha256:13c2e8a811ac58bec33c91554a63b70bacb04fb30462dc1a4ccd6e44233b32be
+        sourceBlobDigest: sha256:41616a7f631d560a87c26d4995863e1553b73b127dbaca926e822e6e8ba7550b
+        tags:
+            - latest
+            - 1.0.1
 targets:
     accessi:
         source: ANNCSU Accessi API
@@ -29,6 +36,13 @@ targets:
         sourceBlobDigest: sha256:791001f3ee0f6647b59ad55caa568e90a8299245fc127dc6ff6a466c0f7360a2
         codeSamplesNamespace: anncsu-coordinate-api-python-code-samples
         codeSamplesRevisionDigest: sha256:458eace30f305f5d98bccb007663a62a4472d820dc20da7891f379d869b92c23
+    odonimi:
+        source: ANNCSU Odonimi API
+        sourceNamespace: anncsu-odonimi-api
+        sourceRevisionDigest: sha256:13c2e8a811ac58bec33c91554a63b70bacb04fb30462dc1a4ccd6e44233b32be
+        sourceBlobDigest: sha256:41616a7f631d560a87c26d4995863e1553b73b127dbaca926e822e6e8ba7550b
+        codeSamplesNamespace: anncsu-odonimi-api-python-code-samples
+        codeSamplesRevisionDigest: sha256:fafa3f1209c1c4c9eb546fa9f1e433113042b2303c9020cd3c7daf2ee96a719d
 workflow:
     workflowVersion: 1.0.0
     speakeasyVersion: latest
@@ -49,6 +63,14 @@ workflow:
             output: .speakeasy/out.coordinate.openapi.yaml
             registry:
                 location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-coordinate-api
+        ANNCSU Odonimi API:
+            inputs:
+                - location: oas/dev/Specifica API - ANNCSU - Aggiornamento odonimi.yaml
+            transformations:
+                - removeUnused: true
+            output: .speakeasy/out.odonimi.openapi.yaml
+            registry:
+                location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-odonimi-api
         ANNCSU REST API:
             inputs:
                 - location: ../oas/dev/Specifica API - ANNCSU – Consultazione per le PA.yaml
@@ -87,3 +109,13 @@ workflow:
                 labelOverride:
                     fixedValue: Python (SDK)
                 blocking: false
+        odonimi:
+            target: python
+            source: ANNCSU Odonimi API
+            output: odonimi-sdk
+            codeSamples:
+                registry:
+                    location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-odonimi-api-python-code-samples
+                labelOverride:
+                    fixedValue: Python (SDK)
+                blocking: false

{anncsu_sdk-0.0.9.dev17 → anncsu_sdk-0.0.9.dev28}/.speakeasy/workflow.yaml

@@ -17,6 +17,14 @@ sources:
         output: .speakeasy/out.coordinate.openapi.yaml
         registry:
             location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-coordinate-api
+    ANNCSU Odonimi API:
+        inputs:
+            - location: oas/dev/Specifica API - ANNCSU - Aggiornamento odonimi.yaml
+        transformations:
+            - removeUnused: true
+        output: .speakeasy/out.odonimi.openapi.yaml
+        registry:
+            location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-odonimi-api
     ANNCSU REST API:
         inputs:
             - location: ../oas/dev/Specifica API - ANNCSU – Consultazione per le PA.yaml
@@ -55,3 +63,13 @@ targets:
             labelOverride:
                 fixedValue: Python (SDK)
             blocking: false
+    odonimi:
+        target: python
+        source: ANNCSU Odonimi API
+        output: odonimi-sdk
+        codeSamples:
+            registry:
+                location: registry.speakeasyapi.dev/geobeyond-zd1/anncsu/anncsu-odonimi-api-python-code-samples
+            labelOverride:
+                fixedValue: Python (SDK)
+            blocking: false

{anncsu_sdk-0.0.9.dev17 → anncsu_sdk-0.0.9.dev28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.9.dev17
+Version: 0.0.9.dev28
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE

{anncsu_sdk-0.0.9.dev17 → anncsu_sdk-0.0.9.dev28}/docs/CLI.md

@@ -2103,6 +2103,277 @@ The default (without `--auto-resolve`) remains `--progr-civico` explicit — saf
 
 ---
 
+### `anncsu odonimo` - Odonimo CRUD
+
+CRUD operations on ANNCSU street names (odonimi). Three sub-commands map 1:1 to the `tipo_operazione` field of the POST `/odonimi` endpoint:
+
+| Sub-command | `tipo_operazione` | Purpose |
+|---|---|---|
+| `insert` | `I` | Create a new odonimo |
+| `update` | `R` | Replace/update an existing odonimo |
+| `delete` | `S` | Soppressione (logical delete) |
+
+Plus `status` for the GET `/status` health check.
+
+> **ModI headers required**: All write operations require `Agid-JWT-Signature` (INTEGRITY_REST_02) and `Agid-JWT-TrackingEvidence` (AUDIT_REST_02). They are added automatically by the ModI pre-request hook when `PDND_MODI_*` variables are configured.
+
+> **Validation rules**: Inputs are pre-validated by `ValidatedOdonimo` before the API call. Common rules:
+>
+> - `tipo_operazione` must be `I`, `R`, or `S` (enum)
+> - `codcom` is required for every operation
+> - `progr_nazionale` is required for `R`/`S` (assigned by ANNCSU for `I`)
+> - `dug` is required for `I`/`R`, **not allowed for `S`**
+> - If `provvedimento.flag_delibera ∈ {0, 1}`, `provvedimento.data` and `provvedimento.protocollo` are required
+> - `aut_prefettura.data_pref` ↔ `aut_prefettura.protocollo_pref` are mutually required (both or neither)
+> - maxLength enforced on every string field (per OAS spec; e.g. `denom_localita` has the OAS quirk `maxLength: 151` preserved as-is)
+
+#### `anncsu odonimo insert`
+
+Insert a new odonimo (`tipo_operazione='I'`). `--codcom` and `--dug` are required; `--prognaz` is assigned by ANNCSU.
+
+```bash
+# Minimal insert
+anncsu odonimo insert --codcom A062 --dug VIA --denom-delibera "DELLE ORCHIDEE"
+
+# With provvedimento (flag_delibera=1 requires data + protocollo)
+anncsu odonimo insert --codcom A062 --dug VIA --denom-delibera "DEI TIGLI" \
+    --provv-data 10/10/2023 --provv-protocollo "1234567/abc" \
+    --provv-flag-delibera 1
+
+# Full insert with aut_prefettura + multilingua
+anncsu odonimo insert --codcom A062 --dug VIA \
+    --denom-delibera "DELLE ORCHIDEE" \
+    --denom-in-lingua-1 "STRASSE DER ORCHIDEEN" \
+    --denom-localita "CASAL PALOCCO" \
+    --provv-data 10/10/2023 --provv-protocollo "1234/abc" \
+    --provv-flag-delibera 1 \
+    --prefettura-data 11/10/2023 \
+    --prefettura-protocollo "Prot.Gen.1234567" \
+    --data-valid-amm 08/10/2024
+```
+
+Options:
+
+- `--codcom, -c` - Codice comune (Belfiore code, e.g. `A062`) **[required]**
+- `--dug` - DUG (e.g. `VIA`, `PIAZZA`, `STRADA`) **[required for I/R]**
+- `--denom-delibera` - Denominazione delibera (uppercase applied server-side)
+- `--denom-in-lingua-1` / `--denom-in-lingua-2` - Odonimo in lingua (per comuni bi/tri-lingua)
+- `--denom-localita` - Denominazione località (uppercase applied)
+- `--codice-comunale` - Codifica comunale dell'odonimo (no uppercase)
+- `--provv-data` - Data del provvedimento (formato `dd/MM/yyyy`)
+- `--provv-protocollo` - Protocollo del provvedimento (max 70 char, no uppercase)
+- `--provv-flag-delibera` - Flag delibera (`0`-`4`); `0` and `1` make `--provv-data` + `--provv-protocollo` required
+- `--prefettura-data` - Data prefettura (required if `--prefettura-protocollo`)
+- `--prefettura-protocollo` - Protocollo prefettura (required if `--prefettura-data`)
+- `--data-valid-amm` - Data validità amministrativa (formato `dd/MM/yyyy`)
+- `--token-endpoint, -e` - PDND token endpoint URL
+- `--server-url, -s` - API server URL (auto-discovered from voucher if omitted)
+- `--validation/--production` - Use validation (UAT) or production environment
+- `--no-verify-ssl` - Disable SSL certificate verification
+- `--json` - Output as JSON
+- `--raw` - Print raw API response to stderr
+- `--dry-run` - I + S rollback (see `--dry-run` section below)
+
+JSON output:
+
+```json
+{
+  "success": true,
+  "tipo_operazione": "I",
+  "id_richiesta": "5145",
+  "esito": "0",
+  "messaggio": "OK",
+  "dati_count": 1
+}
+```
+
+#### `anncsu odonimo update`
+
+Update/replace an existing odonimo (`tipo_operazione='R'`). Requires `--prognaz` (or `--auto-resolve` + `--denom`) and `--dug`.
+
+```bash
+# Replace denomination of an existing odonimo
+anncsu odonimo update --codcom A062 --prognaz 2000449 \
+    --dug VIA --denom-delibera "DEI TIGLI"
+
+# Update with auto-resolve (lookup prognaz via PA from base64 denom)
+anncsu odonimo update --codcom A062 \
+    --auto-resolve --denom "VklBIERFTEwgT1JDSElERUU=" \
+    --dug VIA --denom-delibera "DEI TIGLI NUOVI"
+```
+
+Options:
+
+- All `insert` options (except `--prognaz` is required, not assigned)
+- `--prognaz, -p` - Progressivo nazionale dell'odonimo (required unless `--auto-resolve`)
+- `--auto-resolve` - Resolve `--prognaz` via PA from `--codcom` + `--denom` (see `--auto-resolve` section)
+- `--denom` - Base64-encoded denomination used with `--auto-resolve`
+
+#### `anncsu odonimo delete`
+
+Soppressione (logical delete) of an odonimo (`tipo_operazione='S'`).
+
+```bash
+# Minimal delete (data_valid_amm defaults to today)
+anncsu odonimo delete --codcom A062 --prognaz 2000449
+
+# With explicit end-of-validity date
+anncsu odonimo delete --codcom A062 --prognaz 2000449 \
+    --data-valid-amm 31/12/2025
+
+# Delete via auto-resolve
+anncsu odonimo delete --codcom A062 \
+    --auto-resolve --denom "VklBIERFTEwgT1JDSElERUU="
+```
+
+Options:
+
+- `--codcom, -c` - Codice comune **[required]**
+- `--prognaz, -p` - Progressivo nazionale (required unless `--auto-resolve`)
+- `--auto-resolve` / `--denom` - Same as `update`
+- `--data-valid-amm` - Data **fine** validità amministrativa (formato `dd/MM/yyyy`)
+- Other shared options (`--token-endpoint`, `--server-url`, `--validation/--production`, `--no-verify-ssl`, `--json`, `--raw`, `--dry-run`)
+
+> **Note**: `delete` does NOT accept `--dug`, `--denom-*`, `--codice-comunale`, `--provv-*`, or `--prefettura-*` — Typer rejects them at parse time as unknown options because they have no meaning for a soppressione.
+
+#### `anncsu odonimo status`
+
+Check the status of the Odonimi API service:
+
+```bash
+anncsu odonimo status
+anncsu odonimo status --production
+anncsu odonimo status --json
+```
+
+#### `anncsu odonimo *` — `--dry-run` flag
+
+All three write commands accept `--dry-run` to execute a full CRUD cycle on a **fictitious odonimo** (generated automatically) so real data is never touched.
+
+Unlike `accesso --dry-run` (which operates on an existing accesso via test+restore), `odonimo --dry-run` **always creates and deletes a temporary odonimo** with a recognizable `TEST SDK <timestamp>-<uuid>` denomination.
+
+| Command | Cycle | API calls |
+|---|---|---|
+| `insert --dry-run` | I (user data) → S (rollback) | 2 |
+| `update --dry-run` | I (fake denom) → R (user data on fake) → S (cleanup) | 3 |
+| `delete --dry-run` | I (fake denom) → S (immediate) | 2 |
+
+**Fictitious odonimo details**:
+
+- `denom_delibera = "TEST SDK <YYYYMMDDHHMMSS>-<short-uuid>"`
+- `dug = "VIA"` (fixed)
+- `codcom` = whichever value the user passes
+- Easily identifiable in audit logs for manual cleanup if a crash occurs
+
+**Crash safety**: before any rollback API call, a JSON file is written to `~/.anncsu/dryrun_pending.json` with all data needed for manual cleanup if the CLI crashes between steps.
+
+**For `update --dry-run`**: `--prognaz` and `--auto-resolve` are ignored (a warning is printed) because the R is always applied to the fake odonimo generated by the preceding I.
+
+Examples:
+
+```bash
+# Insert dry-run — creates the odonimo with user data, then deletes it
+anncsu odonimo insert --codcom A062 --dug VIA \
+    --denom-delibera "DELLE ORCHIDEE" --dry-run
+
+# Update dry-run — fake I → user R on fake → cleanup S
+anncsu odonimo update --codcom A062 --dug VIA \
+    --denom-delibera "DEI TIGLI" --dry-run
+
+# Delete dry-run — fake I → immediate S (smoke-test del flusso S)
+anncsu odonimo delete --codcom A062 --dry-run
+```
+
+JSON output of `--dry-run` (delete example):
+
+```json
+{
+  "success": true,
+  "tipo_operazione": "S",
+  "fake_denom": "TEST SDK 20260524150301-3f8a1b2c",
+  "fake_prognaz": "9999999",
+  "test_op": {
+    "success": true,
+    "tipo_operazione": "I",
+    "id_richiesta": "REQ-I",
+    "esito": "0",
+    "messaggio": "OK",
+    "dati_count": 1
+  },
+  "update_op": null,
+  "rollback": {
+    "success": true,
+    "tipo_operazione": "S",
+    "id_richiesta": "REQ-S",
+    "esito": null,
+    "messaggio": null,
+    "dati_count": 1
+  },
+  "rollback_failed": false,
+  "pending_log_path": "/Users/me/.anncsu/dryrun_pending.json",
+  "error_message": null
+}
+```
+
+> **Note on `esito` for S operations**: the server response for S (delete/cleanup) does **not** carry `esito` (it is `null`). Success is detected by the presence of `data_FINE` / `data_fine_valid_amm` in the `dati` payload, which mark the closure timestamp of the odonimo. The CLI maps this into `"success": true` even though `esito` stays `null` — this is by design.
+
+For `update --dry-run`, the `update_op` field is populated (R step), and `tipo_operazione` is `"R"`.
+
+##### Recovery from a pending log
+
+If the CLI crashes between the I step and the rollback S, `~/.anncsu/dryrun_pending.json` contains:
+
+```json
+{
+  "timestamp": "2026-05-24T15:03:01.123456+00:00",
+  "tipo_operazione": "I_then_S",
+  "payload": {
+    "codcom": "A062",
+    "fake_prognaz": "9999999",
+    "fake_denom": "TEST SDK 20260524150301-3f8a1b2c"
+  },
+  "note": "Created an odonimo via I; about to delete via S to roll back. If the CLI crashed before deletion, run `anncsu odonimo delete --codcom A062 --prognaz 9999999` manually.",
+  "pid": 12345
+}
+```
+
+Manual cleanup:
+
+```bash
+anncsu odonimo delete --codcom A062 --prognaz 9999999
+rm ~/.anncsu/dryrun_pending.json
+```
+
+#### `anncsu odonimo update/delete` — `--auto-resolve` flag
+
+`update` and `delete` both require `--prognaz` to identify the target odonimo. As an alternative, pass `--auto-resolve` together with `--denom` (base64-encoded denomination) to have the CLI look up the `prognaz` automatically via PA API.
+
+```bash
+# Encode denomination to base64 (full street name including dug)
+echo -n "VIA DELLE ORCHIDEE" | base64
+# VklBIERFTExFIE9SQ0hJREVF
+
+# Update via auto-resolve
+anncsu odonimo update --codcom A062 \
+    --auto-resolve --denom "VklBIERFTExFIE9SQ0hJREVF" \
+    --dug VIA --denom-delibera "DEI TIGLI"
+
+# Delete via auto-resolve
+anncsu odonimo delete --codcom A062 \
+    --auto-resolve --denom "VklBIERFTExFIE9SQ0hJREVF"
+```
+
+Errors:
+
+- `--auto-resolve` without `--denom` → error (lookup needs the base64 denomination)
+- PA lookup returns 0 matches → error (no odonimo found)
+- PA lookup returns >1 matches → error (ambiguous, specify `--prognaz` directly)
+- If both `--prognaz` and `--auto-resolve` are provided → `--prognaz` is ignored with a warning
+
+The default (without `--auto-resolve`) remains `--prognaz` explicit — safer for scripting and CI/CD where you typically already know the identifier.
+
+---
+
 ## Environment Variables
 
 The CLI reads configuration from environment variables (with `PDND_` prefix) or a `.env` file: