{
  "openapi": "3.1.0",
  "info": {
    "title": "SaaS RENTRI — elenco FIR",
    "version": "1.1.0",
    "description": "Elenco locale dei FIR confermati del client nei contesti attualmente autorizzati. Filtri AND, date RFC3339 con offset, intervalli [da,a). Non effettua letture RENTRI. Documentazione operativa su /docs."
  },
  "x-implementation-status": "implemented-step-2",
  "paths": {
    "/api/v1/fir": {
      "get": {
        "operationId": "listClientFirs",
        "x-implementation-status": "implemented-step-2",
        "x-required-scope": "fir:read",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Solo FIR locali confermati del client e dei contesti attualmente autorizzati. Parametri non dichiarati, array o vuoti rifiutati. Nessuna selezione ambiente. Firme osservate con freschezza separata; filtri affidabili solo su current/coerente. Nessun totale obbligatorio. Nessuna snapshot immutabile fra pagine. Query massima 16384 byte, parametri duplicati e body GET rifiutati; confronto binario esatto anche per spazi finali. Nessun ETag di pagina o conteggio totale.",
        "parameters": [
          {
            "name": "emissione_da",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite incluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "emissione_a",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite escluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "inizio_trasporto_da",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite incluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "inizio_trasporto_a",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite escluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "aggiornamento_da",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite incluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "aggiornamento_a",
            "in": "query",
            "required": false,
            "description": "RFC3339 con offset, massimo 6 decimali; limite escluso. UTC 1000–9999; da < a se entrambi presenti.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "operator_id",
            "in": "query",
            "required": false,
            "description": "Identificativo pubblico del contesto esecutore autorizzato.",
            "schema": {
              "type": "string",
              "pattern": "^op_[a-f0-9]{32}$"
            }
          },
          {
            "name": "local_unit_id",
            "in": "query",
            "required": false,
            "description": "Identificativo pubblico del contesto esecutore autorizzato.",
            "schema": {
              "type": "string",
              "pattern": "^ul_[a-f0-9]{32}$"
            }
          },
          {
            "name": "numero_fir",
            "in": "query",
            "required": false,
            "description": "Confronto binario esatto, senza trim. Vietati caratteri di controllo.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "riferimento",
            "in": "query",
            "required": false,
            "description": "Confronto binario esatto, senza trim. Vietati caratteri di controllo.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "stato",
            "in": "query",
            "required": false,
            "description": "Vedere il dizionario v1; acceptance non prova chiusura documentale.",
            "schema": {
              "type": "string",
              "enum": [
                "InserimentoQuantita",
                "InserimentoQuantitaTrasportoIniziale",
                "InserimentoTrasportoIniziale",
                "FirmaProduttoreTrasportatoreIniziale",
                "FirmaTrasportatoreIniziale",
                "FirmaProduttore",
                "InserimentoTrasportoSuccessivo",
                "FirmaTrasportatoreSuccessivo",
                "FirmaAnnotazione",
                "FirmaTrasbordoParziale",
                "FirmaTrasbordoTotale",
                "FirmaSostaTecnica",
                "FirmaAllegato",
                "InserimentoAccettazione",
                "FirmaAccettazione",
                "Accettato",
                "RespintoAccettatoParzialmente",
                "FirmaDestinatarioSuccessivo",
                "FirmaAccettazioneSuccessiva",
                "FirmaAnnullamento",
                "Annullato",
                "Indeterminato"
              ]
            }
          },
          {
            "name": "categoria",
            "in": "query",
            "required": false,
            "description": "Vedere il dizionario v1; acceptance non prova chiusura documentale.",
            "schema": {
              "type": "string",
              "enum": [
                "preparazione",
                "firme_iniziali",
                "in_corso",
                "conferimento",
                "annullamento_in_corso",
                "annullato",
                "indeterminato"
              ]
            }
          },
          {
            "name": "aperto",
            "in": "query",
            "required": false,
            "description": "Vedere il dizionario v1; acceptance non prova chiusura documentale.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false",
                "unknown"
              ]
            }
          },
          {
            "name": "firma_produttore",
            "in": "query",
            "required": false,
            "description": "Presente/non_rilevata richiedono osservazione current e coerente; altrimenti non_disponibile.",
            "schema": {
              "type": "string",
              "enum": [
                "presente",
                "non_rilevata",
                "non_disponibile"
              ]
            }
          },
          {
            "name": "firma_trasportatore",
            "in": "query",
            "required": false,
            "description": "Presente/non_rilevata richiedono osservazione current e coerente; altrimenti non_disponibile.",
            "schema": {
              "type": "string",
              "enum": [
                "presente",
                "non_rilevata",
                "non_disponibile"
              ]
            }
          },
          {
            "name": "firma_destinatario",
            "in": "query",
            "required": false,
            "description": "Presente/non_rilevata richiedono osservazione current e coerente; altrimenti non_disponibile.",
            "schema": {
              "type": "string",
              "enum": [
                "presente",
                "non_rilevata",
                "non_disponibile"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "NULL sempre ultimi, ID interno come spareggio nella stessa direzione.",
            "schema": {
              "type": "string",
              "enum": [
                "emissione",
                "inizio_trasporto",
                "aggiornamento"
              ],
              "default": "aggiornamento"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Direzione ordinamento.",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Query decimale senza zeri iniziali.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursore cifrato di 24h legato a client/query/limit. Non è una fotografia immutabile.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 8192
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pagina locale autorizzata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirSearchPage"
                }
              }
            }
          },
          "401": {
            "description": "Credenziale non valida."
          },
          "403": {
            "description": "Scope mancante o contesto esplicito non autorizzato."
          },
          "422": {
            "description": "invalid_query o invalid_cursor, involucro errore standard SaaS."
          },
          "503": {
            "description": "search_index_unavailable: indice incompleto o non allineato, ricostruzione riservata al gestore. Non ritentare creando nuovi FIR."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Signature": {
        "type": "string",
        "enum": [
          "presente",
          "non_rilevata",
          "non_disponibile"
        ]
      },
      "FirSearchItem": {
        "type": "object",
        "required": [
          "numero_fir",
          "riferimento",
          "operator_id",
          "local_unit_id",
          "data_emissione",
          "inizio_trasporto",
          "ultimo_aggiornamento",
          "provenienza",
          "stato",
          "categoria",
          "aperto",
          "firme",
          "osservazione",
          "versione",
          "riepilogo"
        ],
        "properties": {
          "numero_fir": {
            "type": "string"
          },
          "riferimento": {
            "type": "string"
          },
          "operator_id": {
            "type": "string",
            "pattern": "^op_[a-f0-9]{32}$"
          },
          "local_unit_id": {
            "type": "string",
            "pattern": "^ul_[a-f0-9]{32}$"
          },
          "data_emissione": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "inizio_trasporto": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "ultimo_aggiornamento": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "provenienza": {
            "type": "object",
            "required": [
              "emissione",
              "inizio_trasporto",
              "aggiornamento"
            ],
            "properties": {
              "emissione": {
                "enum": [
                  "rentri_observed",
                  "unavailable"
                ]
              },
              "inizio_trasporto": {
                "enum": [
                  "rentri_observed",
                  "gateway_confirmed",
                  "unavailable"
                ]
              },
              "aggiornamento": {
                "enum": [
                  "gateway_confirmation",
                  "rentri_observation",
                  "unavailable"
                ]
              }
            }
          },
          "stato": {
            "type": [
              "string",
              "null"
            ],
            "description": "Fase originale osservata o comunicata alla conferma, mai prova di firma."
          },
          "categoria": {
            "type": "string",
            "enum": [
              "preparazione",
              "firme_iniziali",
              "in_corso",
              "conferimento",
              "annullamento_in_corso",
              "annullato",
              "indeterminato"
            ]
          },
          "aperto": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "firme": {
            "type": "object",
            "required": [
              "produttore",
              "trasportatore",
              "destinatario"
            ],
            "properties": {
              "produttore": {
                "$ref": "#/components/schemas/Signature"
              },
              "trasportatore": {
                "$ref": "#/components/schemas/Signature"
              },
              "destinatario": {
                "$ref": "#/components/schemas/Signature"
              }
            }
          },
          "osservazione": {
            "type": "object",
            "required": [
              "ultima_verifica",
              "aggiornamento_dati",
              "coerente_con_versione_locale"
            ],
            "properties": {
              "ultima_verifica": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "aggiornamento_dati": {
                "enum": [
                  "never_checked",
                  "current",
                  "stale",
                  "error"
                ]
              },
              "coerente_con_versione_locale": {
                "type": "boolean"
              }
            }
          },
          "versione": {
            "type": "integer",
            "minimum": 1,
            "description": "Ultima versione locale confermata, distinta da quella RENTRI."
          },
          "riepilogo": {
            "$ref": "./fir-summary.schema.json#/$defs/Compact"
          }
        }
      },
      "FirSearchPage": {
        "type": "object",
        "required": [
          "request_id",
          "data",
          "meta"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FirSearchItem"
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "limit",
              "next_cursor"
            ],
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              },
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    }
  }
}
