Implementazione di un proxy

Molti aspetti implementativi dipendono più dalla normativa che da nostre scelte progettuali, in questa pagina si evidenziano gli uni e le altre.

Requisiti funzionali

Sono requisiti che dipendono da nostre scelte implementative, possono cambiare man mano che evolviamo la piattaforma, per supportare nuovi casi d'uso (pagamento dei dovuti) oppure perché ci accorgiamo che abbiamo commesso qualche errore nella progettazione.

1. Gestione di pagamenti spontanei

2. Gestione di pagamenti con bilancio

3. Gestione della notifica dello stato del pagamento da parte dell'IdP - se disponibile - o del polling se non è disponibile la notifica

4. Se è implementato il polling, questo deve avvenire con un back-off esponenziale che assicuri alcuni check nel giro di pochi minuti e poi si diradi fino a un massimo di un check al giorno fino alla scadenza del pagamento o 1 anno se la scadenza è inferiore.

5. Gestione delle configurazioni a livello di Tenant e di Servizio

Requisiti normativi

• Avere una specifica in formato OpenAPI v3

• Rispettare la Linee Guida di interoperabilità: in particolare per quanto riguarda

  • il formato dei dati (4.2)

  • raccomandazioni sul naming (4.3) optando per la scelta di snake_case per i nomi degli attributi

  • logging (4.4)

  • risultare valido nel validatore ufficiale OA3

Requisiti per l'ambiente di produzione

• Sappiamo che in molti topic ci sono diversi eventi mal formati, per vari errori e assenza di uno schema registry, quindi è necessario validare gli eventi in input e opzionalmente in output (lo fanno le nostre prime implementazioni in python, ma è un requisito?)

• Ci aspettiamo che se di dovesse aggiornare il formato dell'evento nel topic payments gestiremo eventi anche in parallelo con versioni distinte, quindi ogni proxy deve Interpretare solo gli eventi che riportano il formato più recente dell'evento nel topic payments: event_version: 2.0

• Integrarsi con sentry per la gestione degli errori

• Esporre metriche di monitoraggio in formato prometheus, in particolare:

  • counter sul numero di pagamenti creati

  • counter sul numero di errori durante il processamento di pagamenti, differenziando gli errori interni (errori di formato dati in ingresso o validazione) da errori esterni (errori di dialogo con l'IdP)

  • latenza delle chiamate fatte all'IdP

  Di seguito la tabella contenente le specifiche di ogni metrica

Metrica	Labels	Descrizione
oc_payment_validation_errors_total	cluster, env, app_name	la metrica deve misurare gli errori di validazione sull'evento letto (es. l'importo è una stringa invece che un float)
oc_api_requests_total	cluster, env, method, app_name, status_code	la metrica deve monitorare le chiamate http indicandone lo status code
oc_payment_success_events_total	cluster, env, app_name	la metrica deve misurare solo gli eventi per cui il proxy ha una configurazione e che stati processati con successo
oc_payment_failed_events_total	cluster, env, app_name	la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing per qualsiasi motivo (escluso il caso in cui non esiste una configurazione per esso)
oc_payment_provider_errors_total	cluster, env, app_name	la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing a causa di un errore sul provider
oc_payment_internal_errors_total	cluster, env, app_name	la metrica deve misurare gli eventi di pagamento validi di cui però è fallito il processing per errori interni al codice
oc_payment_provider_latency_bucket	cluster, env, app_name	istogramma che mostra la distribuzione di latenza delle risposte del provider

Inoltre il servizio deve rispettare gli standard della piattaforma in particolare per quanto riguarda la gestione dello storage: non possiamo avere vendor-lockin sulle tecnologie, quindi dobbiamo essere compatibili con file-system posix tradizionale, NFS share e almeno i due cloud-storage più diffusi S3 e Azure Blob.

Documentazione API di Esempio - Swagger

Get Status

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/status

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Online Url

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/online-payment/{payment_id}

Path parameters

payment_id*Payment Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/online-payment/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Notice File

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/notice/{payment_id}

Path parameters

payment_id*Payment Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/notice/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Receipt File

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/receipt/{payment_id}

Path parameters

payment_id*Payment Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/receipt/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Check For Updates

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/update/{payment_id}

Path parameters

payment_id*Payment Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/update/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Landing Url

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/landing/{payment_id}

Path parameters

payment_id*Payment Id

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/landing/{payment_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Notify Payment

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/notify-payment

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/notify-payment', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Get Tenant Form Schema

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/schema

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/schema', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Tenant Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Response

200422

Successful Response

Body

application/json

tax_identification_number*Tax Identification Number

code*Code

sil_id*Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tax_identification_number": "01234567891",
  "code": "CBugliano",
  "sil_id": "SIL_CBUGLIANO_OPEN",
  "password": "76JWL*G6bS!OM2e9*3Fg",
  "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
  "application_code": "",
  "active": true,
  "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
}

Update Tenant Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Body

application/json

tax_identification_number*Tax Identification Number

code*Code

sil_id*Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "code": "CBugliano",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "stamp_code": "CBugliano_SIL_E_BOLLO",
      "stamp_password": "76JWL*G6bS!OM2e9*3Fg",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true
    }),
});
const data = await response.json();

