Core

Il componente principale, il core, è ovviamente il frutto del lavoro dei primi anni di sviluppo della piattaforma, ed assolve ai compiti principali della stessa:

1. Definizione e organizzazione dei Servizi Digitali

2. Definizione dei Moduli on-line

3. Gestione delle Pratiche inviate dai cittadini e dei messaggi

4. Gestione degli utenti

5. Gestione Uffici e appuntamenti on-line su slot di tempo e orari di apertura.

6. Gestione Sale pubbliche e altre risorse a prenotazione flessibile

Il core assolve anche al compito di interfaccia utente, sia per i cittadini che per gli operatori e gli amministratori degli Enti.

Il core è costituito dai seguenti microservizi:

• Caddy / Symfony App (dal 2023 i due servizi sono distribuiti in una immagine unica: registry.gitlab.com/opencontent/stanza-del-cittadino/core/app) Nota

• Form Server, implementazione del server di Form.IO: registry.gitlab.com/opencontent/stanza-del-cittadino/form-server

• Form Builder, un editor multi-tenant con accesso riservato agli amministratori della piattaforma per l'editing dei componenti condivisi dei form degli Enti: registry.gitlab.com/opencontent/stanza-del-cittadino/formbuilderjs

• Varnish, un cache proxy server che incrementa l'affidabilità e la scalabilità del formserver e del catalogo dei servizi: registry.gitlab.com/opencontent/varnish:latest

• Gotenberg, a Docker-powered stateless API for PDF files: gotenberg/gotenberg:7

• Payment Updates, ascolta gli eventi relativi ai pagamenti e aggiorna le pratiche di conseguenza: registry.gitlab.com/opencontent/stanza-del-cittadino/payment-updater

• Signature Check, api usata dal componente sdc_upload di form.io per validate le firme dei documenti firmati .p7m: geopartner/signcheckwebapi:latest

Per un esempio completo di deploy dei microservizi si veda il file docker-compose.yml nel repositoy del core, che fornisce una configurazione funzionante della piattaforma.

Utilizza inoltre i seguenti servizi di persistenza:

• PostgreSQL, per la gestione di tutti i dati e delle configurazioni della piattaforma, ad eccezione delle form. La versione usata in sviluppo è la 11 e comprende anche l'estensione PostGIS: postgis/postgis:11-3.3-alpine

• MongoDB, per la persistenza dei moduli realizzati con l'editor di Form.IO: mongo:4.2

• Redis, per la gestione delle sessioni degli utenti e della cache applicativa: redis:5-alpine.

Per ulteriori dettagli si veda https://gitlab.com/groups/opencity-labs/-/milestones

La piattaforma può offrire sia una esperienza completa al cittadino o all'impresa, che consente l'invio di pratiche e la loro gestione nel backend, sia farsi carico di uno solo di questi aspetti, lasciando ad altri sistemi il ruolo di interfaccia con il cittadino o a sistemi verticali il compito di gestire pratiche (pratiche edilizie o in ambito sociale)

In presenza di questa esigenza è importante che la piattaforma e il sistema terzo siano in grado di instaurare e mantenere nel tempo la relazione tra le pratiche, mantenere aggiornati lo stato della pratica o di un pagamento pendente per la stessa.

Vari strumenti nella piattaforma consentono di mantenere aggiornate le informazioni e ricevere aggiornamenti:

1. API ReST

2. Webhook

Prima di entrare nei dettagli di questi strumenti merita avere uno sguardo di insieme del flusso della pratica e di tutti gli stati che può attraversare. Nel grafico che segue il tratto continuo più forte rappresenta il flusso più frequente di una pratica, il tratto punteggiato rappresenta i flussi alternativi. I cerchi costituiscono gli stati finali di una pratica

Per una visione generale di tutti gli stati che una pratica può assumere e quali sono i cambi di stato ammessi segue un grafico più generale. Nel grafico sono evidenziati in azzurro gli stati fondamentali della pratica, mentre in grigio gli stati deprecati.

La piattaforma OpenCity Italia semplifica la realizzazione e la gestione di servizi digitali per cittadini e imprese, anche da smartphone (art. 7 CAD).

OpenCity Italia è open source, scaricabile da Developers Italia o disponibile come servizio pronto all'uso (Software as a Service).

La piattaforma è sviluppata con l'obiettivo di erogare servizi per centinaia di Enti contemporaneamente da una singola installazione, per questo motivo il codice della piattaforma è organizzato in microservizi indipendenti tra loro e il dialogo tra gli stessi è realizzato mediante stream di eventi piuttosto che mediante chiamate dirette alle API.

Per queste scelte l'installazione e la gestione della piattaforma in un ambiente di produzione richiede un ampio ventaglio di conoscenze:

• Sistema Operativo GNU/Linux e uso della command line (CLI)

• database PostgresQL, MongoDB, Redis

• Docker e sistemi di orchestrazione di container

• Kafka e KsqlDB

Per contribuire alla piattaforma, a seconda dell'area su cui si desidera sviluppare sono necessarie cometenze nei seguenti linguaggi di programmazione:

• PHP

• NodeJS

• Python

• Golang

Infine la piattaforma è in costante evoluzione e nuovi componenti vengono aggiunti o prendono il posto di componenti esistenti divenuti obsoleti.

Ogni servizio è autonomo e deve implementa una singola funzionalità all'interno di un contesto delimitato. Un contesto delimitato è una divisione naturale all'interno di un Ente e fornisce un limite esplicito all'interno del quale esiste un modello di dominio.

Ogni microservizio della piattaforma è distribuito come docker container, ha un proprio versionamento ed espone una o più porte per comunicare con l'esterno.

I microservizi sono esposti all'esterno da un web router che assolve solitamente anche il ruolo di terminatore di SSL.

Ad ogni release della piattaforma vengono aggiornati uno o più microservizi.

Streaming eventi: gli eventi vengono scritti in un log. Gli eventi sono rigorosamente ordinati (in una partizione) e durevoli. I client non sottoscrivono il flusso, ma un client può invece leggere da qualsiasi parte del flusso. Il client è responsabile di far avanzare la propria posizione nel flusso. Questo significa che un client può aggiungersi in qualsiasi momento e può riprodurre gli eventi.

Elaborazione del flusso di eventi. Usare una piattaforma di flussi di dati come Apache Kafka, come pipeline per inserire gli eventi e fornirli agli elaboratori di flussi. Gli elaboratori di flussi intervengono per elaborare o trasformare il flusso. Possono essere presenti più elaboratori di flussi per sottosistemi diversi nell'applicazione.

Introduzione

L’area personale di OpenCity Italia è progettata per integrarsi con vari intermediari di pagamento utilizzati da Comuni ed enti pubblici. Questa sezione descrive i requisiti tecnici necessari per sviluppare e implementare l'integrazione tra la piattaforma e l'intermediario di pagamento PagoPA.

Le interazioni avvengono in seguito ad alcune azioni da parte dei cittadini e degli operatori:

• Invio di una pratica da parte del cittadino

• Approvazione di una pratica da parte di un operatore nel caso di un pagamento posticipato

• Importazione di dovuti da parte dell'operatore mediante API file csv

• Pagamento di un dovuto da parte del cittadino a seguito dell'importazione di quest'ultimo

Requisiti Generali

Per sviluppare l'integrazione con l'intermediario di pagamento PagoPA, sono richiesti i seguenti elementi:

• Documentazione Tecnica: Manuali, guide e riferimenti API.

• Endpoint/Ambiente di Test: URL degli endpoint e accesso a un ambiente di test per effettuare chiamate API.

• Modalità di Verifica dello Stato del Pagamento: Specifiche delle modalità di verifica dello stato del pagamento, tramite polling o notifica.

Dettagli Tecnici dell'Integrazione

Per integrare OpenCity Italia Area Personale con l’intermediario di PagoPA, sono necessari i seguenti parametri minimi:

Creazione di un Pagamento

• Parametri per la creazione di un pagamento

• Parametri per la creazione di una Marca da Bollo Digitale

• Restituzione del numero IUV e/o del numero avviso in fase di creazione del pagamento

Scaricamento Documenti

• Parametri per scaricare l’avviso di pagamento cartaceo

• Parametri per scaricare la ricevuta telematica una volta effettuato il pagamento

Dovuto

• API per il download degli importi dovuti (se disponibile)

Specifiche delle API

L’intermediario di pagamento deve fornire documentazione dettagliata delle API, comprensiva di:

• Endpoint

• Metodi supportati (GET, POST, etc.)

• Parametri richiesti e facoltativi

• Formato dei dati (JSON, XML)

• Esempi di richieste e risposte

Configurazione di Rete

Per garantire le comunicazioni fra la piattaforma e l’intermediario di pagamento, è necessario sbloccare gli IP delle chiamate entranti verso gli endpoint dell’intermediario di pagamento. Gli IP di OpenCity da sbloccare sono:

• 93.41.234.251/32

• 78.47.94.152/32

• 54.220.150.231/32

• 63.33.155.248/32

• 37.186.144.203/32

Supporto Tecnico

Per risolvere eventuali complicazioni, errori o bug durante l'integrazione, è fondamentale avere un contatto tecnico dedicato. Si prega di fornire i seguenti dettagli del contatto tecnico:

• Nome

• Email

• Telefono

• Disponibilità (orari di lavoro)

Event fields

Producers

Nella piattaforma si fa ampio uso del Pattern Event Sourcing è quindi fondamentale che il formato degli eventi sia stabile e documentato.

Per ogni evento i producers DEVONO inserire sempre i seguenti dati:

Attenzione: se si genera un evento, a partire da un evento esistente, si sta creando una nuova entità che avrà i propri valori event_id, event_created_at, event_version, app_id: non si deve mai ricopiare questi valori dall'evento originario.

Consumers

I consumatori devono essere sempre attenti alla versione di eventi che supportano: la versione deve essere esplicitamente supportata ed eventi di una versione non supportata devono essere scartati

Nei log è possibile dare evidenza del fatto che si è incontrato un evento non supportato, ma non va loggato come errore è sufficiente dare l'informazione a livello DEBUG. In condizioni normali un servizio che consuma eventi emette una riga di log a livello INFO se e solo se ha gestito l'evento e ha fatto qualcosa con quell'evento che ha avuto successo.

Standard Date

Le date vanno sempre espresse nello standard ISO8601, in particolare, le date non devono contenere i millisecondi, e devono contenere il formato della timezone Europe/Rome. Le letter T e Z DEVONO essere espresse in maiuscolo.

Es: 2022-06-22T15:11:20+02:00

API Standards

Facciamo in generale riferimento alle linee guida di Zalando, tenendo ovviamente in considerazione anche i requisiti e le raccomandazioni delle Linee Guida di Interoperabilità della PA.

• i servizi DEVONO agire solo su verbi HTTP supportati, rispettarne la semantica, restituire errore sugli altri.

• i metodi DELETE, GET, HEAD, OPTIONS, PUT, TRACE devono essere idempotenti (vd anche RFC7231)

• le API hanno path al plurale sulle collezioni, per separare le parole si usa il kebab-case (il trattino).

• nelle risposte le URL dovrebbero essere sempre espresse in modo assoluto

POST    /tenants
GET     /tenants/{tenant_id}
PUT     /tenants/{tenant_id}
PATCH   /tenants/{tenant_id}
DELETE  /tenants/{tenant_id}

GET

• Le collezioni devono essere facilmente navigabili, per questo abbiamo adottato il seguente standard:

{
    "meta": {
        "page": {
            "offset": 5000,
            "limit": 20,
            "sort": "creationTime"
        },
        "total": 46561
    },
    "links": {
        "self": "http..../items?offset=5000&limit=20&sort=creationTime",
        "prev": "http..../items?offset=4980&limit=20&sort=creationTime",
        "next": "http..../items?offset=5020&limit=20&sort=creationTime"
    },
    "data": [
        { "id": "..." },
        { "id": "..." },
        { "id": "..." }
    ]
}

Pagination

• Le GET sulle risorse devono USARE laddove supportati i query parameters convenzionali:

• sort

• offset

• limit

• cursor

• embed

• q

• fields

Pagination/2

• Su alcuni campi è utile implementare anche l'opzione di paginazione cursor-based:

GET /payments?created_since=$timeStamp

error handling

{ 
    "errors": [
        {
            "type": "/errors/incorrect-user-pass",
            "title": "Incorrect username or password.",
            "status": 401,                                         (optional)
            "detail": "Authentication failed due to incorrect username or password.",
            "instance": "/login/log/abc123"                        (optional)
        },
        ...
    ]
}

Fare riferimento alla RFC 7807

Tutti i servizi devono rispettare i 12factor, descritti in modo anche più dettagliato nell'articolo An illustrated guide to 12 Factor Apps

Packaging

Quello che ci si aspetta è che si possa usare il docker-compose.yml scaricandolo direttamente sul proprio pc, possibilmente senza necessità di clonare tutto il repository.

