openapi: 3.0.3
info:
termsOfService: https://termofservice.it
title: 'Stato della piattaforma SEND'
x-summary: 'Stato della piattaforma SEND'
version: '1.0.0'
description: >-
## Abstract
Queste API vengono utilizzate dai soggetti abilitati all’utilizzo della piattaforma SEND e consentono di:
- Visualizzare lo stato dei servizi di SEND,
- Consultare lo storico dei disservizi,
- Per ogni disservizio è possibile scaricare l'atto opponibile a terzi relativo.
NOTA: gli atti opponibili a terzi sono generati solo per i disservizi che sono stati risolti.
# API
Le API messe a disposizione sono le seguenti:
## STATUS stato di SEND, API pubbliche
### operationId: status
- **GET /status**: La seguente API non presenta nessun query params ed ha lo scopo di verificare se, al momento della chiamata all’API, sono presenti dei disservizi su SEND.
- In caso di nessuna anomalia verrà fornito 200 con l’elenco delle funzionalità attive su SEND.
- In caso di anomalie, invece, verrà fornito 500 con l’elenco dei disservizi nel campo “openIncidents”:
- `NOTIFICATION_CREATE`: la possibilità di creare nuove notifiche
- `NOTIFICATION_VISUALIZATION`: la possibilità di visualizzare le notifiche e scaricare gli atti.
- `NOTIFICATION_WORKFLOW`: l'avanzamento del processo di notifica.
## DOWNTIME recupero disservizi di SEND
Le seguenti API vengono utilizzate per vedere la presenza di eventuali disservizi risolti in un dato periodo ed ottenere l’atto opponibile a terzi relativo al disservizio.
1. **Recupera il legalFactId**: Invia una richiesta a **GET /downtime/v1/resolved** per ottenere l'elenco dei disservizi risolti. Troverai il `legalFactId` associato al disservizio.
2. **Ottieni informazioni sull'atto**: Utilizza il `legalFactId` con la chiamata **GET /downtime/v1/legal-facts/{legalFactId}** per ricevere i dettagli dell'atto, compreso l'URL per il download. Se l'atto è ancora in archivio, l'API fornirà una stima del tempo di attesa.
## Le API messe a disposizione sono:
### operationId: getResolved
- **GET /downtime/v1/resolved**:
La seguente API restituisce l’elenco dei disservizi risolti per l’anno ed il mese indicati nei query params `year` e `month` (NOTA: Se non vengono valorizzati i query params si intendono l’anno e/o il mese corrente).
- In caso di disservizi presenti viene restituita un elenco con tutti i disservizi risolti nell’anno e mese selezionati e gli identificativi univoci degli atti disponibili nel campo `legalFactId`.
- In caso non sia presente nessun disservizio risolto nell’anno e mese selezionato, allora verrà restituita una lista vuota.
### operationId: getLegalFact
- **GET /downtime/v1/legal-facts/{legalFactId}**:
La seguente API fornisce le informazioni necessarie a scaricare un atto opponibile a terzi o, se tale atto deve essere recuperato dagli archivi, fornisce una stima per eccesso di quanti secondi bisogna attendere. Il `legalFactId` deve essere inserito nel query param ed è possibile ottenerlo dalla chiamata all’API **GET /downtime/v1/resolved**.
- Nel caso in cui l’atto opponibile fornito sia già presente verranno restituite le informazioni necessarie a scaricarlo compreso l’URL a S3.
- Nel caso in cui l’atto opponibile debba essere recuperato dagli archivi, verrà fornita una stima di quanti secondi bisogna attendere nel campo `retryAfter`.
## interopProbing API per ottenere lo stato dell’E-service
### operationId: getEserviceStatus
- **GET /interop/probing**: La chiamata alla seguente API, usata esclusivamente in PDND interoperabilità, restituisce 200 nel caso in cui l’E-service non presenta alcun disservizio. Al contrario, restituisce 500 nel caso in cui sia presente un disservizio.
contact:
email: pn@pagopa.it
license:
name: Licenza di SEND
url: 'https://da-definire/'
servers:
- url: https://api.notifichedigitali.it
description: Ambiente di produzione
- url: https://api.uat.notifichedigitali.it
description: Ambiente di test
- url: https://api.dev.notifichedigitali.it
description: Ambiente di sviluppo
tags:
- name: Status
description: >-
Lettura dello stato di SEND, API pubbliche
- name: Downtime
description: >-
Invocazioni per recupero dei disservizi di SEND
- name: interopProbing
description: >-
Invocazioni per sapere lo stato dell'E-service di PDND Interoprabilità
paths:
##########################################################################################
### API DI STATO RICHIESTE DA AGID ###
##########################################################################################
###########################################################################################
### LETTURA DELLO STATO ###
###########################################################################################
"/status": # ONLY EXTERNAL
get: # ONLY EXTERNAL
summary: status path # ONLY EXTERNAL
description: >-
Questo path e questo metodo devono, per richiesta di AGID, restituire
- status 200 se la piattaforma notifica è correttamente funzionante,
- status 500 se la piattaforma ha un funzionamento degradato.
Il body e lasciato libero quindi utilizziamo quanto già definito per il path
/downtime/status
tags: # ONLY EXTERNAL
- Status # ONLY EXTERNAL
operationId: status # ONLY EXTERNAL
responses: # ONLY EXTERNAL
'200': # ONLY EXTERNAL
description: Ok # ONLY EXTERNAL
content: # ONLY EXTERNAL
application/problem+json: # ONLY EXTERNAL
schema: # ONLY EXTERNAL
$ref: "./schemas-pn-components-v1.yaml#/components/schemas/PnStatusResponse" # ONLY EXTERNAL
example: # ONLY EXTERNAL
functionalities: [NOTIFICATION_CREATE,NOTIFICATION_VISUALIZATION,NOTIFICATION_WORKFLOW] # ONLY EXTERNAL
openIncidents: [] # ONLY EXTERNAL
'500': # ONLY EXTERNAL
description: Internal Server Error # ONLY EXTERNAL
content: # ONLY EXTERNAL
application/problem+json: # ONLY EXTERNAL
schema: # ONLY EXTERNAL
$ref: "./schemas-pn-components-v1.yaml#/components/schemas/PnStatusResponse" # ONLY EXTERNAL
example: # ONLY EXTERNAL
functionalities: [NOTIFICATION_CREATE,NOTIFICATION_VISUALIZATION,NOTIFICATION_WORKFLOW] # ONLY EXTERNAL
openIncidents: # ONLY EXTERNAL
- functionality: NOTIFICATION_CREATE # ONLY EXTERNAL
status: KO # ONLY EXTERNAL
startDate: "2019-08-24T14:15:22Z" # ONLY EXTERNAL
'400': # ONLY EXTERNAL
description: Bad request # ONLY EXTERNAL
content: # ONLY EXTERNAL
application/problem+json: # ONLY EXTERNAL
schema: # ONLY EXTERNAL
$ref: './schemas-pn-errors-v1.yaml#/components/schemas/Problem' # ONLY EXTERNAL
###########################################################################################
### INTEROP PROBING ###
###########################################################################################
"/interop/probing":
get:
summary: Recupero stato E-service PDND
description: >-
Metodo che restituisce lo stato dell'E-service di PDND interoperabilità:
- status 200 se i servizi sono correttamente funzionanti,
- status 500 se i servizi non sono correttamente funzionanti.
tags:
- interopProbing
operationId: getEserviceStatus
responses:
'200':
description: The E-service is up and running
'500':
description: A managed error has occured during the request elaboration
content:
application/problem+json:
schema:
$ref: './schemas-pn-errors-v1.yaml#/components/schemas/Problem'
###########################################################################################
### API PUBBLICHE ###
###########################################################################################
"/downtime/v1/resolved":
get:
summary: Recupero disservizi
description: >-
Metodo che restituisce l'elenco dei disservizi risolti per l'anno e il mese selezionato.
tags:
- Downtime
operationId: getResolved
x-api-cachekey-parameters:
- "method.request.querystring.year"
- "method.request.querystring.month"
parameters:
- $ref: '#/components/parameters/queryYear'
- $ref: '#/components/parameters/queryMonth'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: "./schemas-pn-components-v1.yaml#/components/schemas/PnDowntimeHistoryResponse"
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: './schemas-pn-errors-v1.yaml#/components/schemas/Problem'
###########################################################################################
### DOWNLOAD ATTI OPPONIBILI A TERZI ###
###########################################################################################
"/downtime/v1/legal-facts/{legalFactId}":
get:
summary: Ottieni atto opponibile a terzi
description: >-
Fornisce le informazioni per scaricare un atto opponibile a terzi o, se tale atto va
recuperato dagli archivi, fornisce una stima per eccesso di quanti secondi bisogna
attendere.
tags:
- Downtime
operationId: getLegalFact
x-api-cachekey-parameters:
- "method.request.path.legalFactId"
x-api-permissions:
- 'api-key-read'
- 'log-downtime-read'
parameters:
- name: legalFactId
in: path
required: true
description: Identificativo dell'atto opponibile a terzi che si vuole scaricare
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: "./schemas-pn-components-v1.yaml#/components/schemas/LegalFactDownloadMetadataResponse"
examples:
hot:
summary: File disponibile
value:
filename: downtime_NEW_NOTIFICATION_20221204.pdf
contentLength: 32423
url: "https://s3............com/presigned-url"
cold:
summary: File archiviato
value:
filename: downtime_NEW_NOTIFICATION_20221204.pdf
contentLength: 32423
retryAfter: 7200
'204':
description: Not signed
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: './schemas-pn-errors-v1.yaml#/components/schemas/Problem'
'404':
description: Not found
content:
application/problem+json:
schema:
$ref: './schemas-pn-errors-v1.yaml#/components/schemas/Problem'
###########################################################################################
### MODIFICA DELLO STATO ###
###########################################################################################
components:
parameters:
###########################################################################################
### PARAMETRI DI RICERCA DEI DOWNTIME ###
###########################################################################################
queryYear:
name: year
in: query
required: false
description: anno di ricerca dei disservizi risolti. Se non presente si intende l'anno corrente.
schema:
type: integer
minimum: 2023
example: 2024
queryMonth:
name: month
in: query
required: false
description: mese di ricerca dei disservizi risolti. Se non presente si intende il mese corrente.
schema:
type: integer
minimum: 1
maximum: 12
example: 3
queryFromTime:
name: fromTime
in: query
required: true
description: data/ora di inizio dell'intervallo entro cui eseguire la ricerca
schema:
type: string
format: date-time
queryToTime:
name: toTime
in: query
required: false
description: data/ora di fine dell'intervallo entro cui eseguire la ricerca
schema:
type: string
format: date-time
queryFunctionality:
name: functionality
in: query
required: false
description: funzionalità di Piattaforma Notifiche di cui elencare i disservizi
schema:
type: array
items:
$ref: './schemas-pn-components-v1.yaml#/components/schemas/PnFunctionality'
queryPage:
name: page
in: query
required: false
description: Pagina di risultati a cui il client è interessato
schema:
type: string
querySize:
name: size
in: query
required: false
description: Size della pagina di risultati a cui il client è interessato
schema:
type: string