# Servizi # API # Endpoint di lettura ##### API Base Url: dev: [https://b2b-services-subscription-dev.agyo.io/api](https://b2b-services-subscription-test.agyo.io/swagger-ui.html) test: [https://b2b-services-subscription-test.agyo.io/api](https://b2b-services-subscription-test.agyo.io/swagger-ui.html) prod: [https://b2b-services-subscription.agyo.io/api](https://b2b-services-subscription-test.agyo.io/swagger-ui.html) ##### Swagger: [https://b2b-services-subscription-test.agyo.io/swagger-ui.html](https://b2b-services-subscription-test.agyo.io/swagger-ui.html) # Endpoint di scrittura ##### API Base Url: dev: [https://agyo-subscription-api-dev.agyo.io/api](https://agyo-subscription-api-test.agyo.io/swagger-ui.html) test: [https://agyo-subscription-api-test.agyo.io/api](https://agyo-subscription-api-test.agyo.io/swagger-ui.html) prod: [https://agyo-subscription-api-test.agyo.io/api](https://agyo-subscription-api-test.agyo.io/swagger-ui.html) ##### Swagger: [https://agyo-subscription-api-test.agyo.io/swagger-ui.html](https://agyo-subscription-api-test.agyo.io/swagger-ui.html) # TS Digital Insights # TS Digital Insights ### Processo![flow.png](https://digital-docs.ts-paas.com/uploads/images/gallery/2023-05/scaled-1680-/5zGfz3yugnx41hK9-flow.png) Il flusso per utilizzare il servizio di **INSIGHTS** parte dalla firma del contratto, per far ciò dal FE viene chiamato il servizio **Insights-api** e tramite la chiamata **signContratct** viene recuperato il template(**ONE\_PLATFORM\_INSIGHT**) del contratto per dare i consensi, vengono aggiunti i check sulle clausole e il tutto poi viene inviato ad L-CMS che si occupa di tenere una copia del contratto firmato e viene inviata una mail all'utente che riepiloga il contratto firmato. Una volta firmato il contratto viene chiamata l'api di attivazione del servizio **activeService** che scatena tutta la serie di eventi per far si che il servizio sia correttamente attivo e venga notificato il **datalake** di questa attivazione per iniziare a processare i dati dell'azienda così da poter calcolare gli insights. ## Endpoint ##### DEV

