{
  "openapi": "3.1.0",
  "info": {
    "title": "SaaS RENTRI — annullamento controllato FIR (DEMO/PROD)",
    "version": "1.1.0",
    "description": "Disabilitato per default. DEMO/PROD, nessun nuovo permesso alle chiavi esistenti. 202/success tecnico non confermano Annullato. Nessuna nota o firma sul formulario inviata automaticamente. PROD: richiede opt-in del modulo, deployment vincolato, capacità di lettura e certificato approvato; le mutazioni richiedono anche i gate di invio."
  },
  "x-implementation-status": "implemented-demo-prod-offline-tested-disabled-by-default",
  "paths": {
    "/api/v1/fir/{numero_fir}/annullamento": {
      "post": {
        "operationId": "requestFirCancellation",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-required-scope": "fir:cancel",
        "parameters": [
          {
            "name": "numero_fir",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\"v[1-9][0-9]*\"$"
            },
            "description": "Versione locale con virgolette. Non è un If-Match upstream, non previsto da annulla-fir."
          },
          {
            "name": "X-Retry-Not-Sent",
            "in": "header",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "description": "Recupero esplicito della sola operazione not_sent, stessi dati/versione, mai unknown."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "motivo"
                ],
                "properties": {
                  "motivo": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024,
                    "description": "Motivo locale auditabile, non nota RENTRI. Vietati soli spazi e controlli non stampabili."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Esito tecnico già disponibile; controllare separatamente annullamento.stato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "202": {
            "description": "Richiesta in corso; NON conferma Annullato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "401": {
            "description": "Chiave non valida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "403": {
            "description": "Scope fir:cancel o contesto non autorizzati.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "404": {
            "description": "FIR non appartenente al client.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflitto/esito incerto, non cambiare chiave per ritentare.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "412": {
            "description": "Versione locale superata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "422": {
            "description": "Payload invalido o rifiuto definitivo upstream.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "428": {
            "description": "If-Match mancante/non valido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          },
          "503": {
            "description": "Gate, preflight/not_sent o persistenza indisponibili; leggere esito, non cambiare identità.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancellationResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "CancellationOutcome": {
        "type": "object",
        "required": [
          "stato",
          "fase_osservata",
          "confermato_il",
          "motivo_locale",
          "note_inviate_a_rentri",
          "blocco_preinvio",
          "firma_eventuale"
        ],
        "properties": {
          "stato": {
            "enum": [
              "submitting",
              "not_sent",
              "pending",
              "unknown",
              "rejected",
              "awaiting_confirmation",
              "awaiting_signature",
              "confirmed"
            ]
          },
          "fase_osservata": {
            "type": [
              "string",
              "null"
            ]
          },
          "confermato_il": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "motivo_locale": {
            "type": "string"
          },
          "note_inviate_a_rentri": {
            "const": false
          },
          "blocco_preinvio": {
            "type": [
              "string",
              "null"
            ]
          },
          "firma_eventuale": {
            "const": "servizi_ufficiali"
          }
        }
      },
      "CancellationResponse": {
        "type": "object",
        "description": "request_id+data per operazione persistita, oppure request_id+error prima della reservation.",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "operation_id": {
                "type": "string"
              },
              "status": {
                "enum": [
                  "submitting",
                  "not_sent",
                  "pending",
                  "unknown",
                  "failed",
                  "success"
                ]
              },
              "annullamento": {
                "$ref": "#/components/schemas/CancellationOutcome"
              }
            }
          },
          "error": {
            "type": "object"
          }
        }
      }
    }
  },
  "x-native-environments": [
    "demo",
    "prod"
  ]
}
