PagoPA Notice Generation Request APIs API

openapi: 3.2.0
info:
  title: External Payment Notices Print Service Notice Generation…
  description: External Payment Notices Print Service APIs
  termsOfService: https://www.pagopa.gov.it/
  version: 0.9.8
servers:
- url: https://api.platform.pagopa.it/print-payment-notice-service/external/v1
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Notice Generation Request APIs
paths:
  /notices/folder/{folderId}:
    delete:
      tags:
      - Notice Generation Request APIs
      summary: deleteFolder
      description: Delete selected folder, if allowed
      operationId: deleteFolder
      parameters:
      - name: folderId
        in: path
        description: folderId to use for request retrieval
        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: Folder Deleted
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Folder not found
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
        '500':
          description: Service error
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '503':
          description: Service or notice storage unavailable
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/folder/{folderId}/file/{fileId}/url:
    get:
      tags:
      - Notice Generation Request APIs
      summary: getSignedUrlResource
      description: Return file signedUrl
      operationId: getSignedUrlResource
      parameters:
      - name: folderId
        in: path
        description: folderId to use for request retrieval
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        description: fileId to use for request retrieval
        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: Return file signed url
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignedUrlResource'
              example:
                signedUrl: string
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Folder or file not found
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
        '500':
          description: Service error
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '503':
          description: Service or notice storage unavailable
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/folder/{folderId}/url:
    get:
      tags:
      - Notice Generation Request APIs
      summary: getFolderSignedUrlResource
      description: Return compressed folder file signedUrl
      operationId: getFolderSignedUrlResource
      parameters:
      - name: folderId
        in: path
        description: folderId to use for request retrieval
        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: Return folder signed url
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignedUrlResource'
              example:
                signedUrl: string
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Folder or file not found
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
        '500':
          description: Service error
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '503':
          description: Service or notice storage unavailable
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/folder/{folder_id}/status:
    get:
      tags:
      - Notice Generation Request APIs
      summary: getFolderStatus
      description: Return generation request status for a folder of notices
      operationId: getFolderStatus
      parameters:
      - name: folder_id
        in: path
        description: folderId to use for request status retrieval
        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: OK
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGenerationRequestStatusResource'
              example:
                noticesInError:
                - string
                processedNotices:
                - string
                status: INSERTED
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Folder not found or unavailable for the requirer
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '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:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/generate:
    post:
      tags:
      - Notice Generation Request APIs
      summary: generateNotice
      description: Request notice generation using the generator API and returns the pdf that has been producedif a folderId is provided and it is available for the userId, it will be saved for future recovery
      operationId: generateNotice
      parameters:
      - name: folderId
        in: query
        description: If the file exists you can specify the folder id. Pass it if you want to regenerate the file
        schema:
          type: string
          description: If the file exists you can specify the folder id. Pass it if you want to regenerate the file
      - 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/NoticeGenerationRequestItem'
            example:
              data:
                creditorInstitution:
                  taxCode: string
                debtor:
                  address: string
                  buildingNumber: string
                  city: string
                  fullName: string
                  postalCode: string
                  province: string
                  taxCode: string
                notice:
                  code: string
                  discounted:
                    amount: 0
                    code: string
                    dueDate: string
                  dueDate: string
                  installments:
                  - amount: 0
                    code: string
                    dueDate: string
                  paymentAmount: 0
                  reduced:
                    amount: 0
                    code: string
                    dueDate: string
                  subject: string
              templateId: string
      responses:
        '201':
          description: OK
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/pdf:
              schema:
                type: string
                format: binary
              examples:
                default:
                  value: null
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Institution Not Found
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
        '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:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/generate-massive:
    post:
      tags:
      - Notice Generation Request APIs
      summary: generateNoticeMassiveRequest
      description: Insert massive notice generation request and returns folderId for reference an future recovery
      operationId: generateNoticeMassiveRequest
      parameters:
      - 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
      - name: Idempotency-Key
        in: header
        description: key to be used for idempotency checks of pre-existing requests having the same key
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoticeGenerationMassiveRequest'
            example:
              notices:
              - data:
                  creditorInstitution:
                    taxCode: string
                  debtor:
                    address: string
                    buildingNumber: string
                    city: string
                    fullName: string
                    postalCode: string
                    province: string
                    taxCode: string
                  notice:
                    code: string
                    discounted:
                      amount: 0
                      code: string
                      dueDate: string
                    dueDate: string
                    installments:
                    - amount: 0
                      code: string
                      dueDate: string
                    paymentAmount: 0
                    reduced:
                      amount: 0
                      code: string
                      dueDate: string
                    subject: string
                templateId: string
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeGenerationMassiveResource'
              example:
                folder_id: string
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '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:
                detail: There was an error processing the request
                status: 200
                title: string
  /notices/folder/{folder_id}/error/{error_id}:
    get:
      tags:
      - Notice Generation Request APIs
      summary: getError
      description: Return error of an item inside a notice generation request
      operationId: GetErrorResource
      parameters:
      - name: folder_id
        in: path
        description: folderId to use for error detail retrieval
        required: true
        schema:
          type: string
      - name: error_id
        in: path
        description: errorId to use for error detail retrieval
        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: OK
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGenerationRequestStatusResource'
              example:
                noticesInError:
                - string
                processedNotices:
                - string
                status: INSERTED
        '400':
          description: Bad Request
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '401':
          description: Unauthorized
          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
        '404':
          description: Folder not found or unavailable for the requirer
          headers:
            X-Request-Id:
              description: This header identifies the call
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
              example:
                detail: There was an error processing the request
                status: 200
                title: string
        '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:
                detail: There was an error processing the request
                status: 200
                title: string
components:
  schemas:
    NoticeGenerationRequestItem:
      required:
      - data
      - templateId
      type: object
      properties:
        data:
          $ref: '#/components/schemas/NoticeRequestData'
        templateId:
          type: string
          description: The template identifier. Use the appropriate GET service to retrieve the list of the ids
      description: templateId to use for retrieval
    GetGenerationRequestStatusResource:
      required:
      - noticesInError
      - processedNotices
      - status
      type: object
      properties:
        noticesInError:
          type: array
          items:
            type: string
            description: items related to the request that produced an error
          description: items related to the request that produced an error
        processedNotices:
          type: array
          items:
            type: string
            description: Successfully processed items in request
          description: Successfully processed items in request
        status:
          enum:
          - INSERTED
          - PROCESSING
          - COMPLETING
          - FAILED
          - PROCESSED
          - PROCESSED_WITH_FAILURES
          type: string
          description: Generation request status
    NoticeGenerationMassiveResource:
      required:
      - folder_id
      type: object
      properties:
        folder_id:
          type: string
          description: Generation request folderId
    InstallmentData:
      required:
      - amount
      - code
      type: object
      properties:
        amount:
          maximum: 99999999999.0
          type: integer
          description: Installment amount
          format: int64
        code:
          maxLength: 18
          minLength: 18
          type: string
          description: Installment code
        dueDate:
          type: string
          description: Installment dueDate
      description: Notice reduced amount to pay (used in reduced amount for infractions).  Mandatory for CDS infraction notices
    GetSignedUrlResource:
      type: object
      properties:
        signedUrl:
          type: string
    NoticeGenerationMassiveRequest:
      required:
      - notices
      type: object
      properties:
        notices:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/NoticeGenerationRequestItem'
      description: massive notice generation request data
    Debtor:
      required:
      - address
      - buildingNumber
      - city
      - fullName
      - postalCode
      - province
      type: object
      properties:
        address:
          maxLength: 140
          minLength: 0
          type: string
          description: Debtor address
        buildingNumber:
          type: string
          description: Debtor building number
        city:
          type: string
          description: Debtor city
        fullName:
          maxLength: 70
          minLength: 0
          type: string
          description: Debtor full name
        postalCode:
          type: string
          description: Debtor postal code
        province:
          type: string
          description: Debtor province
        taxCode:
          maxLength: 16
          minLength: 0
          type: string
          description: Debtor taxCode
      description: Debtor data
    NoticeRequestData:
      required:
      - creditorInstitution
      - debtor
      - notice
      type: object
      properties:
        creditorInstitution:
          $ref: '#/components/schemas/CreditorInstitution'
        debtor:
          $ref: '#/components/schemas/Debtor'
        notice:
          $ref: '#/components/schemas/Notice'
      description: The data used to fill the template
    Notice:
      required:
      - subject
      type: object
      properties:
        code:
          maxLength: 18
          minLength: 18
          type: string
          description: Notice code, mandatory whenever the template contains a general payment
        discounted:
          $ref: '#/components/schemas/InstallmentData'
        dueDate:
          type: string
          description: Notice due date
        installments:
          maxItems: 2147483647
          minItems: 2
          type: array
          items:
            $ref: '#/components/schemas/InstallmentData'
          description: Notice Installments
        paymentAmount:
          maximum: 99999999999.0
          type: integer
          description: Notice total amount to pay
          format: int64
        reduced:
          $ref: '#/components/schemas/InstallmentData'
        subject:
          maxLength: 90
          minLength: 0
          type: string
          description: Notice subject
      description: Notice data
    CreditorInstitution:
      required:
      - taxCode
      type: object
      properties:
        taxCode:
          type: string
          description: CI tax code
      description: Creditor Institution data
    ProblemJson:
      type: object
      properties:
        detail:
          type: string
          description: A human readable explanation specific to this occurrence of the problem.
          example: There was an error processing the request
        status:
          maximum: 600.0
          minimum: 100.0
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 200
        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'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query