Operazioni disponibili

Tutte le operazioni indicate sono segregate per codice fiscale dell'ente creditore (organizationfiscalcode).

In caso di intermediazione, è possibile associare alla subscription key dell'intermediario da 1 ad n codici fiscali di enti intermediati, ciò consente agli intermediari di utilizzare una sola subscription key per l'invocazione delle API per conto di tutti gli enti intermediati. Tali abilitazioni devono essere richieste a PagoPA contestualmente alla creazione della subscription key o in momenti successivi.

Le subscription key e le relative abilitazioni sono segregate per ambiente UAT/PROD.

Gestione posizioni debitorie

Nei seguenti sequence diagram si identifica con l'acronimo GPD il servizio di Gestione Posizioni Debitorie e con APD l'Archivio delle Posizioni Debitorie (base dati).

Per i dettagli https://github.com/pagopa/pagopa-api/tree/SANP3.8.0/openapi

Creazione di una posizione debitoria

The Organization creates a debt Position.

POSThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

Query parameters

Header parameters

Body

iupd*string

acaboolean

type*enum

payStandInboolean

feature flag to enable a debt position in stand-in mode

Example: true

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpired*boolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Response

Request created.

Headers

Body

iupd*string

acaboolean

type*enum

payStandInboolean

feature flag to enable a debt position in stand-in mode

Example: true

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpired*boolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "companyName": "text",
      "fiscalCode": "text",
      "fullName": "text",
      "iupd": "text",
      "switchToExpired": false,
      "type": "F"
    }),
});
const data = await response.json();

Response

{
  "iupd": "text",
  "aca": false,
  "type": "F",
  "payStandIn": true,
  "fiscalCode": "text",
  "fullName": "text",
  "streetName": "text",
  "civicNumber": "text",
  "postalCode": "text",
  "city": "text",
  "province": "text",
  "region": "text",
  "country": "text",
  "email": "text",
  "phone": "text",
  "switchToExpired": false,
  "companyName": "text",
  "officeName": "text",
  "validityDate": "2024-12-22T07:00:28.662Z",
  "paymentDate": "2024-12-22T07:00:28.662Z",
  "status": "DRAFT",
  "paymentOption": [
    {
      "nav": "text",
      "iuv": "text",
      "amount": 0,
      "description": "text",
      "isPartialPayment": false,
      "dueDate": "2024-12-22T07:00:28.662Z",
      "retentionDate": "2024-12-22T07:00:28.662Z",
      "fee": 0,
      "notificationFee": 0,
      "transfer": [
        {
          "idTransfer": "1",
          "amount": 0,
          "organizationFiscalCode": "00000000000",
          "remittanceInformation": "text",
          "category": "text",
          "iban": "IT0000000000000000000000000",
          "postalIban": "IT0000000000000000000000000",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "transferMetadata": [
            {
              "key": "text",
              "value": "text"
            }
          ]
        }
      ],
      "paymentOptionMetadata": [
        {
          "key": "text",
          "value": "text"
        }
      ]
    }
  ]
}

In fase di creazione della posizione debitoria il servizio effettuerà controlli sui dati in input e controlli di eventuali duplicati.

Tra i controlli dei dati in input si rilevano:

