Caricamento massivo

Specifiche per il caricamento massivo delle posizioni debitorie

In questa sezione sono presenti tutte le informazioni necessarie per l'utilizzo della funzionalità di caricamento massivo delle posizioni debitorie sulla piattaforma GPD.

Al fine di facilitare l'inserimento delle posizioni debitorie relative agli enti creditori che aderiscono alla piattaforma pagoPA in modalità asincrona, è stata implementata la funzionalità di caricamento massivo.

Nei paragrafi che seguono sono descritte le specifiche relative alle due modalità d'interfacciamento rese disponibili:

• ​Caricamento tramite API​

• Caricamento tramite SFTP

Specifiche tracciato di input

Specifiche relative file da utilizzare come input per i servizi di caricamento massivo

Al fine di innescare il caricamento il processo di massivo delle posizioni debitorie, a prescindere dalla modalità scelta è necessario costruire un file in formato JSON secondo le specifiche riportate di seguito nel documento.

Tracciato file

Di seguito è riportato il template relativo al file JSON da produrre per il caricamento massivo:

{
   "paymentPositions": [
     {
       "iupd": "string",
       "type": "F",
       "fiscalCode": "string",
       "fullName": "string",
       "streetName": "string",
       "civicNumber": "string",
       "postalCode": "string",
       "city": "string",
       "province": "string",
       "region": "string",
       "country": "IT",
       "email": "string",
       "phone": "string",
       "switchToExpired": false,
       "companyName": "string",
       "officeName": "string",
       "validityDate": "YYYY-MM-DDThh:mm:ss.SSSZ",
       "paymentOption": [
         {
           "iuv": "string",
           "amount": 0,
           "description": "string",
           "isPartialPayment": true,
           "dueDate": "YYYY-MM-DDThh:mm:ss.SSSZ",
           "retentionDate": "YYYY-MM-DDThh:mm:ss.SSSZ",
           "fee": 0,
           "transfer": [
             {
               "idTransfer": "1",
               "amount": 0,
               "organizationFiscalCode": "00000000000",
               "remittanceInformation": "string",
               "category": "string",
               "iban": "IT0000000000000000000000000",
               "postalIban": "IT0000000000000000000000000",
               "stamp": {
                 "hashDocument": "string",
                 "stampType": "st",
                 "provincialResidence": "RM"
               },
               "transferMetadata": [
                 {
                   "key": "string",
                   "value": "string"
                 }
               ]
             }
           ],
           "paymentOptionMetadata": [
             {
               "key": "string",
               "value": "string"
             }
           ]
         }
       ]
     }
   ]
 }

Si tratta di un array di posizioni debitorie, i campi sono gli stessi descritti all'interno della sezione Operazioni disponibili delle SANP.

Specifiche file

Il tracciato del file è comune ad entrambe le modalità di caricamento API e SFTP, tuttavia per ognuna di queste sono state definite particolari specifiche descritte di seguito.

SFTP

• formato file -> JSON

• dimensioni file -> max 100MB (circa 100K PD)

• nomenclatura -> non ci sono vincoli in merito alla nomenclatura del file, tuttavia il nome deve essere univoco, non è possibile caricare due o più file con lo stesso nome

API

• formato file -> ZIP (un solo file JSON all'interno dell'archivio)

• dimensioni file -> max 5MB (circa 100K PD)

• nomenclatura -> non ci sono vincoli

Nelle prossime versioni della piattaforma i limiti sulle dimensioni dei file verranno aumentati.

Caricamento tramite API

Il caricamento massivo può essere innescato tramite API le cui specifiche sono riportate qui di seguito.

Mediante l'API /organizations/{organizationFiscalCode}/debtpositions/file è possibile innescare il caricamento massivo delle posizioni debitorie presenti all'interno di un file compresso come descritto in Specifiche tracciato di input.

The Organization creates the debt positions listed in the file.

post

Path parameters

broker-codestring · min: 1Required

The broker code

organization-fiscal-codestring · min: 1Required

The organization fiscal code

Body

filestring · binaryOptional

Responses

202

Request accepted.

400

Malformed request.

application/json

401

Wrong or missing function key.

application/json

409

Conflict: duplicate file found.

application/json

500

Service unavailable.

application/json

post

HTTPcURLJavaScriptPython

POST /gpd/debt-positions-service/v1/brokers/{broker-code}/organizations/{organization-fiscal-code}/debtpositions/file HTTP/1.1
Host: api.uat.platform.pagopa.it
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

No content

Il metodo in caso positivo risponde subito con un codice HTTP 202, una volta ottenuta una risposta positiva è possibile verificare lo stato del caricamento mediante l'utilizzo dell'API /organizations/{organizationFiscalCode}/debtpositions/file/{fileId}/status.

Returns the upload status of debt positions uploaded via file.

get

Path parameters

broker-codestring · min: 1Required

The broker code

organization-fiscal-codestring · min: 1Required

The organization fiscal code

file-IDstring · min: 1Required

The fiscal code of the Organization.

Responses

200

Upload found.

application/json

400

Malformed request.

application/json

401

Wrong or missing function key.

application/json

404

Upload not found.

application/json

500

Service unavailable.

application/json

get

HTTPcURLJavaScriptPython

GET /gpd/debt-positions-service/v1/brokers/{broker-code}/organizations/{organization-fiscal-code}/debtpositions/file/{file-ID}/status HTTP/1.1
Host: api.uat.platform.pagopa.it
Accept: */*

{
  "uploadID": "text",
  "processedItem": 1,
  "submittedItem": 1,
  "startTime": "2024-10-08T14:55:16.302Z"
}

Per ottenere un report completo, comprensivo degli esiti per ogni posizioni debitoria, è necessario interrogare l'API /organizations/{organizationFiscalCode}/debtpositions/file/{fileId}/report.

Returns the result of debt positions upload.

get

Path parameters

broker-codestring · min: 1Required

The broker code

organization-fiscal-codestring · min: 1Required

The organization fiscal code

file-IDstring · min: 1Required

The fiscal code of the Organization.

Responses

200

Upload result found.

application/json

400

Malformed request.

application/json

401

Wrong or missing function key.

application/json

404

Upload result not found.

application/json

500

Service unavailable.

application/json

get

HTTPcURLJavaScriptPython

GET /gpd/debt-positions-service/v1/brokers/{broker-code}/organizations/{organization-fiscal-code}/debtpositions/file/{file-ID}/report HTTP/1.1
Host: api.uat.platform.pagopa.it
Accept: */*

{
  "uploadID": "text",
  "processedItem": 1,
  "submittedItem": 1,
  "startTime": "2024-10-08T14:55:16.302Z",
  "endTime": "2024-10-08T14:55:16.302Z",
  "responses": [
    {
      "statusCode": 400,
      "statusMessage": "Bad request caused by invalid email address",
      "requestIDs": [
        "text"
      ]
    }
  ]
}

Caricamento tramite SFTP

Di seguito è descritta la procedura per il caricamento massivo delle posizioni debitorie mediante l'upload di un file non compresso che rispetti le specifiche descritte all'interno della sezione Specifiche tracciato di input.

Credenziali di accesso

Il primo step da eseguire per l'attivazione del servizio consiste nella richiesta di creazione delle credenziali per l'accesso al server SFTP. La richiesta deve essere inoltrata direttamente al team pagoPA-Core utilizzando la casella di posta [e-mail] specificando nome e cognome del referente tecnico e una mail alla quale verranno inviate le credenziali.

Prossimamente sarà possibile ottenere le credenziali in autonomia accedendo al portale BackOffice-pagoPA

Una volta elaborata la richiesta, alla mail indicata verranno inviati i parametri per l'accesso al folder SFTP contenente due subfolders, uno di input su cui depositare i file contenenti l'elenco delle posizioni debitorie da caricare (rif. Specifiche tracciato di input), e uno di output dove la piattaforma fornirà l'esito del caricamento.

Credenziali di accesso:

• path - connection string es. pagopadweugpsgpdsasftp.<USERNAME_INPUT>@pagopadweugpsgpdsasftp.blob.core.windows.net

• password - password riferite all'utente USERNAME_INPUT

Ogni partner/intermediario avrà dunque a disposizione un folder identificato dal codice fiscale/ partita iva avente la seguente struttura:

/CF_BROKER_01
    | CF_EC_01
        | /input
        | /output
    | CF_EC_02
        | /input
        | /output
/CF_BROKER_02
    | CF_EC_03
        | /input
        | /output

Caricamento file

Per innescare il processo di caricamento delle posizioni debitorie è necessario connettersi al folder /CF_BROKER_ID/CF_EC_ID/input utilizzando le relative credenziali di accesso ed effettuare l'upload di uno o più file in formato JSON.

Come riportato nella sezione Specifiche tracciato input va rispettato il vincolo di univocità del nome del file.

L'upload dei file sulla cartella innesca il processo di caricamento massivo che avrà una durata variabile in funzione della dimensione dei file caricati.

Una volta terminato il caricamento massivo, per ogni file viene prodotta una ricevuta all'interno del folder /CF_BROKER_ID/CF_EC_ID/input, la ricevuta è strutturata nel seguente modo:

{
  "uploadID": "string",
  "processedItem": "integer",
  "submittedItem": "integer",
  "responses": [
    {
      "statusCode": "integer",
      "statusMessage": "string",
      "requestIDs": [
        "string"
      ]
    }
  ],
  "startTime": "string($date-time)",
  "endTime": "string($date-time)"
}

• uploadID - identificativo univoco del file caricato (coincide con il nome del file nel caso SFTP)

• responses - la lista degli esiti del caricamento raggruppati per codice di stato e dettaglio.

• requestIDs - la lista degli identificativi delle posizioni debitorie.

• startTime - Data e ora completamento processo di upload

• endTime - Data e ora completamento processo di upload