Operazioni disponibili

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.

post

/organizations/{organizationfiscalcode}/debtpositions

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

Query parameters
toPublishboolean
Header parameters
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Body
iupdstringrequired
acaboolean
fiscalCodestringrequired
fullNamestringrequired
streetNamestring
civicNumberstring
postalCodestring
citystring
provincestring
regionstring
countrystring
Pattern: [A-Z]{2}
emailstring
phonestring
companyNamestringrequired
officeNamestring
validityDatestring date-time
paymentDatestring date-time
typeenumrequired
Options: F, G
payStandInboolean

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

Example: true
switchToExpiredbooleanrequired

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

Example: false
statusenum
Options: DRAFT, PUBLISHED, VALID, INVALID, EXPIRED, PARTIALLY_PAID, PAID, REPORTED
paymentOptionobject[]
Responses
curl -L \
  --request POST \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"iupd":"text","aca":false,"fiscalCode":"text","fullName":"text","companyName":"text","type":"F","payStandIn":true,"switchToExpired":false,"status":"DRAFT","paymentOption":[{"iuv":"text","amount":1,"description":"text","isPartialPayment":true,"dueDate":"2025-02-13T21:35:17.642Z","transfer":[{"amount":1,"remittanceInformation":"text","category":"text","stamp":{"hashDocument":"text","stampType":"text","provincialResidence":"RM"},"idTransfer":"1","organizationFiscalCode":"00000000000","iban":"IT0000000000000000000000000","postalIban":"IT0000000000000000000000000","transferMetadata":[{"key":"text"}]}],"paymentOptionMetadata":[{"key":"text"}]}]}'
{
  "iupd": "text",
  "aca": false,
  "fiscalCode": "text",
  "fullName": "text",
  "streetName": "text",
  "civicNumber": "text",
  "postalCode": "text",
  "city": "text",
  "province": "text",
  "region": "text",
  "country": "text",
  "email": "text",
  "phone": "text",
  "companyName": "text",
  "officeName": "text",
  "validityDate": "2025-02-13T21:35:17.642Z",
  "paymentDate": "2025-02-13T21:35:17.642Z",
  "type": "F",
  "payStandIn": true,
  "switchToExpired": false,
  "status": "DRAFT",
  "paymentOption": [
    {
      "iuv": "text",
      "amount": 1,
      "description": "text",
      "isPartialPayment": true,
      "dueDate": "2025-02-13T21:35:17.642Z",
      "transfer": [
        {
          "amount": 1,
          "remittanceInformation": "text",
          "category": "text",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "idTransfer": "1",
          "organizationFiscalCode": "00000000000",
          "iban": "IT0000000000000000000000000",
          "postalIban": "IT0000000000000000000000000",
          "transferMetadata": [
            {
              "key": "text"
            }
          ]
        }
      ],
      "paymentOptionMetadata": [
        {
          "key": "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_datevalidity_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.

get

/organizations/{organizationfiscalcode}/debtpositions

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

Query parameters
limitinteger int32

Number of elements on one page. Default = 50

pageinteger int32required

Page number. Page value starts from 0

due_date_fromstring date

Filter from due_date (if provided use the format yyyy-MM-dd). If not provided will be set to 30 days before the due_date_to.

due_date_tostring date

Filter to due_date (if provided use the format yyyy-MM-dd). If not provided will be set to 30 days after the due_date_from.

payment_date_fromstring date

Filter from payment_date (if provided use the format yyyy-MM-dd). If not provided will be set to 30 days before the payment_date_to.

payment_date_tostring date

Filter to payment_date (if provided use the format yyyy-MM-dd). If not provided will be set to 30 days after the payment_date_from

statusenum

Filter by debt position status

Options: DRAFT, PUBLISHED, VALID, INVALID, EXPIRED, PARTIALLY_PAID, PAID, REPORTED
orderbyenum

Order by INSERTED_DATE, COMPANY_NAME, IUPD or STATUS

Options: INSERTED_DATE, IUPD, STATUS, COMPANY_NAME
orderingenum

Direction of ordering

Options: ASC, DESC
Header parameters
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Responses
curl -L \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions?page=1' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY'
{
  "page_info": {
    "page": 1,
    "limit": 1,
    "items_found": 1,
    "total_pages": 1
  },
  "payment_position_list": [
    {
      "iupd": "text",
      "aca": false,
      "payStandIn": true,
      "organizationFiscalCode": "text",
      "companyName": "text",
      "officeName": "text",
      "insertedDate": "2025-02-13T21:35:17.642Z",
      "publishDate": "2025-02-13T21:35:17.642Z",
      "validityDate": "2025-02-13T21:35:17.642Z",
      "paymentDate": "2025-02-13T21:35:17.642Z",
      "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
      "type": "F",
      "status": "DRAFT",
      "paymentOption": [
        {
          "nav": "text",
          "iuv": "text",
          "organizationFiscalCode": "text",
          "amount": 1,
          "description": "text",
          "isPartialPayment": true,
          "dueDate": "2025-02-13T21:35:17.642Z",
          "retentionDate": "2025-02-13T21:35:17.642Z",
          "paymentDate": "2025-02-13T21:35:17.642Z",
          "reportingDate": "2025-02-13T21:35:17.642Z",
          "insertedDate": "2025-02-13T21:35:17.642Z",
          "paymentMethod": "text",
          "fee": 1,
          "notificationFee": 1,
          "pspCompany": "text",
          "idReceipt": "text",
          "idFlowReporting": "text",
          "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
          "status": "PO_UNPAID",
          "paymentOptionMetadata": [
            {
              "key": "text",
              "value": "text"
            }
          ],
          "transfer": [
            {
              "organizationFiscalCode": "text",
              "idTransfer": "text",
              "amount": 1,
              "remittanceInformation": "text",
              "category": "text",
              "iban": "text",
              "postalIban": "text",
              "stamp": {
                "hashDocument": "text",
                "stampType": "text",
                "provincialResidence": "RM"
              },
              "insertedDate": "2025-02-13T21:35:17.642Z",
              "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
              "status": "T_UNREPORTED",
              "transferMetadata": [
                {
                  "key": "text",
                  "value": "text"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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.

get

/organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

iupdstringrequired

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
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Responses
curl -L \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY'
{
  "iupd": "text",
  "aca": false,
  "payStandIn": true,
  "organizationFiscalCode": "text",
  "companyName": "text",
  "officeName": "text",
  "insertedDate": "2025-02-13T21:35:17.642Z",
  "publishDate": "2025-02-13T21:35:17.642Z",
  "validityDate": "2025-02-13T21:35:17.642Z",
  "paymentDate": "2025-02-13T21:35:17.642Z",
  "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
  "type": "F",
  "status": "DRAFT",
  "paymentOption": [
    {
      "nav": "text",
      "iuv": "text",
      "organizationFiscalCode": "text",
      "amount": 1,
      "description": "text",
      "isPartialPayment": true,
      "dueDate": "2025-02-13T21:35:17.642Z",
      "retentionDate": "2025-02-13T21:35:17.642Z",
      "paymentDate": "2025-02-13T21:35:17.642Z",
      "reportingDate": "2025-02-13T21:35:17.642Z",
      "insertedDate": "2025-02-13T21:35:17.642Z",
      "paymentMethod": "text",
      "fee": 1,
      "notificationFee": 1,
      "pspCompany": "text",
      "idReceipt": "text",
      "idFlowReporting": "text",
      "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
      "status": "PO_UNPAID",
      "paymentOptionMetadata": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "transfer": [
        {
          "organizationFiscalCode": "text",
          "idTransfer": "text",
          "amount": 1,
          "remittanceInformation": "text",
          "category": "text",
          "iban": "text",
          "postalIban": "text",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "insertedDate": "2025-02-13T21:35:17.642Z",
          "lastUpdatedDate": "2025-02-13T21:35:17.642Z",
          "status": "T_UNREPORTED",
          "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

put

/organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

iupdstringrequired

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.

Query parameters
toPublishboolean
Header parameters
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Body
iupdstringrequired
acaboolean
fiscalCodestringrequired
fullNamestringrequired
streetNamestring
civicNumberstring
postalCodestring
citystring
provincestring
regionstring
countrystring
Pattern: [A-Z]{2}
emailstring
phonestring
companyNamestringrequired
officeNamestring
validityDatestring date-time
paymentDatestring date-time
typeenumrequired
Options: F, G
payStandInboolean

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

Example: true
switchToExpiredbooleanrequired

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

Example: false
statusenum
Options: DRAFT, PUBLISHED, VALID, INVALID, EXPIRED, PARTIALLY_PAID, PAID, REPORTED
paymentOptionobject[]
Responses
curl -L \
  --request PUT \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1//organizations/{organizationfiscalcode}/debtpositions/{iupd}' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"iupd":"text","aca":false,"fiscalCode":"text","fullName":"text","companyName":"text","type":"F","payStandIn":true,"switchToExpired":false,"status":"DRAFT","paymentOption":[{"iuv":"text","amount":1,"description":"text","isPartialPayment":true,"dueDate":"2025-02-13T21:35:17.642Z","transfer":[{"amount":1,"remittanceInformation":"text","category":"text","stamp":{"hashDocument":"text","stampType":"text","provincialResidence":"RM"},"idTransfer":"1","organizationFiscalCode":"00000000000","iban":"IT0000000000000000000000000","postalIban":"IT0000000000000000000000000","transferMetadata":[{"key":"text"}]}],"paymentOptionMetadata":[{"key":"text"}]}]}'
{
  "iupd": "text",
  "aca": false,
  "fiscalCode": "text",
  "fullName": "text",
  "streetName": "text",
  "civicNumber": "text",
  "postalCode": "text",
  "city": "text",
  "province": "text",
  "region": "text",
  "country": "text",
  "email": "text",
  "phone": "text",
  "companyName": "text",
  "officeName": "text",
  "validityDate": "2025-02-13T21:35:17.642Z",
  "paymentDate": "2025-02-13T21:35:17.642Z",
  "type": "F",
  "payStandIn": true,
  "switchToExpired": false,
  "status": "DRAFT",
  "paymentOption": [
    {
      "iuv": "text",
      "amount": 1,
      "description": "text",
      "isPartialPayment": true,
      "dueDate": "2025-02-13T21:35:17.642Z",
      "transfer": [
        {
          "amount": 1,
          "remittanceInformation": "text",
          "category": "text",
          "stamp": {
            "hashDocument": "text",
            "stampType": "text",
            "provincialResidence": "RM"
          },
          "idTransfer": "1",
          "organizationFiscalCode": "00000000000",
          "iban": "IT0000000000000000000000000",
          "postalIban": "IT0000000000000000000000000",
          "transferMetadata": [
            {
              "key": "text"
            }
          ]
        }
      ],
      "paymentOptionMetadata": [
        {
          "key": "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)

Cancellazione di una Posizione Debitoria

The Organization deletes a debt position

delete

/organizations/{organizationfiscalcode}/debtpositions/{iupd}

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

iupdstringrequired

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
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Responses
curl -L \
  --request DELETE \
  --url 'https://api.uat.platform.pagopa.it/gpd/api/v1/organizations/{organizationfiscalcode}/debtpositions/{iupd}' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY'
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

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

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.

get

/payments/{organizationfiscalcode}/receipts

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

Query parameters
pageNuminteger int32required

Page number

pageSizeinteger int32

Number of elements per page. Default = 50

debtorstring

Filter by debtor

servicestring

Filter by service

fromstring

Filter by date, from this date

tostring

Filter by date, to this date

segregationCodesstring

Segregation codes for which broker is authorized

Pattern: \d{2}(,\d{2})*
Header parameters
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Responses
curl -L \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts?pageNum=1' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY'
{
  "receipts_list": [
    {
      "organizationFiscalCode": "text",
      "iuv": "text",
      "debtor": "text",
      "paymentDateTime": "text",
      "status": "text"
    }
  ]
}

Return the details of a specific receipt.

get

/payments/{organizationfiscalcode}/receipts/{iuv}

Authorizations
Path parameters
organizationfiscalcodestringrequired

Organization fiscal code, the fiscal code of the Organization.

Example: 12345
iuvstringrequired

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

Example: ABC123
Query parameters
segregationCodesstring

Segregation codes for which broker is authorized

Pattern: \d{2}(,\d{2})*
Header parameters
X-Request-Idstring

This header identifies the call, if not passed it is self-generated. This ID is returned in the response.

Responses
curl -L \
  --url 'https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1/payments/{organizationfiscalcode}/receipts/{iuv}' \
  --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY'
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