Operazioni disponibili
Last updated
Last updated
Tutte le operazioni indicate sono segregate per codice fiscale dell'ente creditore (organizationfiscalcode). Il dato è recuperato in autonomia dal servizio partendo dalla subscription key utilizzata.
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.
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.4.0/openapi.
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.
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.
La lettura di una posizione debitoria si basa sull'identificativo in input (IUPD). In caso lo IUPD non sia esistente verrà emesso un errore.
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)
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)
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.
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.
Sono messe a disposizione due API per il recupero delle ricevute di pagamento:
lista ricevute di pagamento
dettaglio singola ricevuta
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
Organization fiscal code, the fiscal code of the Organization.
Number of elements on one page
Page number. Page value starts from 0
Filter by debtor
Filter by service
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
Organization fiscal code, the fiscal code of the Organization.
IUV (Unique Payment Identification). Alphanumeric code that uniquely associates and identifies three key elements of a payment: reason, payer, amount
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
Return the list of the organization debt positions.
Organization fiscal code, the fiscal code of the Organization.
Format - int32. Page number. Page value starts from 0
Format - date (as full-date in RFC3339). Filter from due_date (if provided use the format yyyy-MM-dd)
Format - date (as full-date in RFC3339). Filter to due_date (if provided use the format yyyy-MM-dd)
Format - int32. Number of elements on one page. Default = 50
Order by INSERTED_DATE, COMPANY_NAME, IUPD or STATUS
INSERTED_DATE, IUPD, STATUS, COMPANY_NAMEDirection of ordering
ASC, DESCThis header identifies the call, if not passed it is self-generated. This ID is returned in the response.
Return the details of a specific debt position.
Organization fiscal code, the fiscal code of the Organization.
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.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
The Organization deletes a debt position
Organization fiscal code, the fiscal code of the Organization.
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.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
The Organization publish a debt Position.
Organization fiscal code, the fiscal code of the Organization.
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.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
The Organization invalidate a debt Position.
Organization fiscal code, the fiscal code of the Organization.
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.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
The Organization creates a debt Position.
Organization fiscal code, the fiscal code of the Organization.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
F, Gfeature flag to enable the debt position to expire after the due date
falseDRAFT, PUBLISHED, VALID, INVALID, EXPIRED, PARTIALLY_PAID, PAID, REPORTEDThe Organization updates a debt position
Organization fiscal code, the fiscal code of the Organization.
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.
This header identifies the call, if not passed it is self-generated. This ID is returned in the response.
F, Gfeature flag to enable the debt position to expire after the due date
falseDRAFT, PUBLISHED, VALID, INVALID, EXPIRED, PARTIALLY_PAID, PAID, REPORTED