openapi: 3.0.1 info: title: Caitel_Validazione-Libretti description: CAITEL - Api pubblicate per la validazione massiva dei libretti di impianto contact: name: Supporto Validazione Libretti Caitel url: https://servizi.regione.liguria.it/page/welcome/CAITEL email: caitel-api-assistenza@liguriadigitale.it version: 1.0.0 x-summary: API per la validazione massiva dei libretti di impianto e il download dei PDF validati nel sistema regionale CAITEL (Liguria) servers: - url: https://services-caitel.regione.liguria.it/api/validazione-libretti description: Url Server di PRODUZIONE specifico per validazione libretti x-sandbox: false - url: https://services-caitel-test.regione.liguria.it/api/validazione-libretti description: Url Server di TEST specifico per validazione libretti x-sandbox: false security: - BearerAuth: [] tags: - name: validazione-libretti-controller description: Operazioni relative alla validazione massiva dei libretti - name: enums-controller description: Operazioni relative alle enumerations - name: sistema-controller description: Operazioni di sistema paths: /validazioni-multiple-libretti/valida: post: tags: - validazione-libretti-controller summary: Valida piu' libretti in un'unica chiamata description: "Sottopone a validazione fino a 100 libretti in bozza in un'unica\ \ chiamata. Ogni libretto puo' essere identificato dalla sola codiceImpianto\ \ (risoluzione lato server) oppure dalla quaterna+libretto restituita da \"\ cerca\". Restituisce un esito per ciascun libretto, nello stesso ordine della\ \ request, con il dettaglio degli eventuali errori. Se NESSUNO dei libretti\ \ richiesti viene validato la risposta e' 400, senza l'elenco degli esiti:\ \ gli errori di validazione sono in informazioni (stesso formato degli altri\ \ errori 400). Con almeno un libretto validato la risposta e' 200. Lo stato\ \ successivo di ogni libretto (generazione del PDF) si segue con verifica-stato." operationId: validaLibretti parameters: - $ref: '#/components/parameters/CodiceFiscaleOperatore' requestBody: content: application/json: schema: $ref: '#/components/schemas/RichiestaValidazioneLibretti' required: true responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/EsitoValidazioneLibrettiRisposta' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' /validazioni-multiple-libretti/cerca: post: tags: - validazione-libretti-controller summary: Cerca libretti in bozza validabili description: "Restituisce tutti i libretti in bozza della ditta chiamante, validabili\ \ tramite il servizio \"valida\". Nessun filtro applicabile." operationId: cercaLibrettiDaValidare parameters: - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/ElencoLibrettiDaValidare' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' /validazioni-multiple-libretti/elenco-validati: get: tags: - validazione-libretti-controller summary: Elenco libretti validati description: "Restituisce, paginato e ordinabile, l'elenco dei libretti gia'\ \ validati della ditta chiamante. Vedi GET /enums/libretti-validati/ordina-per-con-verso\ \ per i valori ammessi di ordinaPerConVerso." operationId: elencoLibrettiValidati parameters: - name: pagina in: query description: La prima pagina 1 (Uno basata) required: false schema: minimum: 1 type: integer default: 1 example: 1 - name: numeroElementiPerPagina in: query description: Quanti elementi in una pagina required: false schema: minimum: 20 type: integer default: 20 example: 20 - name: ordinaPer in: query description: Ordina secondo questo campo required: false schema: type: string default: "-" example: "-" - name: versoOrdinamento in: query description: Verso ordinamento crescente|decrescente required: false schema: type: string default: crescente example: crescente - name: ordinaPerConVerso in: query description: "Ordinamento e verso in un unica stringa, split '||'." required: false schema: type: string default: "-" example: "-" - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/ElencoLibrettiValidati' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' /status: get: tags: - sistema-controller summary: Api di verifica risposta sistema description: Fornisce informazioni sullo stato del sistema operationId: informazioniSistema parameters: - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/BooleanProblemAndJson' /status/operatore: get: tags: - sistema-controller summary: Api di verifica utilizzo del sistema da parte dell'operatore description: Fornisce informazioni sullo stato del sistema per l'operatore utilizzato nell'invocazione operationId: informazioniSistemaPerUtente parameters: - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/BooleanProblemAndJson' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' ? /impianto/libretto-valida/verifica-stato/{identificativo-impianto}/{codice-impianto}/{identificativo-indirizzo}/{identificativo-responsabile}/{identificativo-libretto} : get: tags: - validazione-libretti-controller summary: Verifica lo stato di validazione di un libretto description: "Dopo aver inviato un libretto in validazione con \"valida\", indica\ \ se e' stato validato (stato VALIDATO, PDF disponibile), se la validazione\ \ e' ancora in corso o se non e' andata a buon fine, con i relativi errori.\ \ Libretto inesistente, di un'altra ditta o identificativi non coerenti tra\ \ loro: 404." operationId: verificaStatoLibretto parameters: - name: identificativo-impianto in: path description: "Identificativo dell'impianto (valore cifrato e opaco, come restituito\ \ dai servizi)" required: true schema: type: string example: Fodeq4ftqKSo6_rUqwjUyA - name: codice-impianto in: path description: "Codice Caitel dell'impianto. Formato: 07 seguito da codice belfiore\ \ del comune e ulteriori 10 numeri. Pattern: 07 + 1 lettera (A-ILM) + 13\ \ cifre." required: true schema: pattern: "^07[A-ILM][0-9]{13}$" type: string example: 07A1110000000069 - name: identificativo-indirizzo in: path description: Identificativo dell'indirizzo. required: true schema: type: string example: 187452 - name: identificativo-responsabile in: path description: "Identificativo responsabile (valore cifrato e opaco, come restituito\ \ dai servizi)" required: true schema: type: string example: kOo4-DORNPN41BZZ-LaWnA - name: identificativo-libretto in: path description: "Identificativo del libretto (valore cifrato e opaco, come restituito\ \ dagli altri servizi)" required: true schema: type: string example: zVwNvOJwh450uyYFgMQdQA - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/VerificaStatoLibrettoRisposta' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' ? /impianto/libretto-pdf/scarica/validato/{identificativo-impianto}/{codice-impianto}/{identificativo-indirizzo}/{identificativo-responsabile}/{identificativo-libretto} : get: tags: - validazione-libretti-controller summary: Scarica il PDF di un libretto validato description: "Download del PDF del libretto gia' validato identificato dalla\ \ quaterna impianto e dall'identificativo del libretto. Libretto inesistente,\ \ non validato o con il PDF non ancora generato: 404." operationId: scaricaLibrettoValidatoByIdLibretto parameters: - name: identificativo-impianto in: path description: "Identificativo dell'impianto (valore cifrato e opaco, come restituito\ \ dai servizi)" required: true schema: type: string example: Fodeq4ftqKSo6_rUqwjUyA - name: codice-impianto in: path description: "Codice Caitel dell'impianto. Formato: 07 seguito da codice belfiore\ \ del comune e ulteriori 10 numeri.Pattern: 07 + 1 lettera (A-ILM) + 13\ \ cifre." required: true schema: pattern: "^07[A-ILM][0-9]{13}$" type: string example: 07A1110000000069 - name: identificativo-indirizzo in: path description: Identificativo dell'indirizzo. required: true schema: type: string example: 187452 - name: identificativo-responsabile in: path description: "Identificativo responsabile (valore cifrato e opaco, come restituito\ \ dai servizi)" required: true schema: type: string example: kOo4-DORNPN41BZZ-LaWnA - name: identificativo-libretto in: path description: "Identificativo del libretto (valore cifrato e opaco, come restituito\ \ dagli altri servizi)" required: true schema: type: string example: zVwNvOJwh450uyYFgMQdQA - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/ScaricaLibrettoValidatoRisposta' "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' /enums/libretti-validati/ordina-per-con-verso: get: tags: - enums-controller summary: Ordinamento completo elenco libretti validati (campo + verso) description: Restituisce le combinazioni di campo e verso (es. dataValidazione||decrescente) secondo cui ordinare il risultato di GET /validazioni-multiple-libretti/elenco-validati operationId: librettiValidatiOrdinaPerConVerso parameters: - $ref: '#/components/parameters/CodiceFiscaleOperatore' responses: "409": description: "Conflitto con lo stato dei dati (dato gia' presente o operazione\ \ non consentita nello stato attuale): il motivo e' in informazioni" content: application/problem+json: schema: $ref: '#/components/schemas/ConflictCaitelResponse' "429": description: "Troppe richieste: riprovare dopo i secondi indicati nell'header\ \ Retry-After" content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsCaitelResponse' "500": description: Internal server error content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerErrorCaitelResponse' "404": description: Non trovati content: application/problem+json: schema: $ref: '#/components/schemas/NotFoundCaitelResponse' "403": description: Richiesta non autorizzata content: application/problem+json: schema: $ref: '#/components/schemas/ForbiddenCaitelResponse' "200": description: Ok content: application/json: schema: $ref: '#/components/schemas/ListaValori' "400": description: Dati sintatticamente errati content: application/problem+json: schema: $ref: '#/components/schemas/BadRequestCaitelResponse' components: schemas: LibrettoDaValidareInput: required: - codiceImpianto type: object properties: codiceImpianto: pattern: "^07[A-ILM][0-9]{13}$" type: string description: Codice Caitel dell'impianto example: 07A1110000000075 identificativoImpianto: type: string description: "Identificativo univoco dell'impianto (se noto, es. da \"cerca\"\ ) (valore cifrato e opaco: va ripassato invariato ai servizi che lo richiedono)" example: ycWfz-Z9GWUMocTF5C2arQ identificativoIndirizzo: type: string description: Identificativo univoco dell'indirizzo (se noto) example: "63023" identificativoResponsabile: type: string description: "Identificativo univoco del responsabile (se noto) (valore\ \ cifrato e opaco: va ripassato invariato ai servizi che lo richiedono)" example: Blg6k0nRDJCxj9Y-KM2zGw identificativoLibretto: type: string description: "Identificativo univoco del libretto (se noto) (valore cifrato\ \ e opaco: va ripassato invariato ai servizi che lo richiedono)" example: zVwNvOJwh450uyYFgMQdQA identificativoTipoIntervento: type: string description: "Identificativo del tipo di intervento (opzionale): se inviato\ \ deve coincidere con quello del libretto, altrimenti l'esito e' negativo.\ \ Valori: 1=Nuova installazione, 2=Ristrutturazione, 3=Sostituzione del\ \ generatore, 4=Compilazione libretto impianto esistente" example: "4" enum: - "1" - "2" - "3" - "4" dataIntervento: type: string description: "Data dell'intervento (opzionale, formato GG/MM/AAAA): se inviata\ \ deve coincidere con quella del libretto, altrimenti l'esito e' negativo" example: 02/09/2026 description: "Un libretto da sottoporre a validazione. Il libretto in bozza\ \ della ditta viene individuato da identificativoLibretto se presente, altrimenti\ \ da codiceImpianto: se per quel codiceImpianto la ditta ha piu' libretti\ \ in bozza l'esito e' negativo e va indicato identificativoLibretto (da \"\ cerca\"). codiceImpianto, identificativoTipoIntervento e dataIntervento, se\ \ inviati, devono coincidere con quelli del libretto, altrimenti l'esito e'\ \ negativo." RichiestaValidazioneLibretti: required: - librettiDaValidare type: object properties: librettiDaValidare: type: array description: Lista dei libretti da validare (massimo 100 elementi) items: $ref: '#/components/schemas/LibrettoDaValidareInput' description: "Corpo della richiesta di validazione massiva: elenco dei libretti\ \ da validare in un'unica chiamata (massimo 100 elementi)." Base: type: object description: Corpo della request originale BasePairString: type: object properties: identificativo: type: string description: Chiave tecnica o ID dell'elemento example: D969 valore: type: string description: Etichetta descrittiva da mostrare all'utente example: Genova altroValore: type: string description: Eventuale informazione aggiuntiva di supporto example: GE selezionato: type: boolean description: Indica se l'elemento è quello selezionato di default example: true description: Elenco dei parametri path/query della request ConflictCaitelResponse: type: object properties: responseStatus: type: string informazioni: $ref: '#/components/schemas/ResponseMessage' request: $ref: '#/components/schemas/RequestPayloadBase' title: type: string detail: type: string status: type: integer format: int32 RequestPayloadBase: type: object properties: corpo: $ref: '#/components/schemas/Base' parametri: type: array description: Elenco dei parametri path/query della request items: $ref: '#/components/schemas/BasePairString' description: Oggetto contenente i dati della request originaria utilizzati per la chiamata del servizio ResponseMessage: type: object properties: tipo: type: string enum: - UNDEF - INFO - WARNING - ERROR - SUCCESS - QUESTION systemMessageCode: type: string confirmationToken: type: string messaggio: type: string ulterioriMessaggi: type: array items: type: string ulterioriMessaggiConDettagli: type: array items: $ref: '#/components/schemas/ResponseMessageDetails' stringaUnicaHtmlCompleta: type: string stringaUnicaHtml: type: string ResponseMessageDetails: type: object properties: tipo: type: string enum: - UNDEF - INFO - WARNING - ERROR - SUCCESS - QUESTION dettaglio: type: string ulterioriDettagli: type: array items: $ref: '#/components/schemas/BasePairString' conclusione: type: string domanda: type: string possibiliRisposteDomanda: type: array items: $ref: '#/components/schemas/BasePairString' TooManyRequestsCaitelResponse: type: object properties: responseStatus: type: string informazioni: $ref: '#/components/schemas/ResponseMessage' request: $ref: '#/components/schemas/RequestPayloadBase' title: type: string detail: type: string status: type: integer format: int32 InternalServerErrorCaitelResponse: type: object properties: responseStatus: type: string informazioni: $ref: '#/components/schemas/ResponseMessage' request: $ref: '#/components/schemas/RequestPayloadBase' title: type: string detail: type: string status: type: integer format: int32 NotFoundCaitelResponse: type: object properties: responseStatus: type: string informazioni: $ref: '#/components/schemas/ResponseMessage' request: $ref: '#/components/schemas/RequestPayloadBase' title: type: string detail: type: string status: type: integer format: int32 EsitoValidazioneLibrettiRisposta: type: object properties: elemento: type: array description: "Lista degli esiti di validazione, uno per ogni libretto richiesto,\ \ nello stesso ordine della request" items: $ref: '#/components/schemas/EsitoValidazioneLibretto' responseStatus: type: string informazioni: $ref: '#/components/schemas/ResponseMessage' request: $ref: '#/components/schemas/RequestPayloadRichiestaValidazioneLibretti' description: "Risposta al servizio di validazione massiva: un esito per ciascun\ \ libretto richiesto, nello stesso ordine della request." EsitoValidazioneLibretto: required: - esitoOk type: object properties: codiceImpianto: pattern: "^07[A-ILM][0-9]{13}$" type: string description: Codice Caitel dell'impianto example: 07D9690000069362 identificativoImpianto: type: string description: "Identificativo univoco dell'impianto, assente se il libretto\ \ non e' stato individuato (valore cifrato e opaco: va ripassato invariato\ \ ai servizi che lo richiedono)" example: Fodeq4ftqKSo6_rUqwjUyA identificativoIndirizzo: type: string description: "Identificativo univoco dell'indirizzo, assente se il libretto\ \ non e' stato individuato" example: "57513" identificativoResponsabile: type: string description: "Identificativo univoco del responsabile, assente se il libretto\ \ non e' stato individuato (valore cifrato e opaco: va ripassato invariato\ \ ai servizi che lo richiedono)" example: kOo4-DORNPN41BZZ-LaWnA identificativoLibretto: type: string description: "Identificativo univoco del libretto (valore cifrato e opaco:\ \ va ripassato invariato ai servizi che lo richiedono)" example: 6bThtTQmDB8BZY9ZfTaHBg esitoOk: type: boolean description: true se il libretto e' stato validato con successo example: false erroriValidazione: type: string description: "Motivo dell'esito negativo (presente solo se esitoOk=false):\ \ dettaglio HTML dei campi non validi, oppure il motivo per cui il libretto\ \ non e' stato individuato o la richiesta non e' coerente col libretto" example: "