{ "openapi": "3.1.0", "info": { "title": "PagoPA API Debt Position", "description": "Progetto Gestione Posizioni Debitorie", "termsOfService": "https://www.pagopa.gov.it/", "version": "1.1.17" }, "servers": [ { "url": "https://api.uat.platform.pagopa.it/gpd/debt-positions-service/v1", "description": "GPD Test environment" }, { "url": "https://api.platform.pagopa.it/gpd/debt-positions-service/v1", "description": "GPD Production Environment" } ], "paths": { "/organizations/{organizationfiscalcode}/debtpositions": { "get": { "tags": [ "Debt Positions API" ], "summary": "Return the list of the organization debt positions. The due dates interval is mutually exclusive with the payment dates interval.", "description": "Return the list of the organization debt positions. The due dates interval is mutually exclusive with the payment dates interval.", "operationId": "getOrganizationDebtPositions", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of elements on one page. Default = 50", "schema": { "maximum": 50, "type": "integer", "format": "int32", "default": 10 } }, { "name": "page", "in": "query", "description": "Page number. Page value starts from 0", "schema": { "minimum": 0, "type": "integer", "format": "int32", "default": 0 } }, { "name": "due_date_from", "in": "query", "description": "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.", "schema": { "type": "string", "format": "date" } }, { "name": "due_date_to", "in": "query", "description": "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.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_from", "in": "query", "description": "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.", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_to", "in": "query", "description": "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", "schema": { "type": "string", "format": "date" } }, { "name": "payment_date_time_from", "in": "query", "description": "Filter from payment_date_time (if provided use the format yyyy-MM-ddTHH:mm:ss). If not provided will be set to 30 days before the payment_date_time_from.", "schema": { "type": "string", "format": "date-time" } }, { "name": "payment_date_time_to", "in": "query", "description": "Filter to payment_date_time (if provided use the format yyyy-MM-ddTHH:mm:ss). If not will be set to 30 days after the payment_date_time_to.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Filter by debt position status", "schema": { "enum": [ "DRAFT", "PUBLISHED", "VALID", "INVALID", "EXPIRED", "PARTIALLY_PAID", "PAID", "REPORTED" ], "type": "string" } }, { "name": "orderby", "in": "query", "description": "Order by INSERTED_DATE, COMPANY_NAME, IUPD or STATUS", "schema": { "enum": [ "INSERTED_DATE", "IUPD", "STATUS", "COMPANY_NAME" ], "type": "string", "default": "INSERTED_DATE" } }, { "name": "ordering", "in": "query", "description": "Direction of ordering", "schema": { "enum": [ "ASC", "DESC" ], "type": "string", "default": "DESC" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Obtained all organization payment positions.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionsInfo" }, "example": { "payment_position_list": [ { "iupd": "string", "organizationFiscalCode": "string", "type": "F", "companyName": "string", "officeName": "string", "insertedDate": "string", "publishDate": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "lastUpdatedDate": "string", "paymentOption": [ { "nav": "string", "iuv": "string", "organizationFiscalCode": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "paymentDate": "string", "reportingDate": "string", "insertedDate": "string", "paymentMethod": "string", "fee": 0, "notificationFee": 0, "pspCompany": "string", "idReceipt": "string", "idFlowReporting": "string", "status": "PO_UNPAID", "lastUpdatedDate": "string", "paymentOptionMetadata": [ { "key": "string", "value": "string" } ], "transfer": [ { "organizationFiscalCode": "string", "companyName": "string", "idTransfer": "string", "amount": 0, "remittanceInformation": "string", "category": "string", "iban": "string", "postalIban": "string", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "insertedDate": "string", "status": "T_UNREPORTED", "lastUpdatedDate": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ] } ] } ], "page_info": { "page": 0, "limit": 0, "items_found": 0, "total_pages": 0 } } } } }, "400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "429": { "description": "Too many requests.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } }, "post": { "tags": [ "Debt Positions API" ], "summary": "The Organization creates a debt Position.", "description": "The Organization creates a debt Position.", "operationId": "createPosition", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "toPublish", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "responses": { "201": { "description": "Request created.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "409": { "description": "Conflict: duplicate debt position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } }, "/organizations/{organizationfiscalcode}/debtpositions/{iupd}": { "get": { "tags": [ "Debt Positions API" ], "summary": "Return the details of a specific debt position.", "description": "Return the details of a specific debt position.", "operationId": "getOrganizationDebtPositionByIUPD", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "pattern": "[\\w*\\h-]+", "type": "string" } }, { "name": "iupd", "in": "path", "description": "IUPD (Unique identifier of the debt position). Format could be `` 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.", "required": true, "schema": { "pattern": "[\\w*\\h-]+", "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Obtained debt position details.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModelBaseResponse" }, "example": { "iupd": "string", "organizationFiscalCode": "string", "type": "F", "companyName": "string", "officeName": "string", "insertedDate": "string", "publishDate": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "lastUpdatedDate": "string", "paymentOption": [ { "nav": "string", "iuv": "string", "organizationFiscalCode": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "paymentDate": "string", "reportingDate": "string", "insertedDate": "string", "paymentMethod": "string", "fee": 0, "notificationFee": 0, "pspCompany": "string", "idReceipt": "string", "idFlowReporting": "string", "status": "PO_UNPAID", "lastUpdatedDate": "string", "paymentOptionMetadata": [ { "key": "string", "value": "string" } ], "transfer": [ { "organizationFiscalCode": "string", "companyName": "string", "idTransfer": "string", "amount": 0, "remittanceInformation": "string", "category": "string", "iban": "string", "postalIban": "string", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "insertedDate": "string", "status": "T_UNREPORTED", "lastUpdatedDate": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ] } ] } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "404": { "description": "No debt position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } }, "put": { "tags": [ "Debt Positions API" ], "summary": "The Organization updates a debt position ", "description": "The Organization updates a debt position ", "operationId": "updatePosition", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "iupd", "in": "path", "description": "IUPD (Unique identifier of the debt position). Format could be `` 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.", "required": true, "schema": { "type": "string" } }, { "name": "toPublish", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "responses": { "200": { "description": "Debt Position updated.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "404": { "description": "No debt position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "409": { "description": "Conflict: existing related payment found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } }, "delete": { "tags": [ "Debt Positions API" ], "summary": "The Organization deletes a debt position", "description": "The Organization deletes a debt position", "operationId": "deletePosition", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "pattern": "[\\w*\\h-]+", "type": "string" } }, { "name": "iupd", "in": "path", "description": "IUPD (Unique identifier of the debt position). Format could be `` 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.", "required": true, "schema": { "pattern": "[\\w*\\h-]+", "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "string" }, "example": "string" } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "404": { "description": "No debt position position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "409": { "description": "Conflict: existing related payment found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } }, "/organizations/{organizationfiscalcode}/debtpositions/{iupd}/invalidate": { "post": { "tags": [ "Debt Position Actions API" ], "summary": "The Organization invalidate a debt Position.", "description": "The Organization invalidate a debt Position.", "operationId": "invalidatePosition", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "iupd", "in": "path", "description": "IUPD (Unique identifier of the debt position). Format could be `` 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.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request published.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "404": { "description": "No debt position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "409": { "description": "Conflict: debt position is not in invalidable state.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } }, "/organizations/{organizationfiscalcode}/debtpositions/{iupd}/publish": { "post": { "tags": [ "Debt Position Actions API" ], "summary": "The Organization publish a debt Position.", "description": "The Organization publish a debt Position.", "operationId": "publishPosition", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "iupd", "in": "path", "description": "IUPD (Unique identifier of the debt position). Format could be `` 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.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request published.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPositionModel" }, "example": { "iupd": "string", "type": "F", "payStandIn": "true", "fiscalCode": "string", "fullName": "string", "streetName": "string", "civicNumber": "string", "postalCode": "string", "city": "string", "province": "string", "region": "string", "country": "IT", "email": "email@domain.com", "phone": "string", "switchToExpired": "false", "companyName": "string", "officeName": "string", "validityDate": "string", "paymentDate": "string", "status": "DRAFT", "paymentOption": [ { "nav": "string", "iuv": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "fee": 0, "notificationFee": 0, "transfer": [ { "idTransfer": "1", "amount": 0, "organizationFiscalCode": "00000000000", "remittanceInformation": "string", "category": "string", "iban": "IT0000000000000000000000000", "postalIban": "IT0000000000000000000000000", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "companyName": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "paymentOptionMetadata": [ { "key": "string", "value": "string" } ] } ] } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "404": { "description": "No debt position found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "409": { "description": "Conflict: debt position is not in publishable state.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } }, "/organizations/{organizationfiscalcode}/debtpositions/transfers": { "patch": { "tags": [ "Debt Positions API" ], "summary": "The Organization updates the IBANs of every updatable payment option's transfers", "description": "The Organization updates the IBANs of every updatable payment option's transfers", "operationId": "updateTransferIbanMassive", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "oldIban", "in": "query", "description": "The old iban to replace", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of Transfer to update (max = 1000, default = 1000)", "schema": { "maximum": 1000, "type": "integer", "format": "int32", "default": 1000 } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransferIbanMassiveModel" }, "example": { "newIban": "string" } } } }, "responses": { "200": { "description": "IBANs updated", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransferIbanMassiveResponse" }, "example": { "description": "string", "updatedTransfers": 0 } } } }, "400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "statusCode": 403, "message": "You are not allowed to access this resource." } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } }, "/organizations/{organizationfiscalcode}/paymentoptions/paids/{nav}": { "post": { "tags": [ "Payments API" ], "summary": "The Organization mark a payment option as already paid.", "description": "The Organization mark a payment option as already paid.", "operationId": "setPaymentOptionAsAlreadyPaid", "parameters": [ { "name": "organizationfiscalcode", "in": "path", "description": "Organization fiscal code, the fiscal code of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "nav", "in": "path", "description": "NAV (notice number) is the unique reference assigned to the payment by a creditor institution.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "This header identifies the call, if not passed it is self-generated. This ID is returned in the response.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlreadyPaidPaymentOptionModel" }, "example": { "paymentDate": "string" } } } }, "responses": { "200": { "description": "Request set as paid.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsModelResponse" }, "example": { "nav": "string", "iuv": "string", "organizationFiscalCode": "string", "amount": 0, "description": "string", "isPartialPayment": true, "dueDate": "string", "retentionDate": "string", "paymentDate": "string", "reportingDate": "string", "insertedDate": "string", "paymentMethod": "string", "fee": 0, "notificationFee": 0, "pspCompany": "string", "idReceipt": "string", "idFlowReporting": "string", "status": "PO_UNPAID", "lastUpdatedDate": "string", "lastUpdatedDateNotificationFee": "string", "paymentOptionMetadata": [ { "key": "string", "value": "string" } ], "transfer": [ { "organizationFiscalCode": "string", "companyName": "string", "idTransfer": "string", "amount": 0, "remittanceInformation": "string", "category": "string", "iban": "string", "postalIban": "string", "stamp": { "hashDocument": "string", "stampType": "string", "provincialResidence": "RM" }, "insertedDate": "string", "status": "T_UNREPORTED", "lastUpdatedDate": "string", "transferMetadata": [ { "key": "string", "value": "string" } ] } ], "serviceType": "string" } } } }, "400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "401": { "description": "Wrong or missing function key.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } } }, "404": { "description": "No payment option found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "409": { "description": "Conflict: existing related payment found.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "422": { "description": "Unprocessable: not in payable state.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } }, "500": { "description": "Service unavailable.", "headers": { "X-Request-Id": { "description": "This header identifies the call", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemJson" }, "example": { "title": "string", "status": 200, "detail": "There was an error processing the request" } } } } } } } }, "components": { "schemas": { "PaymentOptionMetadataModel": { "required": [ "key", "value" ], "type": "object", "properties": { "key": { "maxLength": 140, "minLength": 0, "type": "string" }, "value": { "maxLength": 140, "minLength": 0, "type": "string" } } }, "PaymentOptionModel": { "required": [ "amount", "description", "dueDate", "isPartialPayment", "iuv" ], "type": "object", "properties": { "nav": { "type": "string" }, "iuv": { "type": "string" }, "amount": { "minimum": 1, "type": "integer", "format": "int64" }, "description": { "maxLength": 140, "minLength": 0, "type": "string" }, "isPartialPayment": { "type": "boolean" }, "dueDate": { "type": "string", "format": "date-time" }, "retentionDate": { "type": "string", "format": "date-time" }, "fee": { "type": "integer", "format": "int64", "readOnly": true }, "notificationFee": { "type": "integer", "format": "int64", "readOnly": true }, "transfer": { "maxItems": 5, "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/TransferModel" } }, "paymentOptionMetadata": { "maxItems": 10, "minItems": 0, "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/PaymentOptionMetadataModel" }, "description": "It can be added a maximum of 10 key-value pairs for metadata. Metadata keys must be unique within the same payment option." } } }, "PaymentPositionModel": { "required": [ "companyName", "fiscalCode", "fullName", "iupd", "switchToExpired", "type" ], "type": "object", "properties": { "iupd": { "type": "string" }, "type": { "enum": [ "F", "G" ], "type": "string" }, "payStandIn": { "type": "boolean", "description": "feature flag to enable a debt position in stand-in mode", "default": "true", "example": true }, "fiscalCode": { "type": "string" }, "fullName": { "type": "string" }, "streetName": { "type": "string" }, "civicNumber": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "region": { "type": "string" }, "country": { "pattern": "[A-Z]{2}", "type": "string", "example": "IT" }, "email": { "type": "string", "example": "email@domain.com" }, "phone": { "type": "string" }, "switchToExpired": { "type": "boolean", "description": "feature flag to enable the debt position to expire after the due date", "default": "false", "example": false }, "companyName": { "maxLength": 140, "minLength": 0, "type": "string" }, "officeName": { "maxLength": 140, "minLength": 0, "type": "string" }, "validityDate": { "type": "string", "format": "date-time" }, "paymentDate": { "type": "string", "format": "date-time", "readOnly": true }, "status": { "enum": [ "DRAFT", "PUBLISHED", "VALID", "INVALID", "EXPIRED", "PARTIALLY_PAID", "PAID", "REPORTED" ], "type": "string", "readOnly": true }, "paymentOption": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOptionModel" } } } }, "Stamp": { "required": [ "hashDocument", "provincialResidence", "stampType" ], "type": "object", "properties": { "hashDocument": { "maxLength": 72, "minLength": 0, "type": "string", "description": "Document hash type is stBase64Binary72 as described in https://github.com/pagopa/pagopa-api." }, "stampType": { "maxLength": 2, "minLength": 2, "type": "string", "description": "The type of the stamp" }, "provincialResidence": { "pattern": "[A-Z]{2}", "type": "string", "description": "The provincial of the residence", "example": "RM" } } }, "TransferMetadataModel": { "required": [ "key", "value" ], "type": "object", "properties": { "key": { "maxLength": 140, "minLength": 0, "type": "string" }, "value": { "maxLength": 140, "minLength": 0, "type": "string" } } }, "TransferModel": { "required": [ "amount", "category", "idTransfer", "remittanceInformation" ], "type": "object", "properties": { "idTransfer": { "enum": [ "1", "2", "3", "4", "5" ], "type": "string" }, "amount": { "minimum": 1, "type": "integer", "format": "int64" }, "organizationFiscalCode": { "type": "string", "description": "Fiscal code related to the organization targeted by this transfer.", "example": "00000000000" }, "remittanceInformation": { "maxLength": 140, "minLength": 0, "type": "string" }, "category": { "type": "string" }, "iban": { "maxLength": 35, "minLength": 1, "pattern": "^[A-Za-z0-9]{1,35}$", "type": "string", "description": "mutual exclusive with stamp", "example": "IT0000000000000000000000000" }, "postalIban": { "maxLength": 35, "minLength": 1, "pattern": "^$|^[A-Za-z0-9]{1,35}$", "type": "string", "description": "optional - can be combined with iban but not with stamp", "example": "IT0000000000000000000000000" }, "stamp": { "$ref": "#/components/schemas/Stamp" }, "companyName": { "maxLength": 140, "minLength": 0, "type": "string" }, "transferMetadata": { "maxItems": 10, "minItems": 0, "uniqueItems": true, "type": "array", "items": { "$ref": "#/components/schemas/TransferMetadataModel" }, "description": "It can be added a maximum of 10 key-value pairs for metadata. Metadata keys must be unique within the same transfer." } } }, "ProblemJson": { "type": "object", "properties": { "title": { "type": "string", "description": "A short, summary of the problem type. Written in english and readable for engineers (usually not suited for non technical stakeholders and not localized); example: Service Unavailable" }, "status": { "maximum": 600, "minimum": 100, "type": "integer", "description": "The HTTP status code generated by the origin server for this occurrence of the problem.", "format": "int32", "example": 200 }, "detail": { "type": "string", "description": "A human readable explanation specific to this occurrence of the problem.", "example": "There was an error processing the request" } } }, "AlreadyPaidPaymentOptionModel": { "type": "object", "properties": { "paymentDate": { "type": "string", "format": "date-time" } } }, "PaymentOptionMetadataModelResponse": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "PaymentsModelResponse": { "type": "object", "properties": { "nav": { "type": "string" }, "iuv": { "type": "string" }, "organizationFiscalCode": { "type": "string" }, "amount": { "type": "integer", "format": "int64" }, "description": { "type": "string" }, "isPartialPayment": { "type": "boolean" }, "dueDate": { "type": "string", "format": "date-time" }, "retentionDate": { "type": "string", "format": "date-time" }, "paymentDate": { "type": "string", "format": "date-time" }, "reportingDate": { "type": "string", "format": "date-time" }, "insertedDate": { "type": "string", "format": "date-time" }, "paymentMethod": { "type": "string" }, "fee": { "type": "integer", "format": "int64" }, "notificationFee": { "type": "integer", "format": "int64" }, "pspCompany": { "type": "string" }, "idReceipt": { "type": "string" }, "idFlowReporting": { "type": "string" }, "status": { "enum": [ "PO_UNPAID", "PO_PAID", "PO_PARTIALLY_REPORTED", "PO_REPORTED" ], "type": "string" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "lastUpdatedDateNotificationFee": { "type": "string", "format": "date-time" }, "paymentOptionMetadata": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOptionMetadataModelResponse" } }, "transfer": { "type": "array", "items": { "$ref": "#/components/schemas/TransferModelResponse" } }, "serviceType": { "type": "string" } } }, "TransferMetadataModelResponse": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "TransferModelResponse": { "type": "object", "properties": { "organizationFiscalCode": { "type": "string" }, "companyName": { "type": "string" }, "idTransfer": { "type": "string" }, "amount": { "type": "integer", "format": "int64" }, "remittanceInformation": { "type": "string" }, "category": { "type": "string" }, "iban": { "type": "string" }, "postalIban": { "type": "string" }, "stamp": { "$ref": "#/components/schemas/Stamp" }, "insertedDate": { "type": "string", "format": "date-time" }, "status": { "enum": [ "T_UNREPORTED", "T_REPORTED" ], "type": "string" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "transferMetadata": { "type": "array", "items": { "$ref": "#/components/schemas/TransferMetadataModelResponse" } } } }, "UpdateTransferIbanMassiveModel": { "required": [ "newIban" ], "type": "object", "properties": { "newIban": { "type": "string" } } }, "UpdateTransferIbanMassiveResponse": { "type": "object", "properties": { "description": { "type": "string" }, "updatedTransfers": { "type": "integer", "format": "int32" } } }, "PageInfo": { "required": [ "items_found", "limit", "page", "total_pages" ], "type": "object", "properties": { "page": { "type": "integer", "description": "Page number", "format": "int32" }, "limit": { "type": "integer", "description": "Required number of items per page", "format": "int32" }, "items_found": { "type": "integer", "description": "Number of items found. (The last page may have fewer elements than required)", "format": "int32" }, "total_pages": { "type": "integer", "description": "Total number of pages", "format": "int32" } } }, "PaymentOptionModelResponse": { "type": "object", "properties": { "nav": { "type": "string" }, "iuv": { "type": "string" }, "organizationFiscalCode": { "type": "string" }, "amount": { "type": "integer", "format": "int64" }, "description": { "type": "string" }, "isPartialPayment": { "type": "boolean" }, "dueDate": { "type": "string", "format": "date-time" }, "retentionDate": { "type": "string", "format": "date-time" }, "paymentDate": { "type": "string", "format": "date-time" }, "reportingDate": { "type": "string", "format": "date-time" }, "insertedDate": { "type": "string", "format": "date-time" }, "paymentMethod": { "type": "string" }, "fee": { "type": "integer", "format": "int64" }, "notificationFee": { "type": "integer", "format": "int64" }, "pspCompany": { "type": "string" }, "idReceipt": { "type": "string" }, "idFlowReporting": { "type": "string" }, "status": { "enum": [ "PO_UNPAID", "PO_PAID", "PO_PARTIALLY_REPORTED", "PO_REPORTED" ], "type": "string" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "paymentOptionMetadata": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOptionMetadataModelResponse" } }, "transfer": { "type": "array", "items": { "$ref": "#/components/schemas/TransferModelResponse" } } } }, "PaymentPositionModelBaseResponse": { "type": "object", "properties": { "iupd": { "type": "string" }, "organizationFiscalCode": { "type": "string" }, "type": { "enum": [ "F", "G" ], "type": "string" }, "companyName": { "type": "string" }, "officeName": { "type": "string" }, "insertedDate": { "type": "string", "format": "date-time" }, "publishDate": { "type": "string", "format": "date-time" }, "validityDate": { "type": "string", "format": "date-time" }, "paymentDate": { "type": "string", "format": "date-time" }, "status": { "enum": [ "DRAFT", "PUBLISHED", "VALID", "INVALID", "EXPIRED", "PARTIALLY_PAID", "PAID", "REPORTED" ], "type": "string" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "paymentOption": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentOptionModelResponse" } } } }, "PaymentPositionsInfo": { "required": [ "page_info", "payment_position_list" ], "type": "object", "properties": { "payment_position_list": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentPositionModelBaseResponse" } }, "page_info": { "$ref": "#/components/schemas/PageInfo" } } }, "AppInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "environment": { "type": "string" } } } }, "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "name": "Ocp-Apim-Subscription-Key", "in": "header" }, "apiKeyQuery": { "type": "apiKey", "name": "subscription-key", "in": "query" } } }, "security": [ { "apiKeyHeader": [] }, { "apiKeyQuery": [] } ], "tags": [ { "name": "Debt Positions API" }, { "name": "Debt Position Actions API" } ] }