{
  "openapi": "3.1.0",
  "info": {
    "title": "SaaS RENTRI — validazione preliminare FIR",
    "version": "1.0.0",
    "description": "Controllo locale autenticato con validatori e mapping condivisi. Non certifica regole ambientali, accettazione RENTRI o firmabilità. Nessun invio o lettura remota."
  },
  "x-performs-remote-read": false,
  "x-creates-fir": false,
  "x-consumes-idempotency": false,
  "x-max-body-bytes": 262144,
  "x-max-json-depth": 64,
  "paths": {
    "/api/v1/fir/validazione": {
      "post": {
        "operationId": "validateFirLocally",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-required-scope": "fir:write",
        "description": "Nessuna query. Idempotency-Key non richiesta e ignorata; riferimento non prenotato. Nessuna firma, reservation, numero, operazione o modifica di dati. Disponibile anche con invii disabilitati. Risposta HTTP 200 anche se il controllo è incompleto: leggere data.valido. Le diagnosi sono senza valori privati e senza nomi di campi sconosciuti.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "riferimento",
                  "contesto",
                  "documento"
                ],
                "properties": {
                  "riferimento": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9._:-]{1,128}$"
                  },
                  "contesto": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operator_id",
                      "local_unit_id",
                      "ruolo"
                    ],
                    "properties": {
                      "operator_id": {
                        "type": "string"
                      },
                      "local_unit_id": {
                        "type": "string"
                      },
                      "ruolo": {
                        "enum": [
                          "producer",
                          "transporter",
                          "destination"
                        ],
                        "description": "destination rifiutato con 403: non esiste creazione come destinatario."
                      }
                    }
                  },
                  "documento": {
                    "type": "object",
                    "description": "Identico al documento di POST /api/v1/fir: vocabolario e regole dei validatori di creazione condivisi. Questo involucro non ridefinisce né amplia i campi. Esempio pubblico scaricabile /docs/examples/fir-create.json; matrice completa nella guida API."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Controllo locale valido (valido=true) oppure incompleto (valido=null).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "401": {
            "description": "Chiave assente, scaduta, revocata o non valida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope fir:write, contesto o ruolo non autorizzato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Corpo oltre 256 KiB: validation_payload_too_large.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Diagnosi payload con data.valido=false; query non ammesse con error.code=invalid_query.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Report"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Errore interno inatteso sanitizzato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Autenticazione/isolamento deployment o database non disponibili; errore generale, non diagnosi del payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Issue": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campo",
          "codice",
          "messaggio"
        ],
        "properties": {
          "campo": {
            "type": "string"
          },
          "codice": {
            "type": "string"
          },
          "messaggio": {
            "type": "string"
          }
        }
      },
      "Report": {
        "type": "object",
        "required": [
          "request_id",
          "data"
        ],
        "additionalProperties": false,
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "valido",
              "esito",
              "controlli",
              "errori",
              "avvisi",
              "readiness",
              "invii_abilitati_in_configurazione",
              "fir_creato",
              "garantisce_accettazione_rentri",
              "controlli_non_eseguiti"
            ],
            "properties": {
              "valido": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "true = controlli locali superati; false = dati non validi; null = controllo incompleto."
              },
              "esito": {
                "enum": [
                  "valido",
                  "non_valido",
                  "incompleto"
                ]
              },
              "controlli": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "struttura",
                  "contesto",
                  "prerequisiti_locali",
                  "mapping"
                ],
                "properties": {
                  "struttura": {
                    "enum": [
                      "non_verificata",
                      "non_valida",
                      "valida"
                    ]
                  },
                  "contesto": {
                    "enum": [
                      "non_verificato",
                      "autorizzato"
                    ]
                  },
                  "prerequisiti_locali": {
                    "enum": [
                      "non_verificati",
                      "non_disponibili",
                      "verificati"
                    ]
                  },
                  "mapping": {
                    "enum": [
                      "non_eseguito",
                      "non_valido",
                      "non_eseguibile",
                      "verificato"
                    ]
                  }
                }
              },
              "errori": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/Issue"
                }
              },
              "avvisi": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "$ref": "#/components/schemas/Issue"
                }
              },
              "readiness": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "Requisiti locali conducente/targa già esistenti, non attestazione di firmabilità o partenza.",
                "properties": {
                  "firma_partenza": {
                    "type": "object",
                    "required": [
                      "stato",
                      "mancanti",
                      "invalidi",
                      "fonte"
                    ],
                    "properties": {
                      "stato": {
                        "enum": [
                          "ready",
                          "incomplete",
                          "unknown"
                        ]
                      },
                      "mancanti": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "invalidi": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "fonte": {
                        "type": "string"
                      }
                    }
                  },
                  "partenza": {
                    "type": "object",
                    "required": [
                      "stato",
                      "mancanti",
                      "invalidi",
                      "fonte"
                    ],
                    "properties": {
                      "stato": {
                        "enum": [
                          "ready",
                          "incomplete",
                          "unknown"
                        ]
                      },
                      "mancanti": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "invalidi": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "fonte": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "invii_abilitati_in_configurazione": {
                "type": "boolean",
                "description": "Configurazione immutabile della singola istanza, non disponibilità remota o autorizzazione di invio."
              },
              "fir_creato": {
                "const": false
              },
              "garantisce_accettazione_rentri": {
                "const": false
              },
              "controlli_non_eseguiti": {
                "type": "array",
                "items": {
                  "enum": [
                    "servizi_e_codifiche_rentri",
                    "autorizzazioni_ambientali",
                    "materiale_privato_di_firma",
                    "validita_crittografica_firme",
                    "disponibilita_remota_all_invio"
                  ]
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "request_id",
          "error"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