• Dockerfile e docker-compose.yml devono essere presenti nella root del repo (.dockerignore se serve) per facilitare l'avvio in locale dell'applicativo e farne saggiare l'utilizzo; Perché sia pienamente usabile è necessario che le immagini facciano riferimento al registry pubblico (nostro o meno).

• usare un docker-compose.dev.yml per aggiungere tool utili per lavorare in locale durante lo sviluppo.

Per esempio la chiave "build" per le immagini create deve essere presente nel file ".dev" e non nel file compose principale.

In questo modo scaricando il repository e rinominando il file .dev in docker-compose.override.yml ci si mette nelle condizioni ideali per sviluppare il servizio e un docker-compose up comporterà automaticamente l'uso in cascata dei file docker-compose.yml e docker-compose.override.yml.Per ulteriori dettagli consultare il manuale di Docker: Merge compose files.

Terminazione pulita

• il servizio deve gestire correttamente i segnali inviati da docker SIGTERM e SIGKILL per fare uno shutdown pulito e senza interrompere l'esecuzione in fasi critiche per la consistenza dei dati.

Configurazione

• la configurazione *deve avvenire mediante variabili d'ambiente

• la configurazione può essere fatta anche tramite un file di environment (.env) o parametri da cli

Healthcheck

• se http, deve essere presente un /status entrypoint che risponde 200 se va tutto bene, uno status code diverso in caso contrario

• se non http, l'healthcheck può essere un controllo su un file o su un processo

• l'health check, se disponibile, deve essere inserito nel Dockerfile

Logging

Vanno tenute sempre in considerazione le raccomandazioni implementative di Agid, espresse nell'Allegato 4 alle Linee Guida di Interoperabilità.

• Il log deve supportare almeno tre livelli: debug, info e error. Una gestione matura comprende 6 livelli distinti di log

• Non mi schiare log http e log multiriga (stacktrace o similari): se si è costretti, per esempio inviare lo stacktrace a stderr e riservare stdout ai log a singola riga

• Se possibile implementare log in formato json, ma solo se si può produrre solo del JSON, mischiare testo semplice e JSON non è di grande utilità. Non è altrettanto utile annegare del json dentro un altro json: per esempio quando si logga che l'applicativo ha mandato un certo json in un certo topic di kafka... per avere il json completo si può vedere dentro kafka, nel log è sufficiente inserire l'id dell'evento.

• Sul contenuto:

  • DEVE esserci l'istante della comunicazione in formato UTC (RFC 3339) e con separatori Z e T in maiuscolo.

  • DEVE contenere la URI o l'identificazione dell'operazione che si sta eseguendo o il nome dell'evento ricevuto.

  • Dovrebbe contenere la tipologia della chiamata, ad esempio il verbo HTTP o se si tratta di una chiamata fatta da CLI o in un azione batch.

  • DEVE contenere l'esito della chiamata

  • Se è una chiamata fatta da un client DEVE essere inserito l'IP sorgente della chiamata (attenzione a rispettare eventuali header X-FORWARDED-XXX)

  • Se è una chiamata fatta per conto di un essere umano è possibile inserire un riferimento all'utente, ma NON DEVE contenere dati personali in chiaro (il codice fiscale ad esempio deve essere troncato al mssimo alle prime 7 lettere). Per avere un riferimento certo inserire lo userid della piattaforma.

  • Se disponibile DEVE inserire l'identificatore unico della chiamata o dell'evento (event_id).

• All'inizio della sua esecuzione ogni servizio DEVE loggare il proprio avvio dichiarando anche la versione del servizio e l'environment in cui sta girando: boat-qa, boat-prod, local, etc...

Monitoring errors

• Il microservizio DEVE integrare Sentry per il monitoraggio centralizzato degli errori.

• Una volta operativa l'integrazione è necessario:

  • abilitare l'integrazione con sentry sul repo gitlab

  • inserire regole di allerta per quel microservizio, se le regole esistenti non sono sufficienti

Monitoring metrics

• se http, deve esistere l'entrypoint /metrics che espone metriche in formato prometheus.

• un servizio può mostrare metriche sulle chiamate (status code, timing), anche se solitamente le possiamo prendere altrove (traefik), - un servizio deve mostrare metriche specifiche dell'app, in particolare delle condizioni di errore (counters) e dei tempi di risposta di eventuali servizi esterni richiamati da questo (histograms).

• il servizio NON deve mostrare metriche che derivano ad esempio da errori 404, perché i bot che scansionano tutte le URL provocano infinite varianti che comportano la creazione di infinite metriche di errore

Cron

• sui sistemi di deploy e orchestrazione che usiamo ci sono sempre dei modi di eseguire task stile cron, inutile reimplementare quella logica dentro la propria App.

• è indispensabile invece rendere il proprio software idempotente: deve essere rieseguibile più volte sugli stessi dati senza fare danno.

• il modo più semplice per implementare una chiamata a tempo è implementare un comando da cli che possa essere eseguito con la stessa immagine con cui gira l'applicativo.Questo applicativo viene poi schedulato nel nostro ambiente di produzione istruendo il nostro clustered cron. Per istruzioni sulla configurazione si rimanda alla documentazione di crazymax-cronjob.

Parametri e file di configurazione

• in docker c'e' sempre un mapping tra esterno e interno, inutile parametrizzare questi aspetti in modo particolarmente flessibile: il controllo sul filesystem interno è sempre in mano allo sviluppatore del microservizio, quindi si può sempre usare un path interno del tipo /data senza preoccuparsi tanto del fatto che all'esterno quel path diventerà qualcosa come /srv/data/qualcosa/altro/data.

• Per le configurazioni e' importante usare sempre lo strumento configs di docker swarm, senza ricorrere al volume mapping.

• Analogamente per le credenziali o le parti segrete DEVE essere usato lo strumento dei secrets.

Continuous Integration

• Ogni progetto può inserire nella CI attività di linting del codice e enforcemente dei coding styles

