########################################################################## # # API DISPOSITIVI # ########################################################################## swagger: '2.0' info: title: API REST Dispositivi description: | API per l'utilizzo dei servizi di gestione e trasmissione dei Corrispettivi. Dove è utilizzato il termine `file firmato` si fa riferimento ad un file in formato xml firmato con Xml Signature conforme ad uno specifico elemento di uno schema xml dove l'elemento `Signature` contiene la firma XML. La definizione del formato della firma XML si trova in http://www.w3.org/TR/xmldsig-core/. La firma XML è profilata per facilitare l'interoperabilità, in particolare: - all'interno dell'elemento `Signature` non è presente l'elemento opzionale `Object` - all'interno dell'elemento `SignedInfo` è presente un unico elemento `Reference` che identifica l'intero documento (URI="") - viene utilizzato unicamente l'algoritmo di canonicalizzazione `http://www.w3.org/TR/2001/REC-xml-c14n-20010315` come definito in http://www.w3.org/TR/xml-c14n - viene utilizzato unicamente l'algoritmo di firma `http://www.w3.org/2001/04/xmldsig-more#rsa-sha256` come definito in http://www.w3.org/TR/xmldsig-core/ - viene utilizzato unicamente l'algoritmo di hash `http://www.w3.org/2001/04/xmlenc#sha256` come definito in http://www.w3.org/TR/xmlenc-core/ - la trasformazione da applicare in fase di generazione della firma è quella definita in http://www.w3.org/TR/xmldsig-core/ come `http://www.w3.org/2000/09/xmldsig#envelopedsignature` - l'elemento `KeyInfo` contiene unicamente il certificato della chiave di firma version: "3.0" # the domain of the service host: api.corrispettivi.agenziaentrate.gov.it # array of all schemes that your API supports schemes: - https # will be prefixed to all paths basePath: /v1 paths: ################################################################################ # # DISPOSITIVI # ################################################################################ /dispositivi/: post: summary: Richiesta generazione del certificato per il dispositivo. description: | Richiede il certificato del dispositivo ed effettua il suo censimento, per l'invio è necessario inviare un file firmato conforme all'elemento `RichiestaCertificatoDispositivo` dello schema XSD `CorrispettiviMessaggiType_1.0.xsd`. Per ottenere il certificato è necessario richiamare il servizio fino alla restituzione del codice http 201 ed il certificato in formato X.509. In caso di errore fare riferimento alla Tabella 1 dell'`Allegato - Code List`. Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: * consumes: - application/xml * produces: - application/xml consumes: - application/xml produces: - application/xml parameters: # - $ref: "#/parameters/IdentificativoProduttore" - in: body name: richiestaCertificatoDispositivo required: true description: certificato dispositivo schema: type: string format: binary description: | File xml conforme all'elemento `RichiestaCertificatoDispositivo` dello schema XSD `CorrispettiviMessaggiType_1.0.xsd` firmato utilizzando la XML Signature con il certificato di firma del produttore e contenente la CSR (Certificate Signing Request). La CSR dovrà avere nel CN l'identificativo univoco del dispositivo responses: 201: description: | Generazione certificato completata. schema: type: string format: binary description: | Restituisce un file xml firmato con il certificato del sistema conforme all'elemento `EsitoRichiestaCertificatoDispositivo` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo operazione e il certificato X.509 202: description: | Generazione certificato in corso. 403: description: Dispositivo non autorizzato alla richiesta default: description: Errore non previsto 406: description: Parametri di input non validi schema: type: string format: binary description: | Restituisce un file xml firmato con il certificato del sistema conforme all'elemento `EsitoRichiestaCertificatoDispositivo` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 409: description: Certificato già cesinto schema: type: string format: binary description: | Restituisce un file xml firmato con il certificato del sistema conforme all'elemento `EsitoRichiestaCertificatoDispositivo` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 415: description: Il valore del content-type non è quello atteso 429: description: Superato il numero massimo di chiamate nell'unità di tempo put: summary: Attivazione del dispositivo. description: | Attiva il dispositivo associandolo al gestore, con il dettaglio del verificatore che ha effettuato l'operazione. Il file è un xml firmato col certificato del dispositivo e conforme all'elemento `AttivaDispositivo` dello schema XSD `CorrispettiviMessaggiType_1.0.xsd`. In caso di errore fare riferimento alla Tabella 2 dell'`Allegato - Code List`. Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: * consumes: - application/xml * produces: - application/xml consumes: - application/xml produces: - application/xml parameters: # - $ref: "#/parameters/IdentificativoDisp" - name: attivaDispositivo in: body description: dati attivazione required: true schema: type: string format: binary description: | File xml firmato con il certificato del dispositovo conforme all'elemento `AttivaDispositivo` dello schema XSD `CorrispettiviMessaggiType_1.0.xsd` responses: 200: description: | Attivazione eseguita. schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione 403: description: Dispositivo non autorizzato alla richiesta default: description: Errore non previsto 406: description: Parametri di input non validi schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 409: description: Dispositivo non attivabile schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 415: description: Il valore del content-type non è quello atteso /dispositivi/corrispettivi/: post: summary: Invio dei corrispettivi. description: | Trasmette un file xml firmato con il certificato di firma del dispositivo conforme all'elemento `DatiCorrispettivi` dello schema XSD `CorrispettiviType_1.0.xsd`. In caso di errore fare riferimento alla Tabella 3 dell'`Allegato - Code List`. Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: * consumes: - application/xml * produces: - application/xml consumes: - application/xml produces: - application/xml parameters: # - $ref: "#/parameters/IdentificativoDisp" - name: datiCorrispettivi in: body required: true schema: type: string format: binary description: | File xml firmato con il certificato del dispositovo conforme all'elemento `DatiCorrispettivi` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo operazione responses: 200: description: | Trasmissione eseguita. schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione 403: description: Dispositivo non autorizzato alla richiesta 406: description: Parametri di input non validi schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 409: description: Dispositivo non valido schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione 415: description: Il valore del content-type non è quello atteso 429: description: Superato il numero massimo di chiamate nell'unità di tempo default: description: Errore non previsto # /dispositivi/datifatture/: # post: # summary: Invio i dati delle fatture. # description: | # Trasmette un file xml firmato con il certificato di firma del dispositivo conforme all'elemento `DatiFattura` dello schema XSD `DatiFattura_v1.0.xsd`. # # In caso di errore fare riferimento alla Tabella 1 dell'`Allegato - Code List`. # # Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: # * consumes: - application/xml # * produces: - application/xml # # consumes: # - application/xml # produces: # - application/xml # parameters: ## - $ref: "#/parameters/IdentificativoDisp" # - name: datiFatture # in: body # required: true # schema: # type: string # format: binary # description: | # File xml firmato con il certificato del dispositovo conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo operazione # responses: # 200: # description: | # Trasmissione eseguita. # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione # 403: # description: Dispositivo non autorizzato alla richiesta # 406: # description: Parametri di input non validi # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati # 409: # description: Dispositivo non valido # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione # 415: # description: Il valore del content-type non è quello atteso # 429: # description: Superato il numero massimo di chiamate nell'unità di tempo # default: # description: Errore non previsto # # /dispositivi/scontrini/: # post: # summary: Invio gli scontrini parlanti. # description: | # Trasmette un file xml firmato con il certificato di firma del dispositivo conforme all'elemento `Scontrino` dello schema XSD `ScontriniType_v1.0.xsd`. # # In caso di errore fare riferimento alla Tabella 5 dell'`Allegato - Code List`. # # Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: # * consumes: - application/xml # * produces: - application/xml # # produces: # - application/xml # consumes: # - application/xml # parameters: # - $ref: "#/parameters/IdentificativoDisp" # - name: datiFatture # in: body # required: true # schema: # type: string # format: binary # description: | # File xml firmato con il certificato del dispositovo conforme all'elemento `Scontrino` dello schema `ScontriniType_v1.0.xsd` contenente l'identificativo operazione # responses: # 200: # description: | # Trasmissione eseguita. # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione # 403: # description: Dispositivo non autorizzato alla richiesta # 406: # description: Parametri di input non validi # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati # 409: # description: Dispositivo non valido # schema: # type: string # format: binary # description: | # Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione # 415: # description: Il valore del content-type non è quello atteso # 429: # description: Superato il numero massimo di chiamate nell'unità di tempo # default: # description: Errore non previsto /dispositivi/evento/: put: summary: Invio di un evento da parte del dispositivo. description: | Invia un evento che modifica lo stato del dispositivo (i.e. guasto o disattivazione). Per i codici relativi alle tipologie di evento fare riferimento alla Tabella 6 dell'`Allegato - Code List`. Per specificare il dettaglio dell'evento segnalato fare riferimento alla Tabella 7 dell'`Allegato - Code List`. In caso di errore fare riferimento alla Tabella 8 dell'`Allegato - Code List`. Assicurarsi che i valori relativi al content-type siano conformi a quanto previsto: * consumes: - application/xml * produces: - application/xml consumes: - application/xml produces: - application/xml parameters: # - $ref: "#/parameters/IdentificativoDisp" - name: eventoDispositivo in: body required: true schema: type: string format: binary description: | File xml firmato con il certificato del dispositovo conforme all'elemento `EventoDispositivo` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo operazione responses: 200: description: anomalia registrata schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente il dettaglio degli errori riscontrati 403: description: Dispositivo non autorizzato alla richiesta default: description: Errore non previsto 409: description: Dispositivo non valido schema: type: string format: binary description: | Il file xml resituito è firmato con il certificato del sistema e conforme all'elemento `EsitoOperazione` dello schema `CorrispettiviMessaggiType_1.0.xsd` contenente l'identificativo dell'operazione 415: description: Il valore del content-type non è quello atteso