Delete Tenant

DELETEhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Response

204422

Successful Response

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Update Existing Tenant Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}

Path parameters

tenant_id*Tenant Id

Body

application/json

New Configuration

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants/{tenant_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "1234567891"
    }),
});
const data = await response.json();

Save Tenant Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants

Body

application/json

tax_identification_number*Tax Identification Number

code*Code

sil_id*Sil Id

password*Password

cert*Cert

application_codeApplication Code

active*Active

stamp_codeStamp Code

stamp_passwordStamp Password

id*Id

Response

201422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/tenants', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tax_identification_number": "01234567891",
      "code": "CBugliano",
      "sil_id": "SIL_CBUGLIANO_OPEN",
      "password": "76JWL*G6bS!OM2e9*3Fg",
      "cert": "-----BEGIN CERTIFICATE REQUEST-----MIIB9TCCAWACAQAwgbgxGTAXBgNVBAoMEFF1b1ZhZGlzIExpbWl0ZWQxHDAaBgNVBAsME0RvY3VtZW50IERlcGFydG1lbnQxOTA3BgNVBAMMMFdoeSBhcmUgeW91IGRl-----END CERTIFICATE REQUEST-----",
      "application_code": "",
      "active": true,
      "id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6"
    }),
});
const data = await response.json();

Get Service Form Schema

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/schema

Response

200

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/schema', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Get Service Configuration

GEThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Response

200422

Successful Response

Body

application/json

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

stampPaymentStamp

id*Id

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
  "payment_type": "pagopa",
  "code": "CONTR_PRTPM",
  "description": "<p>Abbonamento aree di sosta</p>",
  "active": true,
  "split": [
    {
      "split_id": "c_1",
      "split_type": "Tipo c1",
      "split_code": "Codice c1",
      "split_description": "Descrizione c1",
      "split_amount": 0.5,
      "split_budget_chapter": "Capitolo di bilancio c1",
      "split_assessment": "Accertamento c1"
    }
  ],
  "stamp": {
    "items": [
      {
        "id": "01",
        "amount": 16
      }
    ],
    "office_code": "FSE",
    "office_description": "Fondo Sociale Europeo",
    "reference_code": "BOLLO_TIROCINI",
    "notes": ""
  },
  "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
  "__$markdownParsed": true
}

Update Service Configuration

PUThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Body

application/json

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

stampPaymentStamp

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "stamp": {
        "items": [
          {
            "id": "01",
            "amount": 16
          }
        ],
        "office_code": "FSE",
        "office_description": "Fondo Sociale Europeo",
        "reference_code": "BOLLO_TIROCINI",
        "notes": ""
      },
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Delete Service

DELETEhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Response

204422

Successful Response

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Update Existing Service Configuration

PATCHhttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}

Path parameters

service_id*Service Id

Body

application/json

New Configuration

Response

200422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services/{service_id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Save Service Configuration

POSThttps://api.qa.stanzadelcittadino.it/payment-proxy/iris/services

Body

application/json

tenant_id*Tenant Id

payment_typePayment Type

codeCode

descriptionDescription

active*Active

splitSplit

stampPaymentStamp

id*Id

Response

201422

Successful Response

Body

application/json

any

Request

JavaScriptCurl

const response = await fetch('https://api.qa.stanzadelcittadino.it/payment-proxy/iris/services', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tenant_id": "b212c4b4-db26-4404-8c7c-47dab99dd2e6",
      "payment_type": "pagopa",
      "code": "CONTR_PRTPM",
      "description": "<p>Abbonamento aree di sosta</p>",
      "active": true,
      "split": [
        {
          "split_id": "c_1",
          "split_type": "Tipo c1",
          "split_code": "Codice c1",
          "split_description": "Descrizione c1",
          "split_amount": 0.5,
          "split_budget_chapter": "Capitolo di bilancio c1",
          "split_assessment": "Accertamento c1"
        }
      ],
      "id": "23d57b65-5eb9-4f0a-a507-fbcf3057b248",
      "__$markdownParsed": true
    }),
});
const data = await response.json();

Iris Proxy - Swagger UI

Esempi di proxy da cui si può prendere spunto

EFIL: http://gitlab.com/opencontent/stanza-del-cittadino/efil-payment-proxy

IRIS: http://gitlab.com/opencontent/stanza-del-cittadino/iris-payment-proxy

MYPAY: http://gitlab.com/opencontent/stanza-del-cittadino/mypay-payment-proxy

PMPAY: http://gitlab.com/opencontent/stanza-del-cittadino/pmpay-payment-proxy

Questi proxy condividono alcune scelte implementative grazie a un apposito python-sdk sviluppato in parallelo ai proxy stessi:

• le configurazioni sono salvate su disco locale o s3 secondo un albero ben definito tenant->servizio

• i singoli pagamenti vengono salvati su storage fino a che il pagamento è pendente, così da poter fare il polling in autonomia.

Altri riferimenti utili

• Presentazione API Interoperability a EuroPython 2018

• Presentazione API Interoperability a EuroPython 2019

• API Starter Kit