Servizi

API

API

Endpoint di lettura

API Base Url:

dev: https://b2b-services-subscription-dev.agyo.io/api

test: https://b2b-services-subscription-test.agyo.io/api

prod: https://b2b-services-subscription.agyo.io/api

Swagger:

https://b2b-services-subscription-test.agyo.io/swagger-ui.html

API

Endpoint di scrittura

API Base Url:

dev: https://agyo-subscription-api-dev.agyo.io/api

test: https://agyo-subscription-api-test.agyo.io/api

prod: https://agyo-subscription-api-test.agyo.io/api

Swagger:

https://agyo-subscription-api-test.agyo.io/swagger-ui.html

TS Digital Insights

TS Digital Insights

TS Digital Insights

Processoflow.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://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


TEST

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-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. 

 

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

Permette di recuperare i dati specifici per il singolo kpi.

 

[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.

 

[POST] /activeService

Permette di attivare il servizio di insights.

 

[POST] /disableService

Permette di disattivare il servizio di insights.

 

[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.

{
    "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.

 

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

Permette di recuperare le info del config.

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:

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

Insights Use Case

Statistiche SDI

Insights legati alle fatture elettroniche del singolo cliente:

 

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

 

Insights Use Case

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

 

Insights Use Case

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. 

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 :

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