[https://insights-api-dev.agyo.io/swagger](https://insights-api-dev.agyo.io/swagger) [https://ts-digital-insights-config-write-dev.agyo.io/swagger-ui/index.html](https://ts-digital-insights-config-write-dev.agyo.io/swagger-ui/index.html) [https://ts-digital-insights-config-read-dev.agyo.io/swagger-ui/index.html](https://ts-digital-insights-config-read-dev.agyo.io/swagger-ui/index.html#/)

##### TEST

[https://insights-api-test.agyo.io/swagger](https://insights-api-test.agyo.io/swagger) [https://ts-digital-insights-config-write-test.agyo.io/swagger-ui/index.html](https://ts-digital-insights-config-write-test.agyo.io/swagger-ui/index.html) [https://ts-digital-insights-config-read-test.agyo.io/swagger-ui/index.html](https://ts-digital-insights-config-read-test.agyo.io/swagger-ui/index.html)

##### PROD

## Api #### Insights-api \*opzionale ---

\[GET\] /getCardList/{itemId}

Permette di recuperare la lista delle card di insights. - `itemId` identificativo uuid dell'azienda. ---

\[GET\] /getKpiData/{kpiName}/{itemId}

Permette di recuperare i dati specifici per il singolo kpi. - `kpiName` nome del kpi per cui si vuole recuperare i dati. - `itemId` identificativo uuid dell'azienda. ---

\[POST\] /signContract

Permette di firmare il contratto per dare il consenso di trattare i dati di un azienda ai fine di poterli usare per analytics. - `itemId` identificativo uuid dell'azienda. - `userId` identificativo uuid dell'utente che sta firmando il contratto per conto dell'azienda. ---

\[POST\] /activeService

Permette di attivare il servizio di insights. - `ownerId` identificativo uuid dell'azienda owner del pacchetto. - `itemId` identificativo uuid dell'azienda. ---

\[POST\] /disableService

Permette di disattivare il servizio di insights. - `ownerId` \* identificativo uuid dell'azienda owner del pacchetto. - `itemId` identificativo uuid dell'azienda. ---

\[GET\] /getStatus/{itemId}/{ownerId}

Permette di recuperare le informazioni sul pacchetto di insights per una singola azienda. Con il parametro `infoServiceName` si possono recuperare dei conteggi aggiuntivi sul pacchetto. - `ownerId` identificativo uuid dell'azienda owner del pacchetto. - `itemId` identificativo uuid dell'azienda. - `infoServiceName` \* valori possibili: - **CARD\_NUMBER** permette di recuperare il numero di insights disponibili. - **SALES\_INFO** permette di recuperare l'incremento % di fatture ricevute e inviate rispetto l'anno precedente. ```JSON { "configInfo": { "id": 4, "itemId": "e6e530cc-8f98-4fc1-9017-cda412b51497", "ownerId": "e6e530cc-8f98-4fc1-9017-cda412b51497", "createdAt": "2023-04-20T13:22:18.947+00:00", "createdBy": "c34b9996-fb3f-4378-a9e5-fb180d8a5db9-WEBHOOK-INVOKER-INSIGHTS", "updatedAt": "2023-04-20T13:22:18.947+00:00", "updatedBy": "c34b9996-fb3f-4378-a9e5-fb180d8a5db9-WEBHOOK-INVOKER-INSIGHTS", "active": true, "readonly": false, "flows": [ { "id": 4, "configId": 4, "flowId": "EIP", "createdAt": "2023-04-20T13:22:18.959+00:00", "createdBy": "c34b9996-fb3f-4378-a9e5-fb180d8a5db9-WEBHOOK-INVOKER-INSIGHTS", "updatedAt": "2023-04-20T13:22:18.959+00:00", "updatedBy": "c34b9996-fb3f-4378-a9e5-fb180d8a5db9-WEBHOOK-INVOKER-INSIGHTS", "active": true } ] }, "status": "ACTIVE", "infoService": [ { "name": "cardNumber", "value": 7, "type": "number" } ] } ``` --- #### Ts-digital-insights-config-read --- ---

\[GET\] /api/v1/flows

Permette di recuperare la lista dei flussi disponibili. ---

\[GET\] /api/v1/flows/{flowId}

Permette di recuperare le informazioni di un singolo flusso. - `flowId` identificativo uuid dell'azienda. ---

\[GET\] /api/v1/config/{itemId}/{ownerId}

Permette di recuperare le info del config. - `ownerId` identificativo uuid dell'azienda owner del pacchetto. - `itemId` identificativo uuid dell'azienda. --- #### Ts-digital-insights-config-write --- ## Flussi Il servizio digital Insights una volta attivo permette di configurare differenti flussi su cui è configurato il servizio come ad esempio:

flow\_id (identificativo del flusso)	flow description
EIP	Digital Invoice
FLOW\_2
FLOW\_3

Esistono dei flussi che vengono attivati automaticamente all'attivazione del servizio. ## Flussi di Notifica Tramite il config è possibile configurare per ogni flusso una lista di endpoint a cui notificare l'attivazione del flusso di digital Insights. L'endpoint del servizio a cui il config dovrà inviare la notifica deve essere sviluppato nel seguente modo:

Protocollo	REST
Metodo	POST
Autenticazione	Bearer JWT
Body della richiesta per notifiche sui flussi	{ "flowId": "String", "itemId": "String", "ownerId": "String", "action": "ENABLE\_FLOW/DISABLE\_FLOW", }

Di seguito è presente una descrizione dei parametri passati nel body: - **flowId**: identificativo del flusso (es EIP per fatturazione) - **itemId**: azienda su cui è stato attivato il flusso - **ownerId**: azienda che paga il servizio Digital Insights Gli endpoint messi a disposizione dovranno essere idempotenti, quindi dovranno gestire potenziali chiamate doppie (in caso di eventuali errori del sistema) . Gli endpoint dovranno restituire le seguenti risposte

Status Code	Body
200/202	{ "message":"" }
400/401/404/406/412/500/502	{ "code": "string", "timeStamp": "2021-07-08T13:13:12.223Z", "message": "string" }

**\[documentazione parziale, ancora in fase di sviluppo\]** # Insights Use Case Use Case di Insights disponibili # Statistiche SDI Insights legati alle fatture elettroniche del singolo cliente: ![](https://digital-docs.ts-paas.com/uploads/images/gallery/2023-08/ArWVvP4ro3Kko9Gg-embedded-image-puunjqmi.png) Datalake calculation: I kpi da calcolare (rispettivamente anno in corso e anno precedente) in data lake sono: Numero fatture elettroniche (un campo per le attive e un campo per le passive). Valore fatture elettroniche (sia attive che passive), valore proveniente dalle linee. Vengono considerati le condizioni per il calcolo del fatturato (vedi condizioni sotto). Analytics model converter: Per l’insights «Fatture emesse»: somma del «TotaleFattureAttiveAnnoInCorso» per i mesi di competenza dell’anno in corso Per l’insights «Fatture ricevute »: somma del «TotaleFatturePassiveAnnoInCorso» per i mesi di competenza dell’anno in corso Per la «media mensile fatture emesse» : «TotaleFattureAttiveAnnoInCorso» diviso il numero dei mesi di competenza Per la «media mensile fatture ricevute» : «TotaleFatturePassiveAnnoInCorso» diviso il numero dei mesi di competenza Condizioni per il calcolo del fatturato:

Ciclo attivo (active = true)	Flusso	Stato	Stato Dalake	Tipo documento	Formula di calcolo	Formula di calcolo TD07, TD08, TD09
	SDIPA	ACCETTATA (PA) ACCETTATA PER DECORENZA TERMINI (PA)	ACCETTATO NESSUNA\_RISPOSTA IN\_GESTIONE	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26)	-Sommatoria degli imponibili di tutte le linee ( 2.2.1.11 <PrezzoTotale>) tranne TD04 \- per TD04 fare la sommatoria di tutte le linee (2.2.1.11 <PrezzoTotale>, questa sommatoria è da considerare in valore assoluto (togliere quindi l'eventuale segno "-") e da sottrarre alla stessa sommatoria degli altri tipi documento	- sommatoria 2.2.2 <Importo> - 2.2.3.1 <Imposta> Oppure 2.2.2 <Importo> / \[1+( 2.2.3.2 <Aliquota>/100)\] (i tag 2.2.3.1 e 2.2.2 sono alternativi) -TD08 (nota credito) va considerata in valore assoluto e sottratta al fatturato
	SDIPR	EMESSA (PR)	INVIATO	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD27	idem
	AUTOINVIO / SELFSEND	AUTO INVIATA	AUTO\_INVIATO	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario TD26), TD27	idem

Ciclo passivo (active=false)	Flusso	Stato	Stato Dalake	Tipo documento	Formula di calcolo	Formula di calcolo TD07, TD08, TD09
	SDIPA	ACCETTATA (PA) ACCETTATA PER DECORENZA TERMINI (PA)	ACCETTATO NESSUNA\_RISPOSTA A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	-Sommatoria degli imponibili di tutte le linee ( 2.2.1.11 <PrezzoTotale>) + sommatoria 2.1.1.7.3 <ImportoContributoCassa> tranne TD04 \- per TD04 fare la sommatoria di tutte le linee (2.2.1.11 <PrezzoTotale>) + sommatoria 2.1.1.7.3 <ImportoContributoCassa>, considerarla in valore assoluto (togliere quindi l'eventuale segno "-") e sottrarlo alla stessa sommatoria degli altri tipi documento	- sommatoria 2.2.2 <Importo> - 2.2.3.1 <Imposta> Oppure 2.2.2 <Importo> / \[1+( 2.2.3.2 <Aliquota>/100)\] (i tag 2.2.3.1 e 2.2.2 sono alternativi) -TD08 (nota credito) va considerata in valore assoluto e sottratta al fatturato
	SDIPR	RICEVUTA	A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	idem
	AUTOINVIO / SELFSEND	RICEVUTA	A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	idem

# KPI Green

KPI Green sono degli indicatori legati al potenziale risparmio dovuto all'utilizzo della fatturazione elettronica e alla rinuncia a stampare le fatture. Si tratta risparmio calcolato in termini di Alberi (numero) , Acqua (litri) e Co2 (kg).

Datalake Calculation:

Calcolato direttamente su synapse, con i dati dei consumi, utilizzando vista vw_greenDigitalBox e la funzione udf_greenDigitalBox e scritto su tabella api.greendigitalbox.

Al fine di arricchire i dati con gli ulteriori filtri è stata scritta su sql anche l'anagrafica.

Per ogni partita IVA e mese vengono calcolati i seguenti indicatori moltiplicando i parametri per #alberi, litri acqua e kg CO2 per la somma del numero di fatture:

SUM([Nfatture]) * 0,00026944 [RisparmioAlberi]

SUM([Nfatture]) * 0,88721574 [RisparmioAcqua]

SUM([Nfatture]) * 0,0224532 [RisparmioCO2]

Viene inoltre filtrato il dato per i consumi delle **fatture attive**

Il dato viene salvato nella tabella sql api.greenDigitalBox

Parametri utilizzati per il calcolo:

Fattura (#)	1
Numero di fogli (per fattura)	3
Alberi (#)	0,00026944
Acqua (litri)	0,88721574
CO2 (kg)	0,0224532

# Incassi e pagamenti da fatture elettroniche Si tratta di un Insights basato sulle fatture elettroniche del singolo cliente in cui, attraverso la lettura della data scadenza del singolo documento, si calcolano gli incassi e pagamenti previsti nei successivi 6 mesi rispetto alla data di riferimento. Oltre al calcolo degli incassi e pagamenti (raggruppati per mese) viene fornito al cliente la differenza tra incassi e pagamenti a livello mensile ma anche a livello cumulato, suggerendo inoltre l'andamento generale dei successivi 6 mesi attraverso un messaggio testuale sintetico. ![](https://digital-docs.ts-paas.com/uploads/images/gallery/2023-08/hxHIx6mynZ13wnII-embedded-image-0jfoke47.png) **Perimetro**: \- Selezione clienti sottoscriventi \- Filtro temporale sulla tabella \[dati pagamento\] delle fatture che hanno \[data scadenza pagamento\] tra oggi (incluso) e i prossimi 12 mesi o Il dato grezzo deriva da \[fattura elettronica header\]; vengono selezionati i codici fiscali del cedente prestatore e i codici fiscali del cessionario committente, oltre all’importo pagamento. Quest’ultimo viene diviso per il tasso di cambio recuperato dalle API di Banca d’Italia. Il campo utilizzato per recuperare la valuta della fattura è il campo \[divisa\] dalla tabella \[dati generali\]. o Con i dati così recuperati vengono calcolate le somme delle fatture attive e passive per mese e le cumulate sui 12 mesi; dove il dato è mancante viene messo di default il valore 0. Il calcolo è stato eseguito seguendo l’algoritmo allegato. o In base ai valori appena selezionati vengono calcolati i flag di alert mensile, cumulato e annuale Definizione data scadenza : - Per definire la data della scadenza considerare il campo 2.4.2.5 <DataScadenzaPagamento> \- se 2.4.2.5 <DataScadenzaPagamento> non è compilato riportiamo la data del documento contenuta nel campo 2.1.1.3 <Data> Condizioni :

Ciclo attivo (active = true)	Flusso	Stato	Stato Dalake	Tipo documento	Formula di calcolo	Formula di calcolo TD07, TD08, TD09
	SDIPA	ACCETTATA (PA) ACCETTATA PER DECORENZA TERMINI (PA)	ACCETTATO NESSUNA\_RISPOSTA IN\_GESTIONE	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26)	-Sommatoria degli imponibili di tutte le linee ( 2.2.1.11 <PrezzoTotale>) tranne TD04 \- per TD04 fare la sommatoria di tutte le linee (2.2.1.11 <PrezzoTotale>, questa sommatoria è da considerare in valore assoluto (togliere quindi l'eventuale segno "-") e da sottrarre alla stessa sommatoria degli altri tipi documento	- sommatoria 2.2.2 <Importo> - 2.2.3.1 <Imposta> Oppure 2.2.2 <Importo> / \[1+( 2.2.3.2 <Aliquota>/100)\] (i tag 2.2.3.1 e 2.2.2 sono alternativi) -TD08 (nota credito) va considerata in valore assoluto e sottratta al fatturato
	SDIPR	EMESSA (PR)	INVIATO	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD27	idem
	AUTOINVIO / SELFSEND	AUTO INVIATA	AUTO\_INVIATO	TD01, TD02, TD03, TD04, TD05, TD06, TD24, TD25, TD26 (se cedente diverso da cessionario TD26), TD27	idem

Ciclo passivo (active=false)	Flusso	Stato	Stato Dalake	Tipo documento	Formula di calcolo	Formula di calcolo TD07, TD08, TD09
	SDIPA	ACCETTATA (PA) ACCETTATA PER DECORENZA TERMINI (PA)	ACCETTATO NESSUNA\_RISPOSTA A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	-Sommatoria degli imponibili di tutte le linee ( 2.2.1.11 <PrezzoTotale>) + sommatoria 2.1.1.7.3 <ImportoContributoCassa> tranne TD04 \- per TD04 fare la sommatoria di tutte le linee (2.2.1.11 <PrezzoTotale>) + sommatoria 2.1.1.7.3 <ImportoContributoCassa>, considerarla in valore assoluto (togliere quindi l'eventuale segno "-") e sottrarlo alla stessa sommatoria degli altri tipi documento	- sommatoria 2.2.2 <Importo> - 2.2.3.1 <Imposta> Oppure 2.2.2 <Importo> / \[1+( 2.2.3.2 <Aliquota>/100)\] (i tag 2.2.3.1 e 2.2.2 sono alternativi) -TD08 (nota credito) va considerata in valore assoluto e sottratta al fatturato
	SDIPR	RICEVUTA	A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	idem
	AUTOINVIO / SELFSEND	RICEVUTA	A\_DISPOSIZIONE RICEVUTO	TD01, TD02, TD03, TD04, TD05, TD06, TD20, TD24, TD25, TD26 (se cedente diverso da cessionario solo per TD26), TD28	idem