• Ogni progetto DEVE includere la CI condivisa, nel seguente modo:

  Copy

  stages:
   - build
   - test
   - deploy  # dummy stage to follow the template guidelines
   - review
   - dast
   - staging
   - canary
   - production
   - incremental rollout 10%
   - incremental rollout 25%
   - incremental rollout 50%
   - incremental rollout 100%
   - performance
   - cleanup
  
  include:
    - project: 'opencity-labs/product'
      ref: main
      file: '.gitlab/ci/devops.yml'`

• Eventuali step di test devono essere inclusi dopo questo snippet di codice e devono sfruttare la fase di build già eseguite, per esempio se viene fatta la build di un binario la si può sfruttare negli step successivi mediante un artifact.

• La durata della CI non DEVE mai superare i 15 minuti e non dovrebbe mai superare i 5: questo perché soprattutto in condizioni di emergenza, fare un hotfix non può richiedere troppo tempo, è necessario che ogni step sia ben ottimizzato per ottenere questo scopo, per esempio sfruttando le build multi-stage di docker o la cache di Gitlab CI.

• in caso di pubblicazione su Developers Italia, la correttezza del public-code.yml deve essere testato con:

  Copy

  publiccode:
    stage: test
    allow_failure: false
    image:
      name: italia/publiccode-parser-go
      entrypoint: [""]
    script:
      - publiccode-parser /dev/stdin < publiccode.yml
    only:
      - master

La piattaforma consente la creazione di servizi contenenti pagamenti. I pagamenti possono essere in forma di bolli, che non richiedono una integrazione con un sistema esterno (il cittadino registra soltanto i numeri di marche da bollo che ha acquistato in precedenza), o in forma di pagamento PagoPA.

I pagamenti PagoPA vengono creati e aggiornati mediante l'integrazione con uno degli intermediari di pagamento di PagoPA.

JSON Evento Pagamento

{
  "id": "68dada78-2398-4a11-b80a-98aaede3371c",
  "user_id": "5b00796e-ef10-4c98-b9f5-b0f7ffd7a17d",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "b21c4429-95e4-45d5-930f-44eb74136625",
  "created_at": "2023-06-06T11:59:11+02:00",
  "updated_at": "2023-06-12T00:10:16+02:00",
  "status": "PAYMENT_STARTED",
  "reason": "79501b2a-c9ad-41f8-a9e7-a885f2d570a2 - BNRMHL75C06G702B",
  "remote_id": "79501b2a-c9ad-41f8-a9e7-a885f2d570a2",
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-09-04T11:59:05+02:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": "001550000000024427",
    "iud": "68dada7823984a11b80a98aaede3371c",
    "iuv": "550000000024427",
    "split": null
  },
  "links": {
    "online_payment_begin": {
      "url": "https://iris-proxy-qa.boat.opencontent.io/online-payment/68dada78-2398-4a11-b80a-98aaede3371c?gw=https://iristest.rete.toscana.it/gateway/PaymentAuthentication?token=1686045553436001U132&expire_at=2023-06-06T12:13:13",
      "last_opened_at": "2023-06-06T11:59:26+02:00",
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune-qa.bugliano.pi.it/lang/it/pratiche/79501b2a-c9ad-41f8-a9e7-a885f2d570a2/detail",
      "last_opened_at": "2023-06-06T11:59:57+02:00",
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://iris-proxy-qa.boat.opencontent.io/notice/68dada78-2398-4a11-b80a-98aaede3371c",
      "last_opened_at": "2023-06-06T11:59:20+02:00",
      "method": "GET"
    },
    "receipt": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune-qa.bugliano.pi.it/lang/api/applications/79501b2a-c9ad-41f8-a9e7-a885f2d570a2/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://iris-proxy-qa.boat-backplane.opencontent.io/update/68dada78-2398-4a11-b80a-98aaede3371c",
      "last_check_at": "2023-06-12T00:10:16+02:00",
      "next_check_at": "2023-06-12T01:10:16+02:00",
      "method": "GET"
    }
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "e0b25e33-9d38-4781-823a-ed04753aea01",
  "event_version": "1.0",
  "event_created_at": "2023-06-12T00:10:16+02:00",
  "app_id": "iris-payment-proxy-qa:1.2.8"
}

Validazione campi

Payment

PaymentData

Links

UrlData

Notify

Update

Payer

Il documento è in fase di stesura, le informazioni in esso contenuto, i protocolli e i jsonSchema possono subire variazioni anche importanti.

La nostra piattaforma permette al cittadino di interagire sia con le pratiche generate sulla piattaforma stessa sia con pratiche generate su altri gestionali. Cittadini e Operatori potranno, da un'unica interfaccia, interagire con un elenco uniforme di pratiche.

Per realizzare questa integrazione è stato ideato il concetto di Pratiche Lite, che rappresenta una pratica con un set minimo di dati, necessari a visualizzare e interagire correttamente l'elenco delle pratiche agli utenti a differenza delle Pratiche che nascono all'interno della piattaforma che contengono tutti i dati delle pratiche. Ma non solo, è possibile visualizzare anche informazioni relative ai documenti correlati alla pratica e i pagamenti.

Sarà necessario fornirci un elenco di Pratiche Lite per esporle sulla nostra piattaforma. Questi dati potranno essere forniti tramite API ReST in formato JSON, oppure mediante file CSV.

I vantaggi dell'integrazione con l'area personale

Integrare le pratiche generare da altri gestionali nell'area personale permette al cittadino di:

• consultare in un unico posto tutte le pratiche relative a un cittadino, anche se generate da altri sistemi;

• seguire l'iter della pratica

• consultare i dati essenziali di una pratica, come il richiedente e il beneficiario;

• consultare i documenti associati alla pratica e lo stato della protocollazione;

• consultare i pagamenti associati alla pratica;

• dialogare con gli operatori mediante la funzione messaggi dell'Area personale.

Ma l'area personale non è solo consultazione, il cittadino, se l'integrazione lo prevede, potrà comunque interagire con le pratiche, anche se generate da sistemi esterni. Operazioni come la visualizzazione completa della pratica, la modifica, l'integrazione dei documenti o l'annullamento della richiesta, saranno eseguite direttamente sul gestionale esterno, invocando gli opportuni endpoint HTTP corrispondenti alle azioni da eseguire. Questi endpoint verranno specificati pratica per pratica all'atto dell'importazione, se non specificati

Modello della Pratica Lite

Questa è una rappresentazione schematica dei dati che è possibile inviare:

• Pratica: titolo e stato della pratica

  • Richiedente: nome, cognome, codice fiscale e contatti del richiedente

  • Beneficiario : nome, cognome, codice fiscale e contatti del beneficiario

  • Servizio: servizio collegato alla pratica

  • Endpoint delle azioni: endpoint http delle azioni eseguibili sulla pratica

• Documenti: documenti collegati alla pratica e stato di protocollazione

• Pagamenti: pagamenti collegati alla pratica

Nei capitoli seguente verranno mostrati i tracciati dettagliati di import.

Stati della Pratica Lite

Il seguente diagramma mostra i possibili stati in cui può trovarsi una pratica:

• Bozza: in questo stato la pratica non è considerata ancora completamente compilata e può essere modificabile

• Inviata: la pratica è stata compilata in ogni sua parte da cittadino e definitivamente inviata. In questo stato non è più possibile modificare i dati delle pratica

• Presa in carico: la pratica è stata presa in carico da un Operatore, il quale effettuerà le normali operazioni d'ufficio necessarie a gestirla

• In attesa di integrazione: l'operatore ha richiesto di integrare la pratica con informazioni e/o documenti mancanti. La pratica resta in questo stato fino a quando non si ottiene una risposta dal Cittadino

• Rifiutata: la pratica non è stata accettata dall'operatore che l'ha gestita

• Ritirata: la pratica è stata ritirata dal cittadino prima che l'ufficio si sia pronunciata

• Annullata: quando l'ufficio definisce che non si procederà ulteriormente con la pratica e non si pronuncerà su ulteriore approvazione o rifiuto

Modalità di integrazione

Supportiamo tre modalità di integrazione:

Modalità push tramite API: è possibile inviarci tramite apposita API i dati delle pratiche per inserire nuove pratiche o per aggiornarne lo stato. Questa modalità di aggiornamento è utile per mantenere costantemente aggiornati i dati delle pratiche tra due sistemi, avendo quindi modifiche immediate per il cittadino. Questa modalità garantisce la possibilità di creare un dialogo col cittadino.

Modalità di invio massivo (batch): permette di importare una grande quantità di dati ad ogni invocazione ma non garantisce l'esecuzione in tempo reale. È utile sopratutto per le prime importazioni, o in tutti quei casi in cui non ho necessità di avere uno stato aggiornato in tempo reale. È possibile fornire i dati nei formati CSV o JSON.

Modalità polling: il sistema esterno espone un API da invocare a scadenza regolare che permette al nostro sistema di recuperare gli aggiornamenti. Fondamentale che API dia la possibilità di recuperare gli aggiornamenti incorsi in un intervallo di tempo

Autenticazione

Per effettuare un'importazione è necessario autenticarsi ed ottenere un token di autenticazione

È possibile seguire questa guida per le istruzioni di autenticazione https://docs.opencityitalia.it/developers/integrazioni/integrazioni-con-il-flusso-delle-pratiche/api-rest

Autenticazione standard nel modello 1 e 2

Modello 3: basic auth, client certificate, api key

Import di una pratica tramite API

Questa è la rotta per effettuar il singolo import di Pratica, Documenti e Pagamenti

POST /api/v1/application-lite/import
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{ vedi tracciato di import }

Come è possibile vedere dal tracciato riportato nel paragrafo successivo, è possibile inviare in un solo colpo i dati relativi a pratiche, documenti e pagamenti. Questi tre elementi si considerano correlati tra di loro, quindi, documenti e pagamenti, si intendono relativi alla pratica inviata e verranno relazionati a essa.

Flusso di import delle pratiche (applications)

Le pratiche verranno identificate in maniera univoca dal campo external_id che rappresenta un identificativo del sistema sorgente, se non presente, verrà creata con i dati passati.

La riconciliazione di richiedente e beneficiario (applicant e beneficiary) verrà effettuata basandosi sul codice fiscale (tax_code). Se nel sistema esiste già un utente con quel codice fiscale, verranno utilizzati i dati già presente nel database ignorando i dati di nome, cognome e contatti che vengono passati. Al contrario, se non presenti, verrà importato un nuovo utente con i dati specificati.

Lo stato della pratica segue il flusso definito nei capitoli precedenti, tuttavia non è stato implementato un controllo stringente sul flusso della pratica, in controllo dello stato della pratica è demandato al sistema sorgente.

Lo stato della pratica regola però le azioni che il cittadino potrà effettuare. Nella sezione links è possibile specificare le azioni permesse sulla pratica è l'URL da invocare al click del cittadino. Se una specifica azione non è specificata non verrà proposta al cittadino. Le azioni verranno proposte al cittadino anche in base allo stato della pratica, per esempio, una pratica in stato inviata non può più essere modificata, quindi, anche se indicata l'azione MODIFY, non verrà comunque proposta.

Tracciato di import

{
  "application": {
    "external_id": "EXT123456",
    "subject": "Richiesta Contributo Startup",
    "applicant": {
      "given_name": "Mario",
      "family_name": "Rossi",
      "identifiers": {
        "tax_code": "RSSMRA85M01H501Z"
      },
      "contacts": {
        "mobile": "+393331234567",
        "email": "mario.rossi@example.com",
        "pec": "mario.rossi@pec.example.com"
      }
    },
    "beneficiary": {
      "given_name": "Luca",
      "family_name": "Bianchi",
      "identifiers": {
        "tax_code": "BNCGLC85M01H501Z"
      },
      "contacts": {
        "phone": "+390612345678",
        "email": "luca.bianchi@example.com"
      }
    },
    "status": 2000,
    "service": {
      "id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "actions": [
      {
        "action": "view",
        "url": "https://sitoweb/other-path?do=view"
      },
      {
        "action": "request_integration",
        "url": "https://sitoweb/other-path?do=request_integration"
      }
    ]
  },
  "documents": [
    {
      "external_id": "00000000-1111-2222-3333-0334ecfb527d",
      "title": "Richiesta: REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
      "description": "REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
      "short_description": "REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
      "folder": "Comunicazione Inizio Lavori-Saverio MMMSSS98D29H123T",
      "has_organization": null,
      "main_document": "https://localhost/comune-di-bugliano/lang/api/applications/00000000-1111-2222-3333-b167c5038be3/attachments/00000000-1111-2222-3333-50413d60ff4e?version=1",
      "registration_data_date": "2024-10-04T14:35:15+02:00",
      "registration_data_document_number": null,
      "registration_data_transmission_type": "Inbound",
      "type": "application-request",
      "valid_from": null,
      "valid_to": null
    }
  ]
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "application": {
      "type": "object",
      "properties": {
        "external_id": {
          "type": "string",
          "description": "Identificativo pratica sul sistema esterno",
          "minLength": 1
        },
        "subject": {
          "type": "string",
          "description": "Oggetto della pratica",
          "minLength": 3,
          "maxLength": 255
        },
        "applicant": {
          "$ref": "#/definitions/person",
          "description": "Richiedente della pratica"
        },
        "beneficiary": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/definitions/person"
            }
          ],
          "description": "Beneficiario della pratica"
        },
        "status": {
          "type": "integer",
          "description": "Stato della pratica. Valori possibili: 2000 (Inviata), 4000 (Presa in carico), 4200 (In attesa di integrazioni), 7000 (Approvata), 9000 (Rifiutata), 20000 (Ritirata), 50000 (Annullata)",
          "enum": [
            2000,
            4000,
            4200,
            7000,
            9000,
            20000,
            50000
          ]
        },
        "service": {
          "type": "object",
          "description": "Servizio correlato alla pratica",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
              "description": "Identificativo interno del servizio"
            }
          },
          "required": [
            "id"
          ]
        },
        "actions": {
          "type": "array",
          "description": "Azioni che è possibile effettuare sulla Pratica con relativo URL",
          "items": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "description": "Azione associata al link (es. view, request integration)",
                "enum": [
                  "view",
                  "request_integration"
                ]
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "URL per accedere alla risorsa"
              }
            },
            "required": [
              "action",
              "url"
            ]
          }
        }
      },
      "required": [
        "external_id",
        "subject",
        "applicant",
        "status",
        "service",
        "actions"
      ]
    }
  },
  "required": [
    "application"
  ],
  "definitions": {
    "person": {
      "type": "object",
      "properties": {
        "given_name": {
          "type": "string",
          "description": "Nome della persona"
        },
        "family_name": {
          "type": "string",
          "description": "Cognome della persona"
        },
        "identifiers": {
          "type": "object",
          "description": "Sistemi di identificazione digitale della persona (attualmente supportiamo solo il codice fiscale)",
          "properties": {
            "tax_code": {
              "type": "string",
              "description": "Codice fiscale",
              "minLength": 16,
              "maxLength": 16
            },
            "spid_code": {
              "type": "string",
              "description": "Codice SPID"
            },
            "id_eidas": {
              "type": "string",
              "description": "Codice eIDAS"
            },
            "anpr_id": {
              "type": "string",
              "description": "Codice unico dell'anagrafe"
            },
            "inps_id": {
              "type": "string",
              "description": "Codice INPS"
            },
            "io_wallet_id": {
              "type": "string",
              "description": "Codice di PagoPA"
            },
            "email": {
              "type": "string",
              "description": "Email se usata come identificativo utente"
            }
          },
          "required": [
            "tax_code"
          ],
          "anyOf": [
            {
              "required": [
                "tax_code"
              ]
            },
            {
              "required": [
                "spid_code"
              ]
            },
            {
              "required": [
                "id_eidas"
              ]
            },
            {
              "required": [
                "anpr_id"
              ]
            },
            {
              "required": [
                "inps_id"
              ]
            },
            {
              "required": [
                "io_wallet_id"
              ]
            },
            {
              "required": [
                "email"
              ]
            }
          ]
        },
        "contacts": {
          "type": "object",
          "properties": {
            "mobile": {
              "type": "string",
              "description": "Numero di cellulare"
            },
            "phone": {
              "type": "string",
              "description": "Numero di telefono"
            },
            "email": {
              "type": "string",
              "description": "Email"
            },
            "pec": {
              "type": "string",
              "description": "PEC"
            }
          }
        }
      },
      "required": [
        "given_name",
        "family_name",
        "identifiers"
      ]
    }
  }
}

Gestione dello stato

Il seguente endpoint serve per il cambio di stato di una pratica lite. Permette opzionalmente di inviare un messaggio al richiedente contestualmente al cambio stato

POST /api/v1/application-lite/{id}/status
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{ 
    "new_status": 3000,
    "message": "Messaggio da inviare al richiedente al relativo al cambio stato"
}

Le API non sono sufficienti per realizzare una buona integrazione tra due sistemi. Se due o più sistemi si devono aggiornare reciprocamente in base agli eventi che avvengono al proprio interno, è necessario che periodicamente ogni sistema interroghi gli altri per sapere se il loro stato è cambiato: questo approccio si chiama anche polling. Questo è molto oneroso e introduce un ritardo nell'aggiornamento che è tanto maggiore quanto maggiore è l'intervallo con cui un sistema interroga gli altri. D'altra parte se di intensifica la frequenza del polling si avranno maggiori costi a fronte di aggiornamenti magari poco frequenti.

Un modo più efficiente di far dialogare due sistemi è avviare una comunicazione in occasione di cambiamenti rilevanti per il sistema in ascolto e per ottenere questo, eliminando del tutto la necessità di fare polling, è possibile usare i Webhook.

Ogni webhook consente di inviare un aggiornamento a una API di un altro sistema che sta ascolto, in base agli eventi che si desidera comunicare.

Per fare test sui webhook si consiglia di utilizzare un servizio come Request Inspector.

Una API ReST, nota anche come API RESTful, è un'interfaccia di programmazione delle applicazioni (API o API web) conforme ai vincoli dello stile architetturale ReST, che consente l'interazione con servizi web RESTful. Il termine REST, coniato dall'informatico Roy Fielding, è l'acronimo di REpresentational State Transfer.

La documentazione delle API ReST della piattaforma è pubblicamente disponibile in ogni Ente all'indirizzo:

Ad esempio per il comune demo della piattaforma è possibile consultarle alla pagina:

Autenticazione

Alcune API richiedono un'autenticazione prima di essere chiamate, in questo caso un cittadino o un operatore possono usare le proprie credenziali per ottenere un token di autenticazione come segue:

Richiesta token di autenticazione

POST https://servizi.comune.bugliano.pi.it/lang/api/auth

Con questa chiamata si riceve un token di autenticazione in formato JWT, che dovrà essere inviato per tutte le successive chiamate che richiedono autenticazione come bearer token nell'header Autorization

Request Body

Alcuni esempi di chiamate

Esempio di chiamata da linea di comando con il client Httpie:

echo '{ "username": "my-api-user", "password": "xxxx" }' | \
http post https://servizi.comune.bugliano.pi.it/lang/api/auth

Esempio di chiamata da linea di comando con il client curl:

curl \
--header 'Content-Type: application/json' \
--data $'{\n "username": "my-api-user",\n "password": "xxxx"\n}' \
https://servizi.comune.bugliano.pi.it/lang/api/auth 

Versioni delle API

Le API sono disponibili in due versioni, la "1" e la "2". Le capacità delle API sono le stesse per le due versioni, nella versione 2 c'e' una migliore gestione del formato JSON, quindi si consiglia l'uso della versione più recente.

È possibile specificare la versione delle Api che si vanno ad interrogare, questo è possibile in 2 modi differenti:

• tramite parametro version da passare come parametro delle GET

• tramite parametro X-Accept-Version da specificare nell' header della richiesta

La versione di default è per retrocompatibilità la 1

Dalla versione 2 le chiavi dei valori del campo data delle applications non sono più restituite come un insieme di strighe piatto separato dal punto (.) ma come campo json con le chiavi esplose.

Nota bene: si raccomanda di specificare sempre la versione di API utilizzata, anche se è il default (1), perche' in futuro il default potrebbe cambiare.

Creazione di un pagamento

Un pagamento nasce da una interazione con il cittadino: il cittadino presenta una pratica per la quale l'Ente richiede un pagamento.

Il cuore dell'integrazione con un intermediario di pagamento è un microservizio apposito che dialoga con l'intermediario da un lato, implementando le chiamate specifiche in protocollo ReST o SOAP, e con il core della piattaforma dall'altro lato, mediante la lettura e la scrittura su un topic di Kafka.

Componenti coinvolte

Componenti del core della piattaforma

In questo momento i pagamenti hanno una relazione 1 a 1 con le pratiche, di conseguenza ci sono due servizi che fanno da intermediari tra le pratiche e i pagamenti, ovvero il payment dispatcher e il payment updater.

Core

È l’interfaccia dalla quale l’utente usufruisce di un servizio digitale, inserendo i dati di una pratica attraverso un modulo: se il servizio prevede un pagamento, i dati di questo sono presenti nella descrizione JSON della pratica e saranno utilizzati dal dispatcher per creare il pagamento.

Payment dispatcher

È il microservizio che, a partire dall'evento di una pratica nel topic applications, crea l'evento del pagamento nel topic payments.

Payment dispatcher API

È il microservizio che sostituirà il Payment Dispatcher, esso, anziche leggere l'evento di una pratica dal topic applications, esporrà un API che, quando chiamata, crea l'evento del pagamento nel topic payments. Questo permette di avere una soluzione unica per gestire tutti i flussi di pagamento della piattaforma, quindi sia pagamenti creati a partire dalle pratiche, che i pagamenti importati tramite csv o API esterne.

Payment updater

Il microservizio legge gli eventi dal topic payments e contestualmente aggiorna lo stato della pratica cambiando lo stato da Payment pending a Inviata.

Sottosistema dei pagamenti

Payment proxy

E' il microservizio che gestisce la comunicazione e l’aggiornamento della posizione debitoria con l'Intermediario di pagamento di riferimento. Esso gestisce inoltre il salvataggio delle configurazioni tramite le quali può interagire con l'intermediario di pagamento di riferimento. Queste configurazioni sono inserite dall'operatore mediante l'interfaccia del Core, il quale comunica con il payment proxy mediante delle apposite API che quest'ultimo serve.

Ksql

E' un microservizio che ascolta dal topic payments e crea un database interrogabile con SQL contenente tutti i pagamenti in stati non definitivi.

Payments poller

E' il microservizio che monitora lo stato dei pagamenti: periodicamente legge su KSQL l'elenco dei pagamenti aperti e invia per ognuno di questi una chiamata alla "update.url" specificata nel pagamento stesso: questa url è una url del proxy stesso che consente al proxy di interrogare l'Intermediario per avere lo stato aggiornato del pagamento.

Checkout pagoPA API

Questo microservizio si occupa di centralizzare il pagamento online dei dovuti in un'unica API, ovvero quella del checkout di pagoPA, in questo modo si astrae dall'intermediario con cui ci si deve integrare facilitando quindi lo sviluppo dell'integrazione e omogeneizzando l'esperienza di pagamento del cittadino, che diventa quindi indipendente dall'intermediario tramite qui andrà a pagare.

Panoramica

La configurazione dei pagamenti avviene interrogando delle API apposite fornite dal proxy di riferimento. Quest'ultimo fornisce inoltre un form come json schema sviluppato con form.io mediante il quale l'utente inserisce tali configurazioni.

Per creare un form utilizzare il seguente builder:

Aggiornamenti principali rispetto alla versione 1.0

NOTA 1: per gli sviluppatori python è stata definita una libreria a cui fare riferimento per la validazione del nuovo evento, è consultabile .

NOTA 2: per gli sviluppatori python, il repository da cui prendere spunto per applicare le modifiche riportate in questa sezione e in quelle successive è consultabile .

Arricchimento della descrizione del pagamento

Con la versione 2.0 aggiornata del pagamento sono stati aggiunti nuovi campi che arricchiscono la descrizione del pagamento, in particolare i campi sono:

• type: serve a distinguere tra un pagamento ordinario e una marca da bollo digitale, può avere PAGOPA o STAMP come valori

• receiver: definisce il beneficiario del pagamento, non è un campo obbligatorio ma può essere utilizzato nel caso di pagamenti con beneficiario differente dall'ente su cui viene creato il pagamento. Se viene valorizzato è obbligatorio valorizzare i campi receiver.tax_identification_number e receiver.name

• due_type: indica la categorizzazione del dovuto sull'intermediario di pagamento, e viene valorizzato dalla configurazione del pagamento

• pagopa_category: indica la categorizzazione del dovuto su pagoPA, e viene valorizzato dalla configurazione del pagamento

• document: è un campo che serve a descrivere il documento su cui viene apposta la marca da bollo digitale, se viene valorizzato è obbligatorio valorizzare il campo document.hash .

• split: con la versione 2.0 dell'evento, questo campo, che viene alimentato dal bilancio contenuto nella configurazione del pagamento, avrà un tipo ben definito, composto da

  • split.code: indica l'identificativo della voce di bilancio

  • split.amount: indica l'importo della voce di bilancio

  • split.meta: oggetto contenente il resto dei campi presenti nella voce di bilancio

• links.confirm: è un campo che serve a contenere l'API per forzare il completamento di un pagamento, per il momento tutti i proxy mancano di questa API, ma il campo è stato aggiunto per utilizzi futuri.

• links.cancel: è un campo che serve a contenere l'API per forzare l'annullamento di un pagamento.

• debtor: in aggiunta al payer è stato aggiunto un campo equivalente debtor, e serve a distinguere tra il debitore e il pagatore di un pagamento, ad esempio è possibile che un cittadino paghi per conto di terzi e in questo caso e debitore e pagatore sono distinti. Per ora non viene valorizzato né utilizzato.

Nota importante

• payment.reason

• payment.payment.amount

• payment.payment.expire_at

• payment.payment.receiver

In sintesi quindi: se questi campi sono valorizzati nell'evento payment, allora li si legge da lì, altrimenti li si legge dalla configurazione inserita via API.

JSON Evento Pagamento

{
  "id": "68dada78-2398-4a11-b80a-98aaede3371c",
  "user_id": "5b00796e-ef10-4c98-b9f5-b0f7ffd7a17d",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "b21c4429-95e4-45d5-930f-44eb74136625",
  "created_at": "2023-06-06T11:59:11+02:00",
  "updated_at": "2023-06-12T00:10:16+02:00",
  "status": "PAYMENT_STARTED",
  "reason": "79501b2a-c9ad-41f8-a9e7-a885f2d570a2 - BNRMHL75C06G702B",
  "remote_id": "79501b2a-c9ad-41f8-a9e7-a885f2d570a2",
  "payment": {
    "type": "PAGOPA",
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-09-04T11:59:05+02:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": "001550000000024427",
    "iud": "68dada7823984a11b80a98aaede3371c",
    "iuv": "550000000024427",
    "receiver": {
      "tax_identification_number": "777777777",
      "name": "Comune di BlaBla",
      "iban": "IT60X0542811101000000123456",
      "address": "Via Del Campo",
      "building_number": "12",
      "postal_code": "38022",
      "town_name": "Roma",
      "country_subdivision": "RM",
      "country": "IT",
    },
    "due_type": "TARI",
    "pagopa_category": "9/12129/TS",
    "document": null,
    "split": [
      {
        "code": "c_1",
        "amount": 1.00,
        "meta": {}
      },
      {
        "code": "c_2",
        "amount": 0.34,
        "meta": {}
      }
    ]
  },
  "links": {
    "online_payment_begin": {
      "url": "https://iris-proxy-qa.boat.opencontent.io/online-payment/68dada78-2398-4a11-b80a-98aaede3371c?gw=https://iristest.rete.toscana.it/gateway/PaymentAuthentication?token=1686045553436001U132&expire_at=2023-06-06T12:13:13",
      "last_opened_at": "2023-06-06T11:59:26+02:00",
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune-qa.bugliano.pi.it/lang/it/pratiche/79501b2a-c9ad-41f8-a9e7-a885f2d570a2/detail",
      "last_opened_at": "2023-06-06T11:59:57+02:00",
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://iris-proxy-qa.boat.opencontent.io/notice/68dada78-2398-4a11-b80a-98aaede3371c",
      "last_opened_at": "2023-06-06T11:59:20+02:00",
      "method": "GET"
    },
    "receipt": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune-qa.bugliano.pi.it/lang/api/applications/79501b2a-c9ad-41f8-a9e7-a885f2d570a2/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://iris-proxy-qa.boat-backplane.opencontent.io/update/68dada78-2398-4a11-b80a-98aaede3371c",
      "last_check_at": "2023-06-12T00:10:16+02:00",
      "next_check_at": "2023-06-12T01:10:16+02:00",
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": "PATCH"
    },
    "cancel": {
      "url": "https://api.qa.stanzadelcittadino.it/payment-proxy/mypay-trentino/payments/5f2c4be0-effb-47a9-a6dc-a972043580f3",
      "last_opened_at": null,
      "method": "PATCH"
    }
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "e0b25e33-9d38-4781-823a-ed04753aea01",
  "event_version": "2.0",
  "event_created_at": "2023-06-12T00:10:16+02:00",
  "app_id": "iris-payment-proxy-qa:1.2.8"
}

Validazione campi

Payment

PaymentData

Receiver

Document

PaymentDataSplit

Links

UrlData

Notify

Update

Payer

Debtor

Flussi

Punti aperti

1. Determinazione delle URL di ritorno: Come si gestiscono le URL di ritorno? È possibile utilizzare l'indirizzo del proxy per gestire i redirect?

2. Gestione dell'happy path del pagamento: Come gestire il percorso ideale del pagamento e cosa accade se l'utente chiude la pagina di pagamento e poi ritorna?

Configurazione Pagamento

Happy Path

Error Path

Compilazione Pratica

1. Compilazione e invio pratica: L'utente compila la pratica per il servizio e invia la richiesta al Core.

2. Verifica pagamenti: Il Core verifica se, nella fase attuale della pratica, è necessario effettuare dei pagamenti (es. pagamento anticipato o posticipato).

3. Creazione pagamenti: Il Core invia i dettagli al servizio di pagamento, che restituisce gli identificativi dei pagamenti creati. Questo passaggio è fondamentale, poiché il Core deve salvare i dettagli dei pagamenti all'interno della pratica, assicurandosi che siano coerenti con il flusso (anticipato o posticipato).

4. Restituzione della pratica: Una volta ottenuti gli ID dei pagamenti, il Core restituisce all'utente l'intera pratica aggiornata con gli identificativi.

Punti aperti:

Gestione degli errori nella creazione dei pagamenti:

• Cosa accade se la creazione di un pagamento fallisce?

  • Il personale dell'ufficio preposto dovrebbe essere notificato in caso di fallimento.

• Stato "Creation Pending": Quando un pagamento viene creato, si ottiene comunque un ID associato al pagamento, ma questo potrebbe essere in stato di "creation pending".

• Politiche di retry: Si potrebbe considerare l'implementazione di politiche di retry, ma è necessario consultare il Product Manager (PM) per decidere la miglior esperienza utente (UX).

  Ipotesi: Al secondo o terzo tentativo di retry (o dopo un timeout di 10 secondi), potremmo mostrare un messaggio d'errore all'utente, suggerendo di riprovare o di avvisare l'assistenza (es. con un link "Clicca qui e avvisa"). Questo sarebbe un errore a livello ERROR.

• Errore di configurazione: Se si verifica un errore di configurazione errata, è possibile fare affidamento sui messaggi restituiti dall'intermediario. In questo caso, si può evitare il retry e notificare direttamente il responsabile (es. Lorello). Questo tipo di errore potrebbe essere classificato come FATAL.

Happy Path

Error Path - Creazione Pagamenti

Il sequence diagram sopra riportato rappresenta il flusso di creazione e gestione dei pagamenti in un'applicazione, con particolare attenzione al retry in caso di fallimento e alla gestione dello stato del pagamento. Il flusso si svolge come segue:

1. Inizio del processo: L'utente invia la pratica e il Core richiama il Payment Dispatcher API per creare il pagamento. Se la creazione ha successo, si procede, altrimenti si ritenta fino a 3 volte.

2. Attesa di aggiornamenti dal Read Model: Quando la creazione del pagamento va a buon fine, il Core si mette in attesa di aggiornamenti dal Read Model.

3. Retry gestito dal Retry Orchestrator: Se il Read Model restituisce lo stato CREATION_FAILED, il Core delega il processo di retry al Retry Orchestrator, che gestisce i retry tramite Kafka. Il Retry Orchestrator tenterà di risolvere il problema creando il pagamento sull'intermediario esterno.

4. Risultati del Retry Orchestrator:

   • Se il retry riesce, il Retry Orchestrator segnalerà il successo al Core, che mostrerà all'utente lo stato PAYMENT_PENDING per procedere con il pagamento.

   • Se i retry falliscono, l'utente riceverà un alert di errore.

5. Conclusione: L'utente vedrà le informazioni di pagamento in caso di successo o un messaggio d'errore in caso di fallimento, dopo aver superato il numero massimo di tentativi.

Error Path - Creazione Carrello Pagamenti

• Gestione di pagamenti parziali: Se due pagamenti vanno a buon fine e uno fallisce, come dovrebbe comportarsi il frontend? Attualmente, il processo di checkout potrebbe risultare incompleto.

• Invio degli ID di pagamento: Durante il checkout, il sistema riceve tutti gli ID dei pagamenti che devono essere completati in un’unica operazione.

Creazione pagamento posticipato da operatore

Il sequence diagram sopra riportato rappresenta il flusso di creazione e gestione dei pagamenti posticipati in fase approvazione della pratica da parte dell'operatore. Il flusso si svolge come segue:

1. Creazione delle configurazioni: L'utente modifica e invia le configurazioni, che vengono temporaneamente salvate tramite il Payment Proxy. Se fallisce, l'errore viene mostrato all'utente.

2. Creazione del pagamento tramite Payment Dispatcher: Il Core invia la richiesta di creazione pagamento al Payment Dispatcher API. Se fallisce, viene avviato un retry per un massimo di 3 tentativi. Se dopo 3 tentativi non riesce, viene mostrato un errore all'utente.

3. Attesa di aggiornamenti dal Read Model: Quando la creazione del pagamento va a buon fine, il Core si mette in attesa di aggiornamenti dal Read Model, che monitora lo stato del pagamento.

4. Stato CREATION_FAILED e Retry Orchestrator:

   • Se il Read Model restituisce lo stato CREATION_FAILED, il Core delega il retry al Retry Orchestrator, che gestisce i retry attraverso i topic di Kafka.

   • Se il Retry Orchestrator completa con successo la creazione, il Read Model aggiorna lo stato del pagamento, e l'utente può procedere con il pagamento (PAYMENT_PENDING).

   • Se anche il Retry Orchestrator fallisce dopo vari tentativi, viene restituito un errore al Core e un alert viene mostrato all'utente.

5. Output finale: Se il pagamento va a buon fine (PAYMENT_PENDING), l'utente riceve le informazioni per procedere con il pagamento. In caso di errore persistente, viene mostrato un alert.

Premessa

Essendo il sistema in questione costruito su un'architettura a eventi, è fondamentale che il payment proxy controlli la versione dell'evento Payment (campo event_version) prima di processarlo e dichiari con quale versione dell'evento quest'ultimo è compatibile. L'evento qui descritto ha versione 2.0.

Step 1

L'utente compila e invia la pratica, la quale viene inserita come evento nel topic applications

Un esempio di evento è il seguente, si faccia particolare attenzione al blocco payment_data:

{
  "app_version": "2.6.0-rc.7",
  "attachments": [],
  "authentication": {
    "authentication_method": "cps/cns",
    "certificate": "DQpSZXN1bHQgZ29lcyBoZXJlLi4uDQpCYXNlNjQNCg0KQmFzZTY0IGlzIGEgZ2VuZXJpYyB0ZXJtIGZvciBhIG51bWJlciBvZiBzaW1pbGFyIGVuY29kaW5nIHNjaGVtZXMgdGhhdCBlbmNvZGUgYmluYXJ5IGRhdGEgYnkgdHJlYXRpbmcgaXQgbnVtZXJpY2FsbHkgYW5kIHRyYW5zbGF0aW5nIGl0IGludG8gYSBiYXNlIDY0IHJlcHJlc2VudGF0aW9uLiBUaGUgQmFzZTY0IHRlcm0gb3JpZ2luYXRlcyBmcm9tIGEgc3BlY2lmaWMgTUlNRSBjb250ZW50IHRyYW5zZmVyIGVuY29kaW5nLg==",
    "certificate_issuer": "FAKE_issuerdn",
    "certificate_subject": "FAKE_subjectdn",
    "instant": "2000-01-01T00-00Z",
    "session_id": "abc123abc123abc123abc123abc123abc123abc123",
    "session_index": "abc123abc123abc123abc123abc123abc123abc123",
    "spid_code": null,
    "spid_level": null
  },
  "backoffice_data": null,
  "compiled_modules": [],
  "created_at": "2022-12-06T17:43:42+01:00",
  "creation_time": 1670345022,
  "data": {
    "applicant.data.Born.data.natoAIl": "1976-09-01T00:00:00+02:00",
    "applicant.data.Born.data.place_of_birth": "Ponte di Piave",
    "applicant.data.address.data.address": "Via Gramsci, 1",
    "applicant.data.address.data.county": "PI",
    "applicant.data.address.data.house_number": "",
    "applicant.data.address.data.municipality": "Bugliano",
    "applicant.data.address.data.postal_code": "56056",
    "applicant.data.completename.data.name": "Vittorino",
    "applicant.data.completename.data.surname": "Coliandro",
    "applicant.data.email_address": "raffaele.luccisano@opencontent.it",
    "applicant.data.fiscal_code.data.fiscal_code": "CLNVTR76P01G822Q",
    "applicant.data.gender.data.gender": "maschio",
    "payment_amount": "1,34"
  },
  "event_created_at": "2022-12-06T17:43:51+01:00",
  "event_id": "01e86cd4-8263-4ac0-a229-8cada5916eae",
  "event_version": 2,
  "flow_changed_at": "2022-12-06T17:43:51+01:00",
  "id": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e",
  "integrations": [],
  "latest_status_change_at": "2022-12-06T17:43:51+01:00",
  "latest_status_change_time": 1670345031,
  "links": [],
  "meetings": [],
  "outcome": null,
  "outcome_attachments": [],
  "outcome_file": null,
  "outcome_motivation": null,
  "outcome_protocol_document_id": null,
  "outcome_protocol_number": null,
  "outcome_protocol_numbers": null,
  "outcome_protocol_time": null,
  "outcome_protocolled_at": null,
  "path": "/applications",
  "payment_data": {
    "amount": "1.34",
    "expire_at": "2023-03-06T17:43:51+01:00",
    "landing": {
      "method": "GET",
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/detail"
    },
    "notify": {
      "method": "POST",
      "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/payment"
    },
    "reason": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e - CLNVTR76P01G822Q",
    "split": []
  },
  "payment_type": "efil",
  "protocol_document_id": null,
  "protocol_folder_code": null,
  "protocol_folder_number": null,
  "protocol_number": null,
  "protocol_numbers": [],
  "protocol_time": null,
  "protocolled_at": null,
  "service": "pagamento-immediato-efil",
  "service_group_name": null,
  "service_id": "daa0f528-b582-4d1c-9691-e226ac443424",
  "service_name": "Pagamento immediato EFIL",
  "source_type": "http",
  "status": "1500",
  "status_name": "status_payment_pending",
  "subject": null,
  "submission_time": null,
  "submitted_at": null,
  "tenant": "60e35f02-1509-408c-b101-3b1a28109329",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "timestamp": "2022-12-06T16:43:51.829146577Z",
  "user": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "user_compilation_notes": null,
  "user_name": "Vittorino Coliandro",
  "x-forwarded-for": "172.31.73.11"
}

Step 2

Il payment dispatcher legge l'evento della pratica dal topic applications, e dopo aver controllato mediante query su KSQLDB che il pagamento per tale pratica non sia già stato creato, estrae da esso i dati del pagamento, successivamente li riversa in un nuovo evento di tipo Payment e lo inserisce nel topic payments in stato CREATION_PENDING, indicando come chiave dell'evento il valore del campo service_id. Da qui in poi solo il proxy si occuperà di scrivere sul topic payments.

{
  "id": "2cc87ee5-3f57-4f20-a703-e6718c21b95b",
  "user_id": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "daa0f528-b582-4d1c-9691-e226ac443424",
  "created_at": "2022-12-06T17:43:52+01:00",
  "updated_at": "2022-12-06T17:43:52+01:00",
  "status": "CREATION_PENDING",
  "reason": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e - CLNVTR76P01G822Q",
  "remote_id": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e",
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-03-06T17:43:51+01:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": null,
    "iud": "2cc87ee53f574f20a703e6718c21b95b",
    "iuv": null,
    "receiver": null,
    "due_type": null,
    "pagopa_category": "9/12129/TS",
    "document": null,
    "split": []
  },
  "links": {
    "online_payment_begin": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/detail",
      "last_opened_at": null,
      "method": "GET"
    },
    "offline_payment": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": null,
      "last_check_at": null,
      "next_check_at": null,
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": null
    },
    "cancel": {
      "url": null
      "last_opened_at": null,
      "method": null
    }    
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "CLNVTR76P01G822Q",
    "name": "Vittorino",
    "family_name": "Coliandro",
    "street_name": "Via Gramsci, 1",
    "building_number": "",
    "postal_code": "56056",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "raffaele.luccisano@opencontent.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "c3ecf316-ca76-4bf3-ab72-26b941a5ce4f",
  "event_version": "2.0",
  "event_created_at": "2022-12-06T17:43:52+01:00",
  "app_id": "payment-dispatcher:1.1.3"
}

Step 3

Il proxy legge dal topic payments e, se ha una configurazione attiva per quel pagamento (quindi se l'evento letto ha un tenant_id e un service_id per cui ha una configurazione salvata nello storage del proxy), crea una posizione debitoria sull'Intermediario di riferimento.

Step 3 - Marca da Bollo Digitale

È possibile che la configurazione relativa al pagamento letto dal topic payments abbia configurato al suo interno una marca da bollo digitale. In tal caso, sarà necessario, per ogni marca da bollo digitale, inserire come minimo le seguenti informazioni all'interno del payload da inviare all'intermediario di pagamento con cui ci si sta integrando (in base a poi all'intermediario potrebbero essere necessari altri campi):

1. Il taglio della marca da bollo o l'importo inserito nella configurazione (per ora l'unico importo supportato è quello da 16 €)

2. La provincia di residenza del pagatore, la quale si trova nel campo payer.country_subdivision dell'evento payment

3. L'hash del documento informatico o della segnatura di protocollo cui è associata la marca da bollo digitale (per semplicità il documento in questione sarà il json dell'evento letto dal topic payments)

4. Il valore del campo reason letto dall'evento nel topic payments o, in assenza di questo, la causale della marca da bollo inserita nella configurazione

Successivamente, sarà necessario:

• Valorizzare il campo payment.amount l'importo della marca da bollo inserita in configurazione

• Valorizzare il campo payment.due_type con il tipo di dovuto inserito nella configurazione

• Valorizzare il campo payment.pagopa_category con il valore della tassonomia di pagoPA contenuta nella configurazione (se presente)

• Valorizzare il campo payment.document.hash contenente l'hash del documento informatico o della segnatura di protocollo cui è associata la marca da bollo digitale

Step 3 - Bilancio fisso

ATTENZIONE: questa struttura sarà presente solo sugli eventi payment con event_version valorizzato a 2.0 , sarà necessario dunque controllare la versione dell'evento prima di processarlo

In alcuni casi è possibile che il pagamento che il proxy deve processare presenti un bilancio fisso, ovvero un bilancio i cui importi per ogni voce sono già predeterminati a priori in fase di configurazione del servizio. In tal caso il campo split, quando letto dal proxy per la prima volta, si presenterà come un array vuoto [], il proxy dunque:

1. Leggerà il campo service_id e reperirà nel mediante esso la configurazione del servizio dentro il quale ci sono le informazioni del bilancio.

2. Utilizzerà le informazioni ricavate per popolare il payload di creazione della posizione debitoria sull'intermediario di riferimento e per arricchire l'evento appena letto con i dati del bilancio.

Esempio

Nel proxy è configurato per il servizio A il seguente bilancio

{
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": "16.00",
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    },
    {
      "split_id": "c_2",
      "split_type": "Tipo c2",
      "split_code": "Codice c2",
      "split_description": "Descrizione c12",
      "split_assessment": "0.50",
      "split_budget_chapter": "Capitolo di bilancio c2",
      "split_assessment": "Accertamento c2"
    }
  ]
}

Il bilancio da utilizzare per arricchire il campo split del pagamento sarà:

{
  "split": [
    {
      "code": "c_1",
      "amount": "16.00",
      "meta": {
        "split_type": "Tipo c1",
        "split_code": "Codice c1",
        "split_description": "Descrizione c1",
        "split_budget_chapter": "Capitolo di bilancio c1",
        "split_assessment": "Accertamento c1"
      }
    },
    {
      "code": "c_2",
      "amount": "0.50",
      "meta": {
        "split_type": "Tipo c2",
        "split_code": "Codice c2",
        "split_description": "Descrizione c12",
        "split_budget_chapter": "Capitolo di bilancio c2",
        "split_assessment": "Accertamento c2"
      }
    }
  ]
}

Step 3 - Bilancio variabile

In alcuni casi è possibile che il pagamento che il proxy deve processare presenti un bilancio variabile, ovvero un bilancio i cui importi per ogni voce vengono determinati dinamicamente a seconda del cittadino. In tal caso il campo split , quando letto dal proxy per la prima volta, si presenterà con un payload così strutturato

[
  {
    "code": "c_1",
    "amount" : "14.00",
    "meta": {}
  },
  {
    "code": "c_2",
    "amount" : "2.50",
    "meta": {}
  }
]

oppure così nel caso in cui il cittadino sia esentato dal pagamento di una certa voce del bilancio

[
  {
    "code": "c_1",
    "amount" : null,
    "meta": {}
  },
  {
    "code": "c_2",
    "amount" : "0.50",
    "meta": {}
  }
]

dove il campo code indica un identificativo interno della voce di bilancio determinato in fase di configurazione del servizio, e il campo amount indica l'importo per ogni voce di bilancio. Nel caso in cui il valore di amount sia null significa che quella riga deve essere eliminata in fase di creazione del pagamento sul gateway. Il proxy dunque:

1. Leggerà il campo service_id e reperirà mediante esso la configurazione del servizio dentro il quale ci sono le informazioni del bilancio.

2. Per ogni voce di bilancio ricavata dalla configurazione del servizio verrà sostituito l'importo con quello letto nel campo split del pagamento

3. Utilizzerà le informazioni ricavate per popolare il payload di creazione della posizione debitoria sull'intermediario di riferimento e per arricchire l'evento appena letto con i dati del bilancio.

Esempio 1

Nel proxy è configurato per il servizio A il seguente bilancio

{
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": "16.00",
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    },
    {
      "split_id": "c_2",
      "split_type": "Tipo c2",
      "split_code": "Codice c2",
      "split_description": "Descrizione c12",
      "split_assessment": "0.50",
      "split_budget_chapter": "Capitolo di bilancio c2",
      "split_assessment": "Accertamento c2"
    }
  ]
}

Nel messaggio del topic payments il campo split è valorizzato a

[
  {
    "code": "c_1",
    "amount" : "14.00",
    "meta": {}
  },
  {
    "code": "c_2",
    "amount" : "2.50",
    "meta": {}
  }
]

Il bilancio da utilizzare per arricchire il campo split del pagamento sarà:

{
  "split": [
    {
      "code": "c_1",
      "amount": "14.00",
      "meta": {
        "split_type": "Tipo c1",
        "split_code": "Codice c1",
        "split_description": "Descrizione c1",
        "split_budget_chapter": "Capitolo di bilancio c1",
        "split_assessment": "Accertamento c1"
      }
    },
    {
      "code": "c_2",
      "amount": "2.50",
      "meta": {
        "split_type": "Tipo c2",
        "split_code": "Codice c2",
        "split_description": "Descrizione c12",
        "split_budget_chapter": "Capitolo di bilancio c2",
        "split_assessment": "Accertamento c2"
      }
    }
  ]
}

Esempio 2

Nel proxy è configurato per il servizio a il seguente bilancio

{
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": "16.00",
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    },
    {
      "split_id": "c_2",
      "split_type": "Tipo c2",
      "split_code": "Codice c2",
      "split_description": "Descrizione c12",
      "split_assessment": "0.50",
      "split_budget_chapter": "Capitolo di bilancio c2",
      "split_assessment": "Accertamento c2"
    }
  ]
}

Nel messaggio del topic payments il campo split è valorizzato a

[
  {
    "code": "c_1",
    "amount" : null,
    "meta": {}
  },
  {
    "code": "c_2",
    "amount" : "0.50",
    "meta": {}
  }
]

Il bilancio da utilizzare per arricchire il campo split del pagamento sarà:

{
  "split": [
    {
      "code": "c_2",
      "amount": "0.50",
      "meta": {
        "split_type": "Tipo c2",
        "split_code": "Codice c2",
        "split_description": "Descrizione c12",
        "split_budget_chapter": "Capitolo di bilancio c2",
        "split_assessment": "Accertamento c2"
      }
    }
  ]
}

Step 4

In caso di risposta positiva:

1. Il pagamento viene passato in stato PAYMENT_PENDING modificando il campo status,

2. Vengono compilate le informazioni del bilancio nel campo split (se presenti),

3. Viene compilata l'url per pagare online (links.online_payment_begin.url), la quale è data dalla concatenazione della variabile d'ambiente EXTERNAL_API_URL alla stringa /online-payment/{payment_id}

4. Viene compilata l'url di ritorno dal pagamento (links.online_payment_landing.url), la quale è data dalla concatenazione della variabile d'ambiente EXTERNAL_API_URL alla stringa /landing/{payment_id}

5. Viene compilata l'url per pagare offline (links.offline_payment.url), la quale è è data dalla concatenazione della variabile d'ambiente EXTERNAL_API_URL alla stringa /offline-payment/{payment_id}

6. Viene compilata l'url della ricevuta di pagamento (links.receipt.url), la quale è data dalla concatenazione della variabile d'ambiente EXTERNAL_API_URL alla stringa /receipt/{payment_id}

7. Viene compilata l'url per richiedere l'aggiornamento del pagamento (links.update.url), la quale è data dalla concatenazione della variabile d'ambiente INTERNAL_API_URL alla stringa /update/{payment_id}

   1. Nota: a differenza dell'altre url, questa viene valorizzata utilizzando una variabile d'ambiente separata in quanto deve essere possibile chiamarla pubblicamente, questo perchè è compito del solo payments-poller richiedere periodicamente l'aggiornamento del pagamento.

8. Viene compilata l'url per forzare l'annullamento di un pagamento (links.cancel.url), la quale è data dalla concatenazione della variabile d'ambiente EXTERNAL_API_URL alla stringa /payments/{payment_id} . Viene inoltre compilato il metodo con cui chiamare la url (links.cancel.method) con il valore PATCH.

9. Viene segnato il timestamp di aggiornamento dell'evento di pagamento (updated_at)

10. Viene infine salvato il pagamento sullo storage e scritto il corrispondente evento aggiornato sul topic payments, indicando come chiave dell'evento il valore del campo service_id.

{
  "id": "2cc87ee5-3f57-4f20-a703-e6718c21b95b",
  "user_id": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "daa0f528-b582-4d1c-9691-e226ac443424",
  "created_at": "2022-12-06T17:43:52+01:00",
  "updated_at": "2022-12-06T17:43:53+01:00",
  "status": "PAYMENT_PENDING",
  "reason": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e - CLNVTR76P01G822Q",
  "remote_id": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e",
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-03-06T17:43:51+01:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": "302872234000000343",
    "iud": "2cc87ee53f574f20a703e6718c21b95b",
    "iuv": "02872234000000343",
    "receiver": null,
    "due_type": "TARI",
    "pagopa_category": "9/12129/TS",
    "document": null,
    "split": []
  },
  "links": {
    "online_payment_begin": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/online-payment/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/detail",
      "last_opened_at": null,
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/notice/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/receipt/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://efil-proxy-qa.boat-backplane.opencontent.io/update/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_check_at": null,
      "next_check_at": "2022-12-06T17:43:53+01:00",
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": "PATCH"
    },
    "cancel": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/payments/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "PATCH"
    } 
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "CLNVTR76P01G822Q",
    "name": "Vittorino",
    "family_name": "Coliandro",
    "street_name": "Via Gramsci, 1",
    "building_number": "",
    "postal_code": "56056",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "raffaele.luccisano@opencontent.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "aa716d45-f56c-4b38-8c62-668a48818a04",
  "event_version": "2.0",
  "event_created_at": "2022-12-06T17:43:53+01:00",
  "app_id": "efil-payment-proxy-qa:1.2.2"
}

In caso di risposta negativa, il pagamento viene passato in stato CREATION_FAILED, viene salvato il pagamento sullo storage e viene scritto l'evento aggiornato sul topic payments

{
  "id": "7037158b-f990-46d9-9377-1392adb81186",
  "user_id": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "b2c33452-a741-4841-acc1-69a2c007e398",
  "created_at": "2022-11-22T17:39:38+01:00",
  "updated_at": "2022-11-22T17:39:38+01:00",
  "status": "CREATION_FAILED",
  "reason": "84a4bc4b-6eaf-4ea2-b4bc-0c4d73b05c6c - CLNVTR76P01G822Q",
  "remote_id": "84a4bc4b-6eaf-4ea2-b4bc-0c4d73b05c6c",
  "payment": {
    "transaction_id": null,
    "paid_at": null,
    "expire_at": "2023-02-20T17:39:37+01:00",
    "amount": 1,
    "currency": "EUR",
    "notice_code": null,
    "iud": "7037158bf99046d993771392adb81186",
    "iuv": null,
    "receiver": null,
    "due_type": null,
    "pagopa_category": null,
    "document": null,
    "split": []
  },
  "links": {
    "online_payment_begin": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/84a4bc4b-6eaf-4ea2-b4bc-0c4d73b05c6c/detail",
      "last_opened_at": null,
      "method": "GET"
    },
    "offline_payment": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": null,
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/84a4bc4b-6eaf-4ea2-b4bc-0c4d73b05c6c/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": null,
      "last_check_at": null,
      "next_check_at": null,
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": "PATCH"
    },
    "cancel": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/payments/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "PATCH"
    }
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "CLNVTR76P01G822Q",
    "name": "Vittorino",
    "family_name": "Coliandro",
    "street_name": "Via Gramsci, 1",
    "building_number": "",
    "postal_code": "56056",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "raffaele.luccisano@opencontent.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "8b3452d8-bd5d-4380-b8a6-7e4f551b09d8",
  "event_version": "2.0",
  "event_created_at": "2022-11-22T17:39:39+01:00",
  "app_id": "pmpay-payment-proxy:1.0.0-rc.2"
}

Nel core intanto, la UI del cittadino monitora lo stato del pagamento interrogando una tabella su KSQLDB creata a partire dal topic payments, e se in stato PAYMENT_PENDING, vengono mostrate all'utente le opzioni per pagare

Step 4 - "Paga online"

1. Verra richiamata l'url {EXTERNAL_API_URL}/online-payment/{payment_id} servita dal proxy

2. Il proxy richiederà all'intermediario di pagamento il link per pagare

3. Sarà segnato il timestamp di apertura del link (links.online_payment_begin.last_opened_at)

4. Sarà segnato il timestamp di aggiornamento dell'evento (updated_at)

5. Il pagamento verrà salvato sullo storage

6. L'evento aggiornato verrà scritto sul topic payments, indicando come chiave dell'evento il valore del campo service_id

7. Verrà restituito il link ritornato allo step 2 mediante il quale l'utente verrà rediretto al portale dell'intermediario

9. Contemporaneamente, essendo che si passa per il proxy, verrà segnato il timestamp in cui l'utente ha aperto il link di ritorno (links.online_payment_landing.last_opened_at)

10. Il pagamento verrà portato in stato PAYMENT_STARTED

11. Sarà segnato il timestamp di aggiornamento dell'evento (updated_at)

12. Il pagamento verrà salvato sullo storage

13. L'evento aggiornato verrà scritto sul topic payments, indicando come chiave dell'evento il valore del campo service_id.

{
  "id": "2cc87ee5-3f57-4f20-a703-e6718c21b95b",
  "user_id": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "daa0f528-b582-4d1c-9691-e226ac443424",
  "created_at": "2022-12-06T17:43:52+01:00",
  "updated_at": "2022-12-06T17:44:51+01:00",
  "status": "PAYMENT_STARTED",
  "reason": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e - CLNVTR76P01G822Q",
  "remote_id": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e",
  "payment": {
    "transaction_id": "7b32b299-67db-4f84-9419-f61962c3e202",
    "paid_at": null,
    "expire_at": "2023-03-06T17:43:51+01:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": "302872234000000343",
    "iud": "2cc87ee53f574f20a703e6718c21b95b",
    "iuv": "02872234000000343",
    "receiver": null,
    "due_type": "TARI",
    "pagopa_category": "9/12129/TS",
    "document": null,
    "split": []
  },
  "links": {
    "online_payment_begin": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/online-payment/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": "2022-12-06T17:43:56+01:00",
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/detail",
      "last_opened_at": "2022-12-06T17:44:51+01:00",
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/notice/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/receipt/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://efil-proxy-qa.boat-backplane.opencontent.io/update/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_check_at": null,
      "next_check_at": "2022-12-06T17:43:53+01:00",
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": "PATCH"
    },
    "cancel": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/payments/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "PATCH"
    } 
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "CLNVTR76P01G822Q",
    "name": "Vittorino",
    "family_name": "Coliandro",
    "street_name": "Via Gramsci, 1",
    "building_number": "",
    "postal_code": "56056",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "raffaele.luccisano@opencontent.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "dcd203c7-a6e8-4084-b09b-f700e8fa94d8",
  "event_version": "2.0",
  "event_created_at": "2022-12-06T17:44:51+01:00",
  "app_id": "efil-payment-proxy-qa:1.2.2"
}

Step 4 - "Paga offline"

1. Verra richiamata l'url {EXTERNAL_API_URL}/offline-payment/{payment_id} servita dal proxy

2. Il proxy richiederà all'intermediario di pagamento il pdf dell'avviso di pagamento

3. Sarà segnato il timestamp di apertura del link (links.offline_payment.last_opened_at)

4. Sarà segnato il timestamp di aggiornamento dell'evento (updated_at)

5. Il pagamento verrà salvato sullo storage

6. L'evento aggiornato verrà scritto sul topic payments, indicando come chiave dell'evento il valore del campo service_id

7. Verrà eseguito il download del pdf ritornato allo step 1

Step 4 - Annulla pagamento

È possibile che l'operatore abbia necessità di annullare un pagamento mediante l'opzione di registrazione del pagamento, ciò può accadere ad esempio se il cittadino, dopo aver creato il pagamento, decide di non concluderlo, e di pagare invece mediante altri canali creando un nuovo pagamento diverso da quello presente sulla piattaforma. Per evitare quindi di lasciare il pagamento pendente per un tempo indefinito, e per permettere l'avanzamento della pratica all'interno della quale è stato creato tale pagamento, sarà possibile annullare quest'ultimo.

Gli step sono i seguenti:

1. Verra richiamata l'url PATCH {EXTERNAL_API_URL}/payments/{payment_id} servita dal proxy con payload {"status": "CANCELED"}

2. Il proxy, dopo aver letto il pagamento dallo storage, segnerà il campo status a CANCELED

3. Sarà segnato il timestamp di apertura del link (links.offline_payment.last_opened_at)

4. Sarà segnato il timestamp di aggiornamento dell'evento (updated_at)

5. Il pagamento verrà salvato sullo storage

6. L'evento aggiornato verrà scritto sul topic payments, indicando come chiave dell'evento il valore del campo service_id

Step 4 - Dovuti importati da fonte esterna all'Area personale

In alcuni casi è possibile che i pagamenti non siano generati a partire dall'area personale, ma siano invece importati da una fonte esterna. In questo caso gli eventi relativi a tali pagamenti saranno inseriti nel topic payments già in status PAYMENT_PENDING e conterranno al loro interno tutte le informazioni che il proxy normalmente inserisce quando fa passare un pagamento generato dall'area personale dallo status CREATION_PENDING allo status PAYMENT_PENDING.

In tal caso tuttavia, questi pagamenti non saranno presenti sullo storage del proxy, dal momento che questa è un'operazione che normalmente farebbe il proxy. Di conseguenza, nel momento in cui dovesse venir letto un evento in stato PAYMENT_PENDING, ci fosse una configurazione attiva per quest'ultimo (ciò si determina controllando che ci sia sullo storage una configurazione con tenant_id e service_id equivalenti a quelli contenuti nel pagamento) ma non esistesse sullo storage, bisogna semplicemente salvare il pagamento sullo storage.

Nel core intanto, questo tipo di dovuti saranno mostrati nella sezione "Pagamenti" insieme a tutti i pagamenti (importati e non) generati dal cittadino, i dati qui presenti sono estratti mediante interrogazione di una tabella su KSQLDB creata a partire dal topic payments.

Cliccando su "Vedi dettaglio" si andrà sul dettaglio dello specifico pagamento dove saranno mostrate le opzioni per pagare (online, offline)

Step 5

Il payments poller nel frattempo:

2. Il proxy a sua volta recupera dallo storage il pagamento, interroga l'intermediario di riferimento per verificare lo stato del pagamento, e in caso lo aggiorna in stato COMPLETE o PAYMENT_STARTED (questa casistica può verificarsi nel caso in cui l'utente paghi ma poi chiuda il browser anziche cliccare sul bottone contenente la landing url)

   1. Se il pagamento viene portato in stato COMPLETE , si dovrà salvare, se presente come informazione ritornata dall'intemediario di riferimento, il timestamp di avvenuto pagamento (payment.paid_at), e l'id della transazione (payment.transaction_id)

3. Il proxy segna il timestamp in cui è stato aperto il link di aggiornamento (links.update.last_opened_at)

4. Il proxy segna il timestamp di aggiornamento del pagamento (updated_at)

5. Il proxy salva il pagamento sullo storage e lo scrive sul topic payments, indicando come chiave dell'evento il valore del campo service_id.

Logica di polling

Più passa il tempo, più è probabile che il pagamento non venga eseguito dall'utente, di conseguenza ad ogni chiamata del poller verso il proxy, viene incrementato l'intervallo di tempo tra una chiamata e l'altra, ciò viene fatto in base al campo links.update.next_check_at.

Nello specifico il polling avviene con al seguente logica:

1. Condizione iniziale: Se il campo last_check_at è nullo (non è stato effettuato alcun controllo in precedenza), la funzione termina immediatamente senza aggiornare il prossimo controllo.

2. Checkpoint temporali: La funzione utilizza diversi checkpoint per classificare il tempo trascorso dalla creazione della risorsa:

   1. 5 minuti

   2. 15 minuti

   3. 7 giorni

   4. 30 giorni

   5. 365 giorni

Ciascun intervallo ha una frequenza di controllo associata:

• Fino a 5 minuti: Controlli ogni 1 minuto.

• Fino a 15 minuti: Controlli ogni 5 minuti.

• Fino a 7 giorni: Controlli ogni ora.

• Fino a 30 giorni: Controlli ogni 6 ore.

• Fino a 365 giorni: Controlli settimanali, sempre alla fine della settimana corrente.

• Oltre 365 giorni: La risorsa è considerata scaduta, lo stato è impostato su STATUS_EXPIRED e il prossimo controllo è disabilitato (next_check_at impostato a None).

• Impostazione del prossimo controllo: Se determinato, il next_check è aggiornato al valore calcolato

• Aggiornamento dello stato: Se il tempo dalla creazione supera i 365 giorni, lo stato della risorsa viene aggiornato a STATUS_EXPIRED.

Nota 2: non tutti i proxy aggiornano i pagamenti mediante update, alcuni vengono aggiornati predisponendo un'apposita API che l'intermediario di pagamento PagoPA chiama inviando la notifica di completamento del pagamento. Questa viene quindi elaborata dal proxy il quale aggiorna il pagamento portandolo in stato COMPLETE, segna il timestamp di aggiornamento del pagamento (updated_at), lo salva sullo storage e lo scrive sul topic payments, indicando come chiave dell'evento il valore del campo service_id .

{
  "id": "2cc87ee5-3f57-4f20-a703-e6718c21b95b",
  "user_id": "1c340b05-0808-4dbe-ad12-81ebbf3b6abf",
  "type": "PAGOPA",
  "tenant_id": "60e35f02-1509-408c-b101-3b1a28109329",
  "service_id": "daa0f528-b582-4d1c-9691-e226ac443424",
  "created_at": "2022-12-06T17:43:52+01:00",
  "updated_at": "2022-12-07T09:47:35+01:00",
  "status": "COMPLETE",
  "reason": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e - CLNVTR76P01G822Q",
  "remote_id": "a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e",
  "payment": {
    "transaction_id": "7b32b299-67db-4f84-9419-f61962c3e202",
    "paid_at": null,
    "expire_at": "2023-03-06T17:43:51+01:00",
    "amount": 1.34,
    "currency": "EUR",
    "notice_code": "302872234000000343",
    "iud": "2cc87ee53f574f20a703e6718c21b95b",
    "iuv": "02872234000000343",
    "receiver": null,
    "due_type": "TARI",
    "pagopa_category": "9/12129/TS",
    "document": null,
    "split": []
  },
  "links": {
    "online_payment_begin": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/online-payment/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": "2022-12-06T17:43:56+01:00",
      "method": "GET"
    },
    "online_payment_landing": {
      "url": "https://servizi.comune.bugliano.pi.it/x/it/pratiche/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/detail",
      "last_opened_at": "2022-12-06T17:44:51+01:00",
      "method": "GET"
    },
    "offline_payment": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/notice/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "receipt": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/receipt/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "GET"
    },
    "notify": [
      {
        "url": "https://servizi.comune.bugliano.pi.it/x/api/applications/a1bbcafb-ee78-4cd1-9b8e-7ddeb434d84e/payment",
        "method": "POST",
        "sent_at": null
      }
    ],
    "update": {
      "url": "http://efil-proxy-qa.boat-backplane.opencontent.io/update/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_check_at": "2022-12-07T09:47:35+01:00",
      "next_check_at": "2022-12-07T10:47:35+01:00",
      "method": "GET"
    },
    "confirm": {
      "url": null,
      "last_opened_at": null,
      "method": "PATCH"
    },
    "cancel": {
      "url": "https://efil-proxy-qa.boat.opencontent.io/payments/2cc87ee5-3f57-4f20-a703-e6718c21b95b",
      "last_opened_at": null,
      "method": "PATCH"
    } 
  },
  "payer": {
    "type": "human",
    "tax_identification_number": "CLNVTR76P01G822Q",
    "name": "Vittorino",
    "family_name": "Coliandro",
    "street_name": "Via Gramsci, 1",
    "building_number": "",
    "postal_code": "56056",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "raffaele.luccisano@opencontent.it"
  },
  "debtor": {
    "type": "human",
    "tax_identification_number": "BNRMHL75C06G702B",
    "name": "Michelangelo",
    "family_name": "Buonarroti",
    "street_name": "Cesare Battisti",
    "building_number": "",
    "postal_code": "38010",
    "town_name": "Bugliano",
    "country_subdivision": "PI",
    "country": "IT",
    "email": "lorenzo.bertoli@opencitylabs.it"
  },
  "event_id": "1a745224-37bb-4843-a85f-3011764395a6",
  "event_version": "2.0",
  "event_created_at": "2022-12-07T09:47:35+01:00",
  "app_id": "efil-payment-proxy-qa:1.2.2"
}

Il payment updater monitora lo stato dei pagamenti leggendo dal topic payments, e contestualmente aggiorna lo stato della pratica, se il pagamento è in statoPAYMENT_STARTED, aggiorna lo stato della pratica a "In attesa dell'esito di pagamento", se invece il pagamento è in stato COMPLETE, aggiorna lo stato della pratica a "Accettata" se il pagamento è posticipato, o Inviata se il pagamento è immediato.

TABELLA STATI PAGAMENTO

Gli stati per i quali passa un pagamento durante il suo ciclo di vita sono riassunti nella seguente tabella

REQUISITI

Tutti i proxy devono:

• Validare gli eventi in input e output

• Integrazione con sentry

• Healthcheck

• Esporre metriche di monitoraggio in formato prometheus

Aggiornamenti principali rispetto all'API v1

Introduzione di campi "standard"

Con la versione 2 delle API di configurazione sono stati introdotti dei campi da introdurre obbligatoriamente in ogni integrazione.

Tenant

I campi da introdurre obbligatoriamente a livello di configurazione del tenant sono:

• id: identificativo univoco del tenant

• name: nome del tenant

• tax_identification_number: codice fiscale dell'ente

Configurazione pagamento

I campi da introdurre obbligatoriamente a livello di configurazione del pagamento sono:

• payment_type: tipo di pagamento, può assumere i valori pagopa o stamp, serve a distinguere tra un pagamento ordinario (es. TARI) e una marca da bollo digitale. Questa distinzione è necessaria in quanto in alcuni intermediare i metodi di creazione di un pagamento di una marca da bollo digitale differiscono da quelli di creazione di un pagamento ordinario.

• remote_collection.id: identificativo della collezione di provenienza della configurazione di pagamento.

• remote_collection.type: tipo di collezione di provenienza della configurazione di pagamento, può assumere valori quali application, service o altro.

• amount: importo del pagamento configurato.

• reason: causale del pagamento configurato

• expire_at: numero di giorni di validità del pagamento

• receiver.tax_identification_number: codice fiscale del beneficiario del pagamento, da usare in caso di pagamenti multibeneficiario

• receiver.name: nome del beneficiario del pagamento, da usare in caso di pagamenti multibeneficiario

• collection_data: tassonomia di pagoPA dei pagamenti

Configurazione tenant

L'admin, dall'interfaccia di configurazione dei pagamenti della Stanza del Cittadino compila la configurazione mediante una form, il cui json schema è servito dall'API /tenants/schema

Lo schema della form sopra riportata è il seguente

{
    "display": "form",
    "components": [
        {
            "label": "UUID del Tenant",
            "placeholder": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "spellcheck": false,
            "attributes": {
                "readonly": "readonly"
            },
            "hidden": true,
            "tableView": false,
            "validate": {
                "required": true
            },
            "key": "id",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Nome dell'ente",
            "placeholder": "Comune di Bugliano",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "name",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Codice IPA dell'ente",
            "placeholder": "A000",
            "description": "Codice (tutto maiuscolo) assegnato all'Ente nel registro <a href='http://www.indicepa.gov.it' target='__blank'>indice PA</a>",
            "spellcheck": false,
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "IPA_code",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Codice fiscale dell'ente",
            "placeholder": "123456789",
            "spellcheck": false,
            "key": "tax_identification_number",
            "type": "textfield",
            "validate": {
                "required": true
            },
            "input": true,
            "tableView": true
        },
        {
            "label": "Password",
            "placeholder": "************",
            "description": "Password assegnata da MyPay all\u2019Ente",
            "spellcheck": false,
            "tableView": false,
            "validate": {
                "required": true
            },
            "key": "password",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Password carrello dovuti",
            "placeholder": "************",
            "description": "Password assegnata all\u2019ente creditore. Tale password va richiesta all\u2019amministratore dell\u2019ente creditore.<br>ATTENZIONE: questo dato NON coincide con la password (principale) dell\u2019ente.",
            "spellcheck": false,
            "tableView": true,
            "key": "cart_password",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Codice applicazione",
            "spellcheck": false,
            "tableView": true,
            "key": "application_code",
            "type": "textfield",
            "input": true,
            "hidden": true,
            "defaultValue": "SDC"
        },
        {
            "label": "Abilitato",
            "key": "active",
            "type": "checkbox",
            "input": true,
            "hidden": true,
            "defaultValue": true
        },
        {
            "label": "Salva",
            "showValidations": false,
            "tableView": false,
            "key": "submit",
            "type": "button",
            "input": true
        }
    ]
}

Premendo poi il bottone Salva, viene eseguita una POST /tenants servita dal proxy, con payload

{
    "name": "Comune di Bugliano",
    "IPA_code": "p_tn",
    "tax_identification_number": "00337460224",
    "password": "4CKSILO7FQPZ",
    "cart_password": "",
    "application_code": "",
    "active": true,
    "enable_checkout": false,
    "id": "60e35f02-1509-408c-b101-3b1a28109329"
}

Per modificare una configurazione esistente, il proxy serve l'API PUT /tenants/{tenant_id} e PATCH /tenants/{tenant_id}

Per eliminare una configurazione esistente, il proxy serve l'API DELETE /tenants/{tenant_id} . In questo caso l'eliminazione è una soft-delete, ovvero la configurazione viene semplicemente disattivata settando il parametro active a false ed eliminando la configurazione dalla memoria ma non dallo storage.

Configurazione pagamento

L'admin, dall'interfaccia di configurazione dei pagamenti per un servizio compila la configurazione mediante una form, il cui json schema è servito dall'API /configs/schema

Lo schema della form soprariportata è il seguente

{
    "display": "form",
    "components": [
        {
            "label": "UUID del Tenant",
            "hidden": true,
            "placeholder": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "spellcheck": false,
            "attributes": {
                "readonly": "readonly"
            },
            "validate": {
                "required": true
            },
            "key": "tenant_id",
            "type": "textfield",
            "input": true,
            "tableView": true
        },
        {
            "label": "Container",
            "tableView": false,
            "validateWhenHidden": false,
            "key": "remote_collection",
            "type": "container",
            "input": true,
            "components": [
                {
                    "label": "UUID del Servizio",
                    "placeholder": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
                    "applyMaskOn": "change",
                    "hidden": true,
                    "spellcheck": false,
                    "tableView": true,
                    "validate": {
                        "required": true
                    },
                    "validateWhenHidden": false,
                    "key": "id",
                    "attributes": {
                        "readonly": "readonly"
                    },
                    "type": "textfield",
                    "input": true
                }
            ]
        },
        {
            "label": "Tipo di pagamento",
            "widget": "choicesjs",
            "tableView": true,
            "defaultValue": "pagopa",
            "data": {
                "values": [
                    {
                        "label": "PagoPA",
                        "value": "pagopa"
                    },
                    {
                        "label": "Marca da Bollo Digitale",
                        "value": "stamp"
                    }
                ]
            },
            "validate": {
                "required": true
            },
            "key": "payment_type",
            "type": "select",
            "input": true
        },
        {
            "label": "Codice Tributo",
            "placeholder": "AAAAA_AAAAA_AAAAA",
            "description": "Questo codice è fornito dall'ente e comunicato a IRIS (inserire in maiuscolo)",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "code",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "pagopa"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Descrizione del servizio",
            "placeholder": "Contributo Pratiche Polizia Municipale",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "description",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "pagopa"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Importo",
            "applyMaskOn": "change",
            "mask": false,
            "tableView": false,
            "delimiter": false,
            "requireDecimal": false,
            "inputFormat": "plain",
            "truncateMultipleSpaces": false,
            "validate": {
                "required": true,
                "custom": "valid = (data.payment_type == 'stamp' && data.amount == 16) || (data.payment_type == 'pagopa') ? true : 'In caso di marca da bollo digitale l\\'unico importo permesso è di 16 euro'"
            },
            "validateWhenHidden": false,
            "key": "amount",
            "type": "number",
            "input": true
        },
        {
            "label": "Causale",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true,
                "maxLength": 60
            },
            "key": "reason",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Scadenza",
            "inputMask": "99/99/9999",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "expire_at_label",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Scadenza",
            "applyMaskOn": "change",
            "hidden": true,
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "expire_at",
            "type": "textfield",
            "input": true
        },
        {
            "label": "Categoria",
            "widget": "choicesjs",
            "description": "Selezione dalla Tassonomia di PagoPA dei pagamenti.",
            "tableView": true,
            "dataSrc": "url",
            "data": {
                "url": "https://api.opencityitalia.it/datasets/pagopa",
                "headers": [
                    {
                        "key": "",
                        "value": ""
                    }
                ]
            },
            "dataType": "object",
            "idPath": "",
            "valueProperty": "DATI SPECIFICI DI INCASSO",
            "template": "<span>{{ item[\"NOME MACRO AREA\"] }}: {{ item[\"TIPO SERVIZIO\"] }}</span>",
            "customDefaultValue": "await new Promise(r => setTimeout(r, 1000));",
            "validate": {
                "required": true
            },
            "key": "collection_data",
            "type": "select",
            "disableLimit": false,
            "noRefreshOnScroll": false,
            "input": true
        },
        {
            "label": "Abilitato",
            "hidden": true,
            "defaultValue": true,
            "key": "active",
            "type": "checkbox",
            "input": true,
            "tableView": false
        },
        {
            "label": "Bilancio",
            "tableView": false,
            "defaultValue": true,
            "key": "split_enable",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "pagopa"
            },
            "type": "checkbox",
            "input": true
        },
        {
            "label": "Bilancio",
            "reorder": false,
            "addAnotherPosition": "bottom",
            "layoutFixed": false,
            "enableRowGroups": false,
            "initEmpty": true,
            "tableView": false,
            "defaultValue": [
                {
                    "split_id": "",
                    "split_type": "",
                    "split_code": "",
                    "split_description": "",
                    "split_budget_chapter": "",
                    "split_assessment": ""
                }
            ],
            "key": "split",
            "customConditional": "show = data.split_enable && data.payment_type == 'pagopa'",
            "type": "datagrid",
            "input": true,
            "components": [
                {
                    "label": "ID",
                    "description": "Identificativo univoco della voce di bilancio. Testo libero",
                    "placeholder": "c_1",
                    "tableView": true,
                    "validate": {
                        "required": true
                    },
                    "key": "split_id",
                    "type": "textfield",
                    "input": true
                },
                {
                    "label": "Tipo",
                    "placeholder": "Tipo c1",
                    "tableView": true,
                    "key": "split_type",
                    "type": "textfield",
                    "input": true
                },
                {
                    "label": "Codice",
                    "placeholder": "Codice c1",
                    "tableView": true,
                    "key": "split_code",
                    "type": "textfield",
                    "input": true
                },
                {
                    "label": "Descrizione",
                    "placeholder": "Descrizione c1",
                    "tableView": true,
                    "key": "split_description",
                    "type": "textfield",
                    "input": true
                },
                {
                    "label": "Importo",
                    "description": "Importo della voce di bilancio. NB: La somma degli importi delle voci DEVE equivalere all'importo totale",
                    "placeholder": "16.00",
                    "validate": {
                        "required": true
                    },
                    "mask": false,
                    "tableView": false,
                    "delimiter": false,
                    "requireDecimal": false,
                    "inputFormat": "plain",
                    "truncateMultipleSpaces": false,
                    "key": "split_amount",
                    "type": "number",
                    "input": true
                },
                {
                    "label": "Capitolo",
                    "placeholder": "Capitolo di bilancio c1",
                    "tableView": true,
                    "key": "split_budget_chapter",
                    "type": "textfield",
                    "input": true
                },
                {
                    "label": "Accertamento",
                    "placeholder": "Accertamento c1",
                    "tableView": true,
                    "key": "split_assessment",
                    "type": "textfield",
                    "input": true
                }
            ]
        },
        {
            "label": "hidden",
            "calculateValue": "if (!data.split || data.split == 'undefined') {\n  data.split = []\n} else if (typeof data.split==='object' && Object.keys(data.split).length === 0) {\n  data.split = [];\n}\n\nlet passedDate = moment(data.expire_at_label, 'DD/MM/YYYY');\nif (!passedDate.isValid()){\n  valid = \"La data inserita non è valida\";\n}\nif (passedDate.isAfter(moment())){\n  valid = \"La data inserita non può essere successiva alla data odierna\";\n}\n\nif (passedDate.isValid()){\n  data.expire_at = new Date(data.expire_at_label).toISOString();\n}",
            "key": "hidden",
            "type": "hidden",
            "input": true,
            "tableView": false
        },
        {
            "label": "Codice ufficio",
            "placeholder": "FSE",
            "description": "Il “codice ufficio” permette di distinguere l’ufficio di regione Toscana competente.",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "office_code",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "stamp"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Descrizione ufficio",
            "placeholder": "Fondo Sociale Europeo",
            "description": "Valorizzare con il nome dell’ufficio competente",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "office_description",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "stamp"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Codice Riferimento Bollo",
            "placeholder": "TIROCINI",
            "description": "Il “codice riferimento bollo” permette di distinguere il bollo per lo specifico ufficio.",
            "prefix": "BOLLO_",
            "applyMaskOn": "change",
            "tableView": true,
            "validate": {
                "required": true
            },
            "key": "reference_code",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "stamp"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Note",
            "placeholder": "Pagamento Bollo Tirocinio Avviso: Avviso contributo tirocini non curriculari on line Giovanisì - FSE dal 1 Settembre 2017 per Soggetto Ospitante: CTP SYSTEM SRL",
            "description": "Necessaria per la corretta visualizzazione di ulteriori dettagli sulla ricevuta di pagamento",
            "applyMaskOn": "change",
            "tableView": true,
            "key": "notes",
            "conditional": {
                "show": true,
                "when": "payment_type",
                "eq": "stamp"
            },
            "type": "textfield",
            "input": true
        },
        {
            "label": "Salva",
            "showValidations": false,
            "key": "submit",
            "type": "button",
            "input": true,
            "tableView": false
        }
    ]
}

Premendo poi il bottone Salva, viene eseguita una POST /configs servita dal proxy, con payload

{
  "id": "5ec5668d-fed1-42a2-b648-abe1fe19b87a",
  "tenant_id": "8fdf037e-d8c0-4314-8291-b5fecb5f613a",
  "remote_collection": {
    "id": "d058b207-aedf-4683-b961-6ae146f69773",
    "type": "service"
  },
  "payment_type": "pagopa",
  "code": "CONTR_PRTPM",
  "description": "Contributo Pratiche Polizia Municipale",
  "reason": "Richiesta permesso di occupazione suolo pubblico",
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione d1",
      "split_budget_chapter": "Cap1",
      "split_assessment": "Acc1",
      "split_amount": 16
    }
  ],
  "collection_data": "9/0101102TS/",
  "amount": 16,
  "expire_at": "2024-12-11T23:00:00.000Z"
}

Per ottenere una lista di configurazioni di pagamento (fino a un massimo di 5), il proxy serve l'API GET /configs?config_id=config_id1&config_id=config_id2

Per modificare una configurazione esistente, il proxy serve l'API PUT /configs/{config_id} e PATCH /configs/{config_id}

Per eliminare una configurazione esistente, il proxy serve l'API DELETE /configs/{config_id} . In questo caso l'eliminazione è una soft-delete, ovvero la configurazione viene semplicemente disattivata settando il parametro active a false.

Swagger di esempio