obbligatorietà dei dati
coerenza date (ad esempio due_date ≥ validity_date)
coerenza importi (ad esempio la somma degli importi dei versamenti deve essere uguale all'importo totale)
validità della tassonomia
validità degli IBAN (devono essere censiti sulla piattaforma pagoPA)

Tra i controlli dei duplicati ci si basa sugli identificativi di pagamento (IUPD, IUV e fiscalCode)

Il query parameter toPublish consente di pubblicare automaticamente una posizione debitoria in fase di creazione, impostando questo parametro a true e valorizzando contestualmente a null il campo validityDate, la posizione debitoria andrà direttamente nello stato VALID pronta per essere pagata.

Lettura di una lista di posizioni debitorie e di una singola posizione debitoria

Return the list of the organization debt positions. The due dates interval is mutually exclusive with the payment dates interval.

GEThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

Query parameters

Header parameters

Response

Obtained all organization payment positions.

Headers

Body

payment_position_list*array of PaymentPositionModelBaseResponse (object)

page_info*PageInfo (object)

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions?page=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "payment_position_list": [
    {
      "iupd": "text",
      "aca": false,
      "payStandIn": true,
      "organizationFiscalCode": "text",
      "type": "F",
      "companyName": "text",
      "officeName": "text",
      "insertedDate": "2024-12-22T07:00:28.662Z",
      "publishDate": "2024-12-22T07:00:28.662Z",
      "validityDate": "2024-12-22T07:00:28.662Z",
      "paymentDate": "2024-12-22T07:00:28.662Z",
      "status": "DRAFT",
      "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
      "paymentOption": [
        {
          "nav": "text",
          "iuv": "text",
          "organizationFiscalCode": "text",
          "amount": 0,
          "description": "text",
          "isPartialPayment": false,
          "dueDate": "2024-12-22T07:00:28.662Z",
          "retentionDate": "2024-12-22T07:00:28.662Z",
          "paymentDate": "2024-12-22T07:00:28.662Z",
          "reportingDate": "2024-12-22T07:00:28.662Z",
          "insertedDate": "2024-12-22T07:00:28.662Z",
          "paymentMethod": "text",
          "fee": 0,
          "notificationFee": 0,
          "pspCompany": "text",
          "idReceipt": "text",
          "idFlowReporting": "text",
          "status": "PO_UNPAID",
          "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
          "paymentOptionMetadata": [
            {
              "key": "text",
              "value": "text"
            }
          ],
          "transfer": [
            {
              "organizationFiscalCode": "text",
              "idTransfer": "text",
              "amount": 0,
              "remittanceInformation": "text",
              "category": "text",
              "iban": "text",
              "postalIban": "text",
              "stamp": {
                "hashDocument": "text",
                "stampType": "text",
                "provincialResidence": "RM"
              },
              "insertedDate": "2024-12-22T07:00:28.662Z",
              "status": "T_UNREPORTED",
              "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
              "transferMetadata": [
                {
                  "key": "text",
                  "value": "text"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "page_info": {
    "page": 0,
    "limit": 0,
    "items_found": 0,
    "total_pages": 0
  }
}

La lettura di una lista di posizioni debitorie prevede sempre una paginazione. E' inoltre possibile filtrare per due_date in modo da limitare i risultati.

Return the details of a specific debt position.

GEThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

iupd*string

IUPD (Unique identifier of the debt position). Format could be <Organization fiscal code + UUID> this would make it unique within the new PD management system. It's the responsibility of the EC to guarantee uniqueness. The pagoPa system shall verify that this is true and if not, notify the EC.

Header parameters

Response

Obtained debt position details.

Headers

Body

iupdstring

acaboolean

payStandInboolean

organizationFiscalCodestring

typeenum

companyNamestring

officeNamestring

insertedDatestring (date-time)

publishDatestring (date-time)

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

lastUpdatedDatestring (date-time)

paymentOptionarray of PaymentOptionModelResponse (object)

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "iupd": "text",
  "aca": false,
  "payStandIn": true,
  "organizationFiscalCode": "text",
  "type": "F",
  "companyName": "text",
  "officeName": "text",
  "insertedDate": "2024-12-22T07:00:28.662Z",
  "publishDate": "2024-12-22T07:00:28.662Z",
  "validityDate": "2024-12-22T07:00:28.662Z",
  "paymentDate": "2024-12-22T07:00:28.662Z",
  "status": "DRAFT",
  "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
  "paymentOption": [
    {
      "nav": "text",
      "iuv": "text",
      "organizationFiscalCode": "text",
      "amount": 0,
      "description": "text",
      "isPartialPayment": false,
      "dueDate": "2024-12-22T07:00:28.662Z",
      "retentionDate": "2024-12-22T07:00:28.662Z",
      "paymentDate": "2024-12-22T07:00:28.662Z",
      "reportingDate": "2024-12-22T07:00:28.662Z",
      "insertedDate": "2024-12-22T07:00:28.662Z",
      "paymentMethod": "text",
      "fee": 0,
      "notificationFee": 0,
      "pspCompany": "text",
      "idReceipt": "text",
      "idFlowReporting": "text",
      "status": "PO_UNPAID",
      "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
      "paymentOptionMetadata": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "transfer": [
        {
          "organizationFiscalCode": "text",
          "idTransfer": "text",
          "amount": 0,
          "remittanceInformation": "text",
          "category": "text",
          "iban": "text",
          "postalIban": "text",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "insertedDate": "2024-12-22T07:00:28.662Z",
          "status": "T_UNREPORTED",
          "lastUpdatedDate": "2024-12-22T07:00:28.662Z",
          "transferMetadata": [
            {
              "key": "text",
              "value": "text"
            }
          ]
        }
      ]
    }
  ]
}

La lettura di una posizione debitoria si basa sull'identificativo in input (IUPD). In caso lo IUPD non sia esistente verrà emesso un errore.

Aggiornamento di una posizione debitoria

The Organization updates a debt position

PUThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

iupd*string

Query parameters

Header parameters

Body

iupd*string

acaboolean

type*enum

payStandInboolean

feature flag to enable a debt position in stand-in mode

Example: true

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpired*boolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Response

Debt Position updated.

Headers

Body

iupd*string

acaboolean

type*enum

payStandInboolean

feature flag to enable a debt position in stand-in mode

Example: true

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpired*boolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "companyName": "text",
      "fiscalCode": "text",
      "fullName": "text",
      "iupd": "text",
      "switchToExpired": false,
      "type": "F"
    }),
});
const data = await response.json();

Response

{
  "iupd": "text",
  "aca": false,
  "type": "F",
  "payStandIn": true,
  "fiscalCode": "text",
  "fullName": "text",
  "streetName": "text",
  "civicNumber": "text",
  "postalCode": "text",
  "city": "text",
  "province": "text",
  "region": "text",
  "country": "text",
  "email": "text",
  "phone": "text",
  "switchToExpired": false,
  "companyName": "text",
  "officeName": "text",
  "validityDate": "2024-12-22T07:00:28.662Z",
  "paymentDate": "2024-12-22T07:00:28.662Z",
  "status": "DRAFT",
  "paymentOption": [
    {
      "nav": "text",
      "iuv": "text",
      "amount": 0,
      "description": "text",
      "isPartialPayment": false,
      "dueDate": "2024-12-22T07:00:28.662Z",
      "retentionDate": "2024-12-22T07:00:28.662Z",
      "fee": 0,
      "notificationFee": 0,
      "transfer": [
        {
          "idTransfer": "1",
          "amount": 0,
          "organizationFiscalCode": "00000000000",
          "remittanceInformation": "text",
          "category": "text",
          "iban": "IT0000000000000000000000000",
          "postalIban": "IT0000000000000000000000000",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "transferMetadata": [
            {
              "key": "text",
              "value": "text"
            }
          ]
        }
      ],
      "paymentOptionMetadata": [
        {
          "key": "text",
          "value": "text"
        }
      ]
    }
  ]
}

In fase di aggiornamento, oltre ai già citati controlli in fase di creazione , si verifica che la posizione sia esistente ed aggiornabile.

In particolare l'aggiornabilità della posizione debitoria dipende dallo stato della posizione stessa (ad esempio se una posizione è già stata pagata non sarà possibile aggiornarla)

E' importante porre particolare attenzione al campo notificationFee che contiene le spese di notifica della posizione debitoria. Questo campo viene gestito in modo esclusivo da Piattaforma Notifiche e l'eventuale importo viene aggiunto automaticamente dal sistema GPD all'importo delle posizioni debitorie. L'EC pertanto in fase di aggiornamento dell'importo amount di uno dei transfer presenti all'interno di una paymentOption, non dovrà tenere conto del valore presente all'interno del campo notificationFee.

Cancellazione di una Posizione Debitoria

The Organization deletes a debt position

DELETEhttps://api.uat.platform.pagopa.it/gpd/api/v1/organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

iupd*string

Header parameters

Response

Operation completed successfully.

Headers

Body

string

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/api/v1/organizations/{organizationfiscalcode}/debtpositions/{iupd}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

text

La cancellazione di una posizione debitoria prevede controlli sia sull'esistenza (IUPD) che sullo stato (ad esempio, una posizione debitoria non sarà cancellabile se è già stata pagata)

Pubblicazione di una posizione debitoria

The Organization publish a debt Position.

POSThttp://api.uat.platform.pagopa.it/organizations/{organizationfiscalcode}/debtpositions/{iupd}/publish

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

iupd*string

Response

Request published.

Body

iupd*string

type*enum

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpiredboolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Request

Response

La pubblicazione della posizione debitoria permette il passaggio dallo stato DRAFT allo stato PUBLISHED.

Una posizione in stato DRAFT (bozza) infatti non permette la normale operatività con la piattaforma pagoPA. Solo quando l'Ente Creditore pubblica la posizione, in coerenza con le date di validità e di scadenza, questa risulta pagabile sulla piattaforma.

Invalidazione di una posizione debitoria

The Organization invalidate a debt Position.

POSThttp://api.uat.platform.pagopa.it/organizations/{organizationfiscalcode}/debtpositions/{iupd}/invalidate

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

iupd*string

Response

Request published.

Body

iupd*string

type*enum

fiscalCode*string

fullName*string

streetNamestring

civicNumberstring

postalCodestring

citystring

provincestring

regionstring

countrystring

Pattern: [A-Z]{2}

emailstring

phonestring

switchToExpiredboolean

feature flag to enable the debt position to expire after the due date

Example: false

companyName*string

officeNamestring

validityDatestring (date-time)

paymentDatestring (date-time)

statusenum

DRAFTPUBLISHEDVALIDINVALIDEXPIREDPARTIALLY_PAIDPAIDREPORTED

paymentOptionarray of PaymentOptionModel (object)

Request

Response

L'invalidazione di una posizione debitore consiste di fatto in una cancellazione logica. E' possibile solo partendo dagli stati PUBLISHED e VALID.

La funzionalità è utile quando si vuole dare evidenza all'utente, in fase di pagamento, della invalidazione della posizione debitoria.

Ricevute di pagamento

Sono messe a disposizione due API per il recupero delle ricevute di pagamento:

lista ricevute di pagamento
dettaglio singola ricevuta

Return the list of the organization receipts.

GEThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

Query parameters

Header parameters

Response

Obtained all organization payment positions.

Headers

Body

receipts_list*array of ReceiptModelResponse (object)

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts?pageNum=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "receipts_list": [
    {
      "organizationFiscalCode": "text",
      "iuv": "text",
      "debtor": "text",
      "paymentDateTime": "text",
      "status": "text"
    }
  ]
}

Return the details of a specific receipt.

GEThttps://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts/{iuv}

Authorization

Path parameters

organizationfiscalcode*string

Organization fiscal code, the fiscal code of the Organization.

Example: 12345

iuv*string

IUV (Unique Payment Identification). Alphanumeric code that uniquely associates and identifies three key elements of a payment: reason, payer, amount

Example: "ABC123"

Query parameters

Header parameters

Response

Obtained receipt details.

Headers

Body

string

Request

const response = await fetch('https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts/{iuv}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

text

Flussi di rendicontazione

Sono messe a disposizione delle funzionalità di lettura dei flussi di rendicontazione:

Lista di flussi di rendicontazione per un Ente Creditore
Dettaglio del flusso di rendicontazione

L'abilitazione al servizio per la gestione dei flussi di rendicontazione su GPD non è automatico e va richiesto esplicitamente al momento dell'on-boarding dell'EC

getFlowList

GEThttps://api.uat.platform.pagopa.it/gpd-reporting/api/v1/organizations/{organizationId}/reportings

Path parameters

organizationId*string

Response

Successful response

Body

flowIdstring

Example: "2022-01-12PPAYITR1XXX-S079177254"

flowDatestring

Example: "2022-01-12T00:31:05"

Request

Response

getFlow

GEThttps://api.uat.platform.pagopa.it/gpd-reporting/api/v1/organizations/{organizationId}/reportings/{flowId}/date/{date}

Path parameters

organizationId*string

flowId*string

date*string

Response

Successful response

Body

string (binary)

Flow XML

Request

Response

PreviousGestione massiva tramite SFTP NextPOS Fisici