From a0ea00691b65903e1734275b861f3b23fe2bd7e2 Mon Sep 17 00:00:00 2001
From: Antonio Tarricone <110115827+antoniotarricone@users.noreply.github.com>
Date: Mon, 4 Nov 2024 16:42:27 +0100
Subject: [PATCH] feat: [SRTP-39] API to handle RTP activations initiated by
 the Payer's RTP Service Provider. (#6)

---
 src/rtp/api/pagopa/activation.yaml | 1188 ++++++++++++++++++++++++++++
 1 file changed, 1188 insertions(+)
 create mode 100644 src/rtp/api/pagopa/activation.yaml

diff --git a/src/rtp/api/pagopa/activation.yaml b/src/rtp/api/pagopa/activation.yaml
new file mode 100644
index 0000000..8d90e19
--- /dev/null
+++ b/src/rtp/api/pagopa/activation.yaml
@@ -0,0 +1,1188 @@
+openapi: 3.0.3
+
+info:
+  title: RTP Activation API.
+  version: 1.0.0
+  description: |
+    API to handle RTP activations initiated by the Payer's RTP Service Provider.
+  contact:
+    name: PagoPA S.p.A.
+    email: rtp@pagopa.it
+
+servers:
+  - description: Development/Test
+    url: https://rtp.dev.cstar.pagopa.it
+    x-internal: true
+  - description: User Acceptance Test
+    url: https://rtp.uat.cstar.pagopa.it
+    x-internal: false
+  - description: Production
+    url: https://rtp.cstar.pagopa.it
+    x-internal: false
+    
+tags:
+  - name: create
+    description: Create operation.
+  - name: read
+    description: Read operation.
+  - name: update
+    description: Update operation.
+  - name: delete
+    description: Delete operation.
+
+paths:
+  /activations:
+    post:
+      operationId: activate
+      summary: RTP activation initiated by the Payer's RTP Service Provider.
+      description: |
+        The operation is used by Payer's RTP Service Provider to enable the
+        Payee's RTP Service Provider to send RTP messages to the Payer's RTP
+        Service Provider.
+        
+        When the operation is used by not-admin subject, the system verifies
+        that the Payer's RTP Service Provider ID matches the subject claim of
+        the access token. `403 Forbidden` is returned on mismatch.
+        
+        If an activation already exists for the provided Payer ID/Payee ID or,
+        in case of bulk activation, for the provided Payer ID, a new one is
+        created. See §3.3.3 of
+        `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf` for more
+        details.
+      tags: [create]
+      security:
+        - oAuth2: [admin_rtp_activations, write_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+      requestBody:
+        $ref: '#/components/requestBodies/CreateOrUpdateActivation'
+      responses:
+        "201":
+          #description: Created.
+          $ref: '#/components/responses/CreateActivation'
+        "400":
+          #description: Bad request.
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Wrong credentials.
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "415":
+          #description: Unsupported media type. Did you provide application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request.
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error.
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error.
+          $ref: '#/components/responses/Error'
+
+    get:
+      operationId: getActivations
+      summary: Returns RTP activations.
+      description: |
+        The operation returns all the RTP activations stored by the system.
+        
+        When the operation is used by not-admin subject, the system returns
+        the RTP activations which have the Payer's RTP Service Provider ID that
+        matches the subject claim of the access token.
+      tags: [read]
+      security:
+        - oAuth2: [admin_rtp_activations, read_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+        - $ref: '#/components/parameters/PageNumber'
+        - $ref: '#/components/parameters/PageSize'
+      responses:
+        "200":
+          #description: Ok.
+          $ref: '#/components/responses/PageOfActivations'
+        "400":
+          #description: Bad request.
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Access token is missing or invalid.
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden.
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request.
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error.
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error.
+          $ref: '#/components/responses/Error'
+
+  /activations/{activationId}:
+    get:
+      operationId: getActivation
+      summary: Returns a RTP activation.
+      description: |
+        The operation finds a RTP activation by its ID.
+        
+        When the operation is used by not-admin subject, the system returns
+        the RTP activation only if its Payer's RTP Service Provider ID matches
+        the subject claim of the access token, otherwise `404 Not Found` is
+        returned.
+      tags: [read]
+      security:
+        - oAuth2: [admin_rtp_activations, read_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+        - $ref: '#/components/parameters/ActivationId'
+      responses:
+        "200":
+          #description: Found.
+          $ref: '#/components/responses/Activation'
+        "400":
+          #description: Bad request.
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Access token is missing or invalid.
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden.
+          $ref: '#/components/responses/Error'
+        "404":
+          #description: Not found.
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request.
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error.
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error.
+          $ref: '#/components/responses/Error'
+
+    put:
+      operationId: updateActivation
+      summary: Updates a RTP activation.
+      description: |
+        The operation updates a RTP actviation searching it by its ID.
+        
+        When the operation is used by not-admin subject:
+          - the system returns `404 Not Found` if the Payer's RTP Service
+            Provider ID of the activation doesn't match the subject claim of
+            the access token;
+          - the system returns `403 Forbidden` if the provided value of Payer's
+            RTP Service doesn't match the subject claim of the access token.
+      tags: [update]
+      security:
+        - oAuth2: [admin_rtp_activations, write_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+        - $ref: '#/components/parameters/ActivationId'
+      requestBody:
+        $ref: '#/components/requestBodies/CreateOrUpdateActivation'
+      responses:
+        "204":
+          #description: No content
+          $ref: '#/components/responses/NoContent'
+        "400":
+          #description: Bad request
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Wrong credentials
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden
+          $ref: '#/components/responses/Error'
+        "404":
+          #description: Not found
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "415":
+          #description: Unsupported media type. Did you provide application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error
+          $ref: '#/components/responses/Error'
+
+    delete:
+      operationId: deleteActivation
+      summary: Deletes a RTP activation.
+      description: |
+        The operation deletes a RTP actviation searching it by its ID.
+        
+        When the operation is used by not-admin subject, the system returns
+        `404 Not Found` if the Payer's RTP Service Provider ID of the activation
+        doesn't match the subject claim of the access token.
+      tags: [delete]
+      security:
+        - oAuth2: [admin_rtp_activations, write_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+        - $ref: '#/components/parameters/ActivationId'
+      responses:
+        "204":
+          #description: No content
+          $ref: '#/components/responses/NoContent'
+        "400":
+          #description: Bad request
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Access token is missing or invalid
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden
+          $ref: '#/components/responses/Error'
+        "404":
+          #description: Not found
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error
+          $ref: '#/components/responses/Error'
+
+  /activations/findByPayerId:
+    get:
+      operationId: findActivationsByPayerId
+      summary: Finds a RTP activation by Payer ID.
+      description: |
+        The operation finds RTP activations by Payer ID.
+        
+        When the operation is used by not-admin subject, the system returns
+        the RTP activations with the Payer's RTP Service Provider ID that
+        matches the subject claim of the access token.
+      tags: [read]
+      security:
+        - oAuth2: [admin_rtp_activations, read_rtp_activations]
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/Version'
+        - $ref: '#/components/parameters/PageNumber'
+        - $ref: '#/components/parameters/PageSize'
+        - $ref: '#/components/parameters/PayerId'
+      responses:
+        "200":
+          #description: Ok.
+          $ref: '#/components/responses/PageOfActivations'
+        "400":
+          #description: Bad request.
+          $ref: '#/components/responses/Error'
+        "401":
+          #description: Access token is missing or invalid.
+          $ref: '#/components/responses/Error'
+        "403":
+          #description: Forbidden.
+          $ref: '#/components/responses/Error'
+        "406":
+          #description: Not acceptable. Did you require application/json?
+          $ref: '#/components/responses/Error'
+        "429":
+          #description: Too many request.
+          $ref: '#/components/responses/Error'
+        "500":
+          #description: Server error.
+          $ref: '#/components/responses/Error'
+        default:
+          #description: Unexpected error.
+          $ref: '#/components/responses/Error'
+
+components:
+  # ============================================================================
+  # Schemas.
+  # ============================================================================
+  schemas:
+    # --------------------------------------------------------------------------
+    # Basic types for CORS stuff.
+    # --------------------------------------------------------------------------
+    AccessControlAllowOrigin:
+      description: |
+        Indicates whether the response can be shared with requesting code from
+        the given origin.
+      type: string
+      pattern: "^[ -~]{1,2048}$"
+      minLength: 1
+      maxLength: 2048
+
+    # --------------------------------------------------------------------------
+    # Basic types for rate limit handling.
+    # --------------------------------------------------------------------------
+    RateLimitLimit:
+      description: The number of allowed requests in the current period.
+      type: integer
+      format: int32
+      minimum: 1
+      maximum: 240
+
+    RateLimitReset:
+      description: The number of seconds left in the current period.
+      type: integer
+      format: int32
+      minimum: 1
+      maximum: 60
+
+    RetryAfter:
+      description: |
+        The number of seconds to wait before allowing a follow-up request.
+      type: integer
+      format: int32
+      minimum: 1
+      maximum: 240
+
+    # --------------------------------------------------------------------------
+    # Basic types for paging.
+    # --------------------------------------------------------------------------
+    PageNumber:
+      description: Number of the page.
+      type: integer
+      format: int32
+      minimum: 0
+      maximum: 2147483647
+      example: 1
+
+    PageSize:
+      description: Size of the page.
+      type: integer
+      format: int32
+      minimum: 1
+      maximum: 128
+      example: 20
+
+    TotalElements:
+      description: Total elements.
+      type: integer
+      format: int64
+      minimum: 0
+      maximum: 9223372036854775807
+      example: 20
+
+    TotalPages:
+      description: Total pages.
+      type: integer
+      format: int64
+      minimum: 0
+      maximum: 9223372036854775807
+      example: 20
+
+    # --------------------------------------------------------------------------
+    # Basic types for error handling.
+    # --------------------------------------------------------------------------
+    ErrorCode:
+      description: Error code.
+      type: string
+      pattern: "^[A-F0-9]{9}$"
+      minLength: 9
+      maxLength: 9
+      example: "01000000F"
+
+    ErrorDescription:
+      description: Error description.
+      type: string
+      pattern: "^[ -~]{0,256}$"
+      minLength: 0
+      maxLength: 256
+      example: "Wrong party identifier"
+
+    # --------------------------------------------------------------------------
+    # Basic types for technical stuff.
+    # --------------------------------------------------------------------------
+    ActivationId:
+      description: Identifier of the RTP activation resource.
+      type: string
+      format: uuid
+      pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
+      minLength: 36
+      maxLength: 36
+      example: "d0d654e6-97da-4848-b568-99fedccb642b"
+
+    ActivationLocation:
+      description: URL of the RTP activation resource.
+      type: string
+      format: uri
+      pattern: "^[ -~]{1,2048}$"
+      minLength: 1
+      maxLength: 2048
+      example: "https://rtp.cstar.pagopa.it/activations/d0d654e6-97da-4848-b568-99fedccb642b"
+
+    RequestId:
+      description: Identifier of the request.
+      type: string
+      format: uuid
+      pattern: "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
+      minLength: 36
+      maxLength: 36
+      example: "d0d654e6-97da-4848-b568-99fedccb642b"
+
+    Version:
+      description: Version of the required API.
+      type: string
+      pattern: "^[ -~]{1,64}$"
+      minLength: 1
+      maxLength: 64
+      example: "1.0.0-alpha-a.b-c-somethinglong+build.1-aef.1-its-okay"
+
+    # --------------------------------------------------------------------------
+    # Domain specific basic types.
+    # --------------------------------------------------------------------------
+    ContractReference:
+      description: |
+        Activation contract reference (B026).
+        
+        Contract/service/tax code on which the activation is valid.
+        
+        If not set, the activation is considered valid on all
+        contracts/services/taxes applicable to the Payee-Payer pair indicated.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='ContractReference1']/xs:sequence/xs:element[@name='Ref']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[ -~]{1,500}$"
+      minLength: 1
+      maxLength: 500
+      example: "3943"
+
+    CountryCode:
+      description: |
+        Nation with its own government.
+        
+        References:
+          - `/xs:schema/xs:complexType[@name='PostalAddress24']/xs:sequence/xs:element[@name='Ctry']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[A-Z]{2}$"
+      minLength: 2
+      maxLength: 2
+      example: "IT"
+
+    DebtorActivationId:
+      description: |
+        Activation counterpart reference (B027).
+        
+        Unique identification, as assigned by the initiating party, to
+        unambiguously identify the activation.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='DebtorActivation3']/xs:sequence/xs:element[@name='DbtrActvtnId']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[ -~]{1,35}$"
+      minLength: 1
+      maxLength: 35
+      example: "0ed6b70dcf6e4a248e9079eb5b0b8e7d"
+
+    DedicatedActivationCode:
+      description: |
+        Dedicated activation code (B029).
+        
+        Unique, one-time code that a creditor may require from a debtor for
+        activation purposes, and which is known only by the creditor and the
+        debtor.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='DebtorActivation3']/xs:sequence/xs:element[@name='DdctdActvtnCd']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[ -~]{1,35}$"
+      minLength: 1
+      maxLength: 35
+      example: "d251b42ebcb94da586bdb20b525856c8"
+
+    EffectiveActivationDate:
+      description: |
+        Effective activation date (B035).
+                
+        Date and time at which activation has been stored.
+                
+        References:
+          - §5.1.2 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='ActivationStatus2']/xs:sequence/xs:element[@name='FctvActvtnDt']`
+            of `EPC254-23_V1.0_reda.073.001.01_DSO-15.xsd` or
+            `EPC254-23_V1.0_reda.073.001.01_DSO-31.xsd`
+      type: string
+      format: date-time
+      example: "2024-10-30T16:39:34+01:00"
+
+    EndDate:
+      description: |
+        Activation end date (B025).
+        
+        Date and time at which the debtor activation will be deactivated.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='DebtorActivation3']/xs:sequence/xs:element[@name='EndDt']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      format: date-time
+      example: "2025-10-30T16:39:34+01:00"
+
+    FiscalCode:
+      description: |
+        Fiscal (or tax) code.
+        
+        It is used as identifier of the Payer (P009) and of the Payee (E005).
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: string
+      pattern: "^(([A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z])|(\\d{11}))$"
+      minLength: 11
+      maxLength: 16
+      example: "RSSMRA85T10A562S"
+
+    MerchantCategoryCode:
+      description: |
+        Merchant Category Code of the Payee (E006).
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: string
+      pattern: "^\\d{4}$"
+      minLength: 4
+      maxLength: 4
+      example: "9399"
+
+    PartyId:
+      description: |
+        Unique and unambiguous identification of a party.
+        
+        It is used as identifier of the Payer’s RTP Service Provider (N001) and
+        for Payee’s RTP Service Provider (N002).
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='RTPPartyIdentification1']/xs:sequence/xs:element[@name='Id']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[ -~]{1,35}$"
+      minLength: 1
+      maxLength: 35
+      example: "12345678901"
+
+    PartyName:
+      description: |
+        Name by which a party is known and which is usually used to identify
+        that party.
+        
+        It is used as name of the Payer (P001) and of the Payee (E001).
+        
+        *According to `EPC254-23 Inter-RTP SP SRTP E&A IG 2023 V1.0.pdf` the
+        maximum length of this field is limited to 70.*
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='RTPPartyIdentification1']/xs:sequence/xs:element[@name='Nm']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      pattern: "^[ -~]{1,70}$"
+      minLength: 1
+      maxLength: 70
+      example: "Mario Rossi"
+
+    RequestedInvoiceType:
+      description: |
+        Requested e-invoice type (B030).
+        
+        Type of elements to be presented in the electronic invoice (e-invoice):
+          - `FULL`: Full information of the presented e-invoice should be presented to the debtor.
+          - `PAYD`: Only information necessary to initiate the payment should be presented to the debtor.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='ElectronicInvoice1']/xs:sequence/xs:element[@name='PresntmntTp']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      enum:
+        - FULL
+        - PAYD
+      example: "PAYD"
+
+    StartDate:
+      description: |
+        Activation start date (B024).
+        
+        Date and time at which the debtor activation will be activated.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+          - `/xs:schema/xs:complexType[@name='DebtorActivation3']/xs:sequence/xs:element[@name='StartDt']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: string
+      format: date-time
+      example: "2024-10-30T16:39:34+01:00"
+
+    TradeName:
+      description: |
+        Trade Name of the Payer (P002) and of the Payee (E002).
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: string
+      pattern: "^[ -~]{1,35}$"
+      minLength: 1
+      maxLength: 35
+      example: "ROMA CAPITALE"
+
+    # --------------------------------------------------------------------------
+    # Complex types for paging.
+    # --------------------------------------------------------------------------
+    PageMetadata:
+      description: Metadata of a page of data.
+      type: object
+      additionalProperties: false
+      properties:
+        totalElements:
+          $ref: '#/components/schemas/TotalElements'
+        totalPages:
+          $ref: '#/components/schemas/TotalPages'
+        page:
+          $ref: '#/components/schemas/PageNumber'
+        size:
+          $ref: '#/components/schemas/PageSize'
+      required:
+        - totalElements
+        - totalPages
+        - page
+        - size
+      example:
+        totalElements: 198
+        totalPages: 10
+        page: 5
+        size: 20
+
+    # --------------------------------------------------------------------------
+    # Complex type for error handling.
+    # --------------------------------------------------------------------------
+    Error:
+      description: Error details.
+      type: object
+      additionalProperties: false
+      properties:
+        code:
+          $ref: '#/components/schemas/ErrorCode'
+        description:
+          $ref: '#/components/schemas/ErrorDescription'
+      required:
+        - code
+        - description
+      example:
+        code: "01000000F"
+        description: "Wrong party identifier"
+
+    Errors:
+      description: List of errors.
+      type: object
+      additionalProperties: false
+      properties:
+        errors:
+          type: array
+          minItems: 1
+          maxItems: 32
+          items:
+            $ref: '#/components/schemas/Error'
+      required:
+        - errors
+      example:
+        errors:
+          - code: "01000000F"
+            description: "Wrong party identifier"
+      
+    # ------------------------------------------------------
+    # Domain specific complex types.
+    # ------------------------------------------------------
+    Activation:
+      allOf:
+        - type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/ActivationId'
+            effectiveActivationDate:
+              $ref: '#/components/schemas/EffectiveActivationDate'
+          required:
+            - id
+            - effectiveActivationDate
+        - $ref: '#/components/schemas/ActivationReq'
+      example:
+        id: "d0d654e6-97da-4848-b568-99fedccb642b"
+        effectiveActivationDate: "2024-10-30T16:39:34+01:00"
+        payer:
+          id: "RSSMRA85T10A562S"
+          name: "Mario Rossi"
+          address:
+            countryCode: "IT"
+            addressLines:
+              - "Via Sardegna, 38"
+              - "00187 Roma (RM)"
+          rtpSpId: "10987654321"
+
+    Activations:
+      description: List of RTP activations.
+      type: array
+      minItems: 0
+      maxItems: 128
+      items:
+        $ref: '#/components/schemas/Activation'
+      example:
+        - id: "d0d654e6-97da-4848-b568-99fedccb642b"
+          effectiveActivationDate: "2024-10-30T16:39:34+01:00"
+          payer:
+            id: "RSSMRA85T10A562S"
+            name: "Mario Rossi"
+            address:
+              countryCode: "IT"
+              addressLines:
+                - "Via Sardegna, 38"
+                - "00187 Roma (RM)"
+            rtpSpId: "10987654321"
+
+    ActivationReq:
+      description: |
+        Data of a RTP activation.
+        
+        For bulk activation, `Payee` property must be omitted.
+        
+        **Currently is supported bulk activation only!**
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: object
+      additionalProperties: true # It's extended by another object.
+      properties:
+        payer:
+          $ref: '#/components/schemas/Payer'
+        payee:
+          $ref: '#/components/schemas/Payee'
+        startDate:
+          $ref: '#/components/schemas/StartDate'
+        endDate:
+          $ref: '#/components/schemas/EndDate'
+        contractRef:
+          $ref: '#/components/schemas/ContractReference'
+        debtorActivationId:
+          $ref: '#/components/schemas/DebtorActivationId'
+        dedicatedActivationCode:
+          $ref: '#/components/schemas/DedicatedActivationCode'
+        requestedInvoiceType:
+          $ref: '#/components/schemas/RequestedInvoiceType'
+      required:
+        - payer
+      example:
+        payer:
+          id: "RSSMRA85T10A562S"
+          name: "Mario Rossi"
+          address:
+            countryCode: "IT"
+            addressLines:
+              - "Via Sardegna, 38"
+              - "00187 Roma (RM)"
+          rtpSpId: "10987654321"
+  
+    AddressLines:
+      description: |
+        Information that locates and identifies a specific address, as defined
+        by postal services, presented in free format text.
+        
+        References:
+          - `/xs:schema/xs:complexType[@name='PostalAddress24']/xs:sequence/xs:element[@name='AdrLine']`
+            of `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: array
+      minItems: 1
+      maxItems: 2
+      items:
+        type: string
+        pattern: "^[ -~]{1,70}$"
+        minLength: 1
+        maxLength: 70
+      example:
+        - "Via Sardegna, 38"
+        - "00187 Roma (RM)"
+
+    PageOfActivations:
+      description: Page of RTP activations.
+      type: object
+      additionalProperties: false
+      properties:
+        activations:
+          $ref: '#/components/schemas/Activations'
+        page:
+          $ref: '#/components/schemas/PageMetadata'
+      required:
+        - activations
+        - page
+      example:
+        activations:
+          - id: "d0d654e6-97da-4848-b568-99fedccb642b"
+            effectiveActivationDate: "2024-10-30T16:39:34+01:00"
+            payer:
+              id: "RSSMRA85T10A562S"
+              name: "Mario Rossi"
+              address:
+                countryCode: "IT"
+                addressLines:
+                  - "Via Sardegna, 38"
+                  - "00187 Roma (RM)"
+              rtpSpId: "10987654321"
+        page:
+          totalElements: 2
+          totalPages: 2
+          page: 1
+          size: 1
+
+    Payee:
+      description: |
+        Payee data.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: object
+      additionalProperties: false
+      properties:
+        id:
+          $ref: '#/components/schemas/FiscalCode'
+        name:
+          $ref: '#/components/schemas/PartyName'
+        address:
+          $ref: '#/components/schemas/PostalAddress'
+        tradeName:
+          $ref: '#/components/schemas/TradeName'
+        mcc:
+          $ref: '#/components/schemas/MerchantCategoryCode'
+        rtpSpId:
+          $ref: '#/components/schemas/PartyId'
+      required:
+        - id
+        - name
+        - address
+        - rtpSpId
+      example:
+        id: "02438750586"
+        name: "ROMA CAPITALE"
+        address:
+          countryCode: "IT"
+          addressLines:
+            - "Piazza del Campidoglio, 1"
+            - "00186 Roma (RM)"
+        rtpSpId: "12345678901"
+
+    Payer:
+      description: |
+        Payer data.
+        
+        References:
+          - §5.1.1 of `CPI-Tavolo-incassi-e-pagamenti-pubblici-RTP-PagoPA.pdf`
+      type: object
+      additionalProperties: false
+      properties:
+        id:
+          $ref: '#/components/schemas/FiscalCode'
+        name:
+          $ref: '#/components/schemas/PartyName'
+        address:
+          $ref: '#/components/schemas/PostalAddress'
+        tradeName:
+          $ref: '#/components/schemas/TradeName'
+        rtpSpId:
+          $ref: '#/components/schemas/PartyId'
+      required:
+        - id
+        - name
+        - address
+        - rtpSpId
+      example:
+        id: "RSSMRA85T10A562S"
+        name: "Mario Rossi"
+        address:
+          countryCode: "IT"
+          addressLines:
+            - "Via Sardegna, 38"
+            - "00187 Roma (RM)"
+        rtpSpId: "10987654321"
+
+    PostalAddress:
+      description: |
+        Information that locates and identifies a specific address, as defined
+        by postal services.
+        
+        References:
+          - `/xs:schema/xs:complexType[@name='PostalAddress24']` of
+            `EPC254-23_V1.0_reda.070.001.01_DSO-06.xsd` or
+            `EPC254-23_V1.0_reda.070.001.01_DSO-22.xsd`
+      type: object
+      additionalProperties: false
+      properties:
+        countryCode:
+          $ref: '#/components/schemas/CountryCode'
+        addressLines:
+          $ref: '#/components/schemas/AddressLines'
+      required:
+        - countryCode
+        - addressLines
+      example:
+        countryCode: "IT"
+        addressLines:
+          - "Via Sardegna, 38"
+          - "00187 Roma (RM)"
+
+  # ============================================================================
+  # Request bodies.
+  # ============================================================================
+  requestBodies:
+    CreateOrUpdateActivation:
+      description: Request to create or update a RTP activation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ActivationReq'
+
+  # ============================================================================
+  # Parameters.
+  # ============================================================================
+  parameters:
+    ActivationId:
+      name: activationId
+      in: path
+      description: Identifier of the RTP activation resource.
+      required: true
+      schema:
+        $ref: '#/components/schemas/ActivationId'
+
+    PageNumber:
+      name: page
+      in: query
+      description: Number of the requested page of data.
+      required: true
+      schema:
+        $ref: '#/components/schemas/PageNumber'
+
+    PageSize:
+      name: size
+      in: query
+      description: Size of the requested page of data.
+      required: true
+      schema:
+        $ref: '#/components/schemas/PageSize'
+
+    PayerId:
+      name: PayerId
+      in: header
+      description: Identifier of the Payer.
+      required: true
+      schema:
+        $ref: '#/components/schemas/FiscalCode'
+
+    RequestId:
+      name: RequestId
+      in: header
+      description: Identifier of the request.
+      required: true
+      schema:
+        $ref: '#/components/schemas/RequestId'
+
+    Version:
+      name: Version
+      in: header
+      description: Version of the required API.
+      required: false
+      schema:
+        $ref: '#/components/schemas/Version'
+
+  # ============================================================================
+  # Responses
+  # ============================================================================
+  responses:
+    Activation:
+      description: Response returned when RTP activation data is requested.
+      headers:
+        Access-Control-Allow-Origin:
+          description: |
+            Indicates whether the response can be shared with requesting code
+            from the given origin.
+          required: false
+          schema:
+            $ref: '#/components/schemas/AccessControlAllowOrigin'
+        RateLimit-Limit:
+          description: The number of allowed requests in the current period
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitLimit'
+        RateLimit-Reset:
+          description: The number of seconds left in the current period
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitReset'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Activation'
+
+    CreateActivation:
+      description: Response returned when a RTP activation is requested.
+      headers:
+        Access-Control-Allow-Origin:
+          description: |
+            Indicates whether the response can be shared with requesting code
+            from the given origin.
+          required: false
+          schema:
+            $ref: '#/components/schemas/AccessControlAllowOrigin'
+        RateLimit-Limit:
+          description: The number of allowed requests in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitLimit'
+        RateLimit-Reset:
+          description: The number of seconds left in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitReset'
+        Location:
+          description: URL of the activation resource.
+          required: true
+          schema:
+            $ref: '#/components/schemas/ActivationLocation'
+
+    Error:
+      description: Error response.
+      headers:
+        Access-Control-Allow-Origin:
+          description: |
+            Indicates whether the response can be shared with requesting code
+            from the given origin.
+          required: false
+          schema:
+            $ref: '#/components/schemas/AccessControlAllowOrigin'
+        RateLimit-Limit:
+          description: The number of allowed requests in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitLimit'
+        RateLimit-Reset:
+          description: The number of seconds left in the current period
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitReset'
+        Retry-After:
+          description: |
+            The number of seconds to wait before allowing a follow-up request.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RetryAfter'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Errors'
+        text/*:
+          schema:
+            type: string
+            pattern: "^[ -~]{0,65535}$"
+            maxLength: 65535
+
+    NoContent:
+      description: No content response.
+      headers:
+        Access-Control-Allow-Origin:
+          description: |
+            Indicates whether the response can be shared with requesting code
+            from the given origin.
+          required: false
+          schema:
+            $ref: '#/components/schemas/AccessControlAllowOrigin'
+        RateLimit-Limit:
+          description: The number of allowed requests in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitLimit'
+        RateLimit-Reset:
+          description: The number of seconds left in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitReset'
+
+    PageOfActivations:
+      description: Response to the request to get RTP activations.
+      headers:
+        Access-Control-Allow-Origin:
+          description: |
+            Indicates whether the response can be shared with requesting code
+            from the given origin.
+          required: false
+          schema:
+            $ref: '#/components/schemas/AccessControlAllowOrigin'
+        RateLimit-Limit:
+          description: The number of allowed requests in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitLimit'
+        RateLimit-Reset:
+          description: The number of seconds left in the current period.
+          required: false
+          schema:
+            $ref: '#/components/schemas/RateLimitReset'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PageOfActivations'
+
+  # ============================================================================
+  # Security schemes.
+  # ============================================================================
+  securitySchemes:
+    oAuth2:
+      description: |
+        A bearer token in the format of a JWS and conforms to the specifications
+        included in RFC8725.
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: /token
+          refreshUrl: /token
+          scopes:
+            admin_rtp_activations: Admin RPT activation.
+            write_rtp_activations: Create, update or delete RTP activation.
+            read_rtp_activations: Read RTP activation.