PagoPA Messages API

openapi: 3.2.0
info:
  title: Pagopa Messages API
  version: 4.1.1
  contact:
    name: PagoPA S.p.A.
    url: https://docs.pagopa.it/io-guida-tecnica/
  x-logo:
    url: https://io.italia.it/assets/img/io-logo-blue.svg
  description: 'Operations tagged Messages across 2 of this provider''s published API definitions: io-functions-services.yaml, pagopa-io-services-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.io.pagopa.it/api/v1
tags:
- name: Messages
paths:
  /messages:
    post:
      operationId: submitMessageforUserWithFiscalCodeInBody
      summary: Submit a Message passing the user fiscal_code in the request body
      description: 'Submits a message to a user with STANDARD or ADVANCED features based on `feature_level_type` value.

        On error, the reason is returned in the response payload.

        In order to call `submitMessageforUser`, before sending any message,

        the sender MUST call `getProfile` and check that the profile exists

        (for the specified fiscal code) and that the `sender_allowed` field

        of the user''s profile it set to `true`.'
      security:
      - SubscriptionKey: []
      responses:
        '201':
          description: Message created.
          headers:
            Location:
              description: 'Location (URL) of created message resource.

                A GET request to this URL returns the message status and details.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedMessage'
              example:
                id: 01BX9NSMKVXXS5PSP2FATZMYYY
        '400':
          description: Invalid payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden.
        '429':
          description: Too many requests
        '500':
          description: The message cannot be delivered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessage'
      tags:
      - Messages
    servers:
    - url: https://api.io.pagopa.it/api/v1
  /messages/{fiscal_code}:
    post:
      operationId: submitMessageforUser
      summary: Submit a Message passing the user fiscal_code as path parameter
      description: 'Submits a message to a user.

        On error, the reason is returned in the response payload.

        In order to call `submitMessageforUser`, before sending any message,

        the sender MUST call `getProfile` and check that the profile exists

        (for the specified fiscal code) and that the `sender_allowed` field

        of the user''s profile it set to `true`.'
      security:
      - SubscriptionKey: []
      parameters:
      - $ref: '#/components/parameters/FiscalCode'
      responses:
        '201':
          description: Message created.
          headers:
            Location:
              description: 'Location (URL) of created message resource.

                A GET request to this URL returns the message status and details.'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The identifier of the created message.
              example:
                id: 01BX9NSMKVXXS5PSP2FATZMYYY
        '400':
          description: Invalid payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden.
        '429':
          description: Too many requests
        '500':
          description: The message cannot be delivered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessage'
      tags:
      - Messages
    servers:
    - url: https://api.io.pagopa.it/api/v1
  /messages/{fiscal_code}/{id}:
    get:
      operationId: getMessage
      summary: Get Message
      description: 'The previously created message with the provided message ID is

        returned. With right permission and `ADVANCED` feature level type

        related to the previously submitted message, also read and payment

        status infos (when applicable) are returned.'
      security:
      - SubscriptionKey: []
      parameters:
      - $ref: '#/components/parameters/FiscalCode'
      - name: id
        in: path
        required: true
        description: The ID of the message.
        schema:
          type: string
      responses:
        '200':
          description: Message found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalMessageResponseWithContent'
              example:
                status: PROCESSED
                message:
                  id: 01BX9NSMKAAAS5PSP2FATZM6BQ
                  fiscal_code: QXJNTX9RCRVD6V4O
                  time_to_live: 3600
                  content:
                    subject: message subject, aliquip sint nulla in estinut
                    markdown: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas et mollis felis.

                      Vivamus orci nisl, commodo ut sodales ut, eleifend a libero. Donec dapibus, turpis in mattis tempor,

                      risus nunc malesuada ex, non aliquet metus nunc a lacus. Aenean in arcu vitae nisl porta

                      fermentum nec non nibh. Phasellus tortor tellus, semper in metus eget, eleifend

                      laoreet nibh. Aenean feugiat lectus ut nisl eleifend gravida.'
                  sender_service_id: 01BX9NSMKVXXS5PSP2FATZM6QX
                notification:
                  email: QUEUED
        '401':
          description: Unauthorized
        '403':
          description: Forbidden.
        '404':
          description: No message found for the provided ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '429':
          description: Too many requests
      tags:
      - Messages
    servers:
    - url: https://api.io.pagopa.it/api/v1
components:
  schemas:
    MessageContent:
      allOf:
      - $ref: '#/components/schemas/MessageContentBase'
      - type: object
        properties:
          payment_data:
            $ref: '#/components/schemas/PaymentData'
          prescription_data:
            $ref: '#/components/schemas/PrescriptionData'
          legal_data:
            $ref: '#/components/schemas/LegalData'
          eu_covid_cert:
            $ref: '#/components/schemas/EUCovidCert'
          third_party_data:
            $ref: '#/components/schemas/ThirdPartyData'
          due_date:
            $ref: '#/components/schemas/Timestamp'
    PrescriptionNRE:
      description: The field *Numero ricetta elettronica* identifies the medical prescription at national level.
      type: string
      minLength: 15
      maxLength: 15
    ExternalCreatedMessageWithContent:
      allOf:
      - $ref: '#/components/schemas/CreatedMessageWithContent'
      - type: object
        properties:
          feature_level_type:
            $ref: '#/components/schemas/FeatureLevelType'
        required:
        - feature_level_type
    HasPrecondition:
      type: string
      x-extensible-enum:
      - ALWAYS
      - ONCE
      - NEVER
    ThirdPartyData:
      type: object
      description: Payload containing all information needed to retrieve and visualize third party message details
      properties:
        id:
          type: string
          description: Unique id for retrieving third party enriched information about the message
          minLength: 1
        original_sender:
          type: string
          description: Either a ServiceId or a simple string representing the sender name
          minLength: 1
        original_receipt_date:
          $ref: '#/components/schemas/Timestamp'
        has_attachments:
          type: boolean
          default: false
        has_remote_content:
          type: boolean
          default: false
        has_precondition:
          $ref: '#/components/schemas/HasPrecondition'
        summary:
          type: string
          minLength: 1
        configuration_id:
          type: string
          description: Ulid string.
          format: Ulid
          x-import: '@pagopa/ts-commons/lib/strings'
          example: 01ARZ3NDEKTSV4RRFFQ69G5FAV
      required:
      - id
    PrescriberFiscalCode:
      type: string
      description: Fiscal code of the Doctor that made the prescription.
      format: FiscalCode
      x-import: '@pagopa/ts-commons/lib/strings'
      example: TCNZRO80R13C555Y
    TimeToLiveSeconds:
      type: integer
      default: 3600
      minimum: 3600
      maximum: 604800
      description: 'This parameter specifies for how long (in seconds) the system will

        try to deliver the message to the channels configured by the user.'
      example: 3600
    MessageResponseNotificationStatus:
      type: object
      properties:
        email:
          $ref: '#/components/schemas/NotificationChannelStatusValue'
        webhook:
          $ref: '#/components/schemas/NotificationChannelStatusValue'
    LegalData:
      type: object
      properties:
        sender_mail_from:
          type: string
          minLength: 1
        has_attachment:
          type: boolean
          default: false
        message_unique_id:
          type: string
          minLength: 1
        original_message_url:
          type: string
          minLength: 1
        pec_server_service_id:
          $ref: '#/components/schemas/ServiceId'
      required:
      - sender_mail_from
      - has_attachment
      - message_unique_id
    MessageContentBase:
      type: object
      properties:
        subject:
          type: string
          description: 'The subject of the message - note that only some notification

            channels support the display of a subject. When a subject is not provided,

            one gets generated from the client attributes.'
          minLength: 10
          maxLength: 120
          example: Welcome new user !
        markdown:
          type: string
          description: 'The full version of the message, in plain text or Markdown format. The

            content of this field will be delivered to channels that don''t have any

            limit in terms of content size (e.g. email, etc...).'
          minLength: 80
          maxLength: 10000
          example: '# This is a markdown header


            to show how easily markdown can be converted to **HTML**


            Remember: this has to be a long text.'
        require_secure_channels:
          type: boolean
          description: When true, messages won't trigger email notifications (only push).
      required:
      - subject
      - markdown
    ReadStatus:
      type: string
      x-extensible-enum:
      - UNAVAILABLE
      - UNREAD
      - READ
      example: UNREAD
      description: Api definition of read status enumeration
    PrescriptionData:
      type: object
      description: Metadata needed to process medical prescriptions.
      properties:
        nre:
          $ref: '#/components/schemas/PrescriptionNRE'
        iup:
          $ref: '#/components/schemas/PrescriptionIUP'
        prescriber_fiscal_code:
          $ref: '#/components/schemas/PrescriberFiscalCode'
      required:
      - nre
    CreatedMessage:
      type: object
      properties:
        id:
          type: string
          description: The identifier of the created message.
    ProblemJson:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type. When dereferenced,

            it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).'
          default: about:blank
          example: https://example.com/problem/constraint-violation
        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:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          example: 200
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.'
          example: There was an error processing the request
        instance:
          type: string
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.'
    PaymentDataWithRequiredPayee:
      allOf:
      - $ref: '#/components/schemas/PaymentDataBase'
      - type: object
        properties:
          payee:
            $ref: '#/components/schemas/Payee'
        required:
        - payee
    NewMessageContent:
      allOf:
      - $ref: '#/components/schemas/MessageContentBase'
      - type: object
        properties:
          payment_data:
            $ref: '#/components/schemas/PaymentDataWithRequiredPayee'
          due_date:
            $ref: '#/components/schemas/Timestamp'
          prescription_data:
            $ref: '#/components/schemas/PrescriptionData'
          eu_covid_cert:
            $ref: '#/components/schemas/EUCovidCert'
          third_party_data:
            $ref: '#/components/schemas/ThirdPartyData'
          legal_data:
            $ref: '#/components/schemas/LegalData'
    NewMessage:
      type: object
      properties:
        time_to_live:
          $ref: '#/components/schemas/TimeToLiveSeconds'
        content:
          $ref: '#/components/schemas/MessageContent'
        default_addresses:
          type: object
          description: 'Default addresses for notifying the recipient of the message in case

            no address for the related channel is set in his profile.'
          properties:
            email:
              type: string
              format: email
              example: foobar@example.com
        fiscal_code:
          $ref: '#/components/schemas/FiscalCode'
        feature_level_type:
          $ref: '#/components/schemas/FeatureLevelType'
      required:
      - content
    FeatureLevelType:
      type: string
      default: STANDARD
      x-extensible-enum:
      - STANDARD
      - ADVANCED
      example: STANDARD
    ExternalMessageResponseWithContent:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/ExternalCreatedMessageWithContent'
        notification:
          $ref: '#/components/schemas/MessageResponseNotificationStatus'
        status:
          $ref: '#/components/schemas/MessageStatusValue'
        read_status:
          $ref: '#/components/schemas/ReadStatus'
          description: 'Describes whether a user has read the message or not

            NOTE  : This value is only available for ADVANCED messages

            NOTE 2: `UNAVAILABLE` will be returned if user revoked the permission to access to read status'
        payment_status:
          $ref: '#/components/schemas/PaymentStatus'
          description: 'Describes the state of the related payment notice

            NOTE: This value is only available for ADVANCED payment messages'
      required:
      - message
    NotRejectedMessageStatusValue:
      type: string
      x-extensible-enum:
      - ACCEPTED
      - THROTTLED
      - FAILED
      - PROCESSED
    PaymentStatus:
      type: string
      description: Payment status enumeration
      x-extensible-enum:
      - PAID
      - NOT_PAID
      example: NOT_PAID
    Payee:
      type: object
      description: Metadata needed to explicit payment's payee.
      properties:
        fiscal_code:
          $ref: '#/components/schemas/OrganizationFiscalCode'
      required:
      - fiscal_code
    RejectedMessageStatusValue:
      type: string
      x-extensible-enum:
      - REJECTED
    CreatedMessageWithContent:
      type: object
      properties:
        id:
          type: string
        fiscal_code:
          $ref: '#/components/schemas/FiscalCode'
        time_to_live:
          $ref: '#/components/schemas/TimeToLiveSeconds'
        created_at:
          $ref: '#/components/schemas/Timestamp'
        content:
          $ref: '#/components/schemas/NewMessageContent'
        sender_service_id:
          $ref: '#/components/schemas/ServiceId'
      required:
      - id
      - fiscal_code
      - created_at
      - sender_service_id
    Timestamp:
      type: string
      format: UTCISODateFromString
      description: A date-time field in ISO-8601 format and UTC timezone.
      x-import: '@pagopa/ts-commons/lib/dates'
      example: '2018-10-13T00:00:00.000Z'
    PaymentDataBase:
      type: object
      description: Metadata needed to process pagoPA payments.
      properties:
        amount:
          description: Amount of payment in euro cent. PagoPA accepts up to 9999999999 euro cents.
          type: integer
          minimum: 1
          maximum: 9999999999
        notice_number:
          description: The field "Numero Avviso" of pagoPa, needed to identify the payment.  Format is `<aux digit(1n)>[<application code> (2n)]<codice IUV (15|17n)>`. See [pagoPa specs](https://docs.pagopa.it/saci/specifiche-attuative-dei-codici-identificativi-di-versamento-riversamento-e-rendicontazione/premessa) for more info on this field and the IUV.
          type: string
          pattern: ^[0123][0-9]{17}$
        invalid_after_due_date:
          type: boolean
          default: false
      required:
      - amount
      - notice_number
    PrescriptionIUP:
      description: The field *Identificativo Unico di Prescrizione* identifies the medical prescription at regional level.
      type: string
      minLength: 1
      maxLength: 16
    ServiceId:
      type: string
      description: 'The ID of the Service. Equals the subscriptionId of a registered

        API user.'
      minLength: 1
    MessageStatusValue:
      x-one-of: true
      allOf:
      - $ref: '#/components/schemas/RejectedMessageStatusValue'
      - $ref: '#/components/schemas/NotRejectedMessageStatusValue'
      description: "The processing status of a message.\n\"ACCEPTED\": the message has been accepted and will be processed for delivery;\n  we'll try to store its content in the user's inbox and notify him on his preferred channels\n\"THROTTLED\": a temporary failure caused a retry during the message processing;\n  any notification associated with this message will be delayed for a maximum of 7 days\n\"FAILED\": a permanent failure caused the process to exit with an error, no notification will be sent for this message\n\"PROCESSED\": the message was succesfully processed and is now stored in the user's inbox;\n  we'll try to send a notification for each of the selected channels\n\"REJECTED\": either the recipient does not exist, or the sender has been blocked"
    OrganizationFiscalCode:
      type: string
      description: Organization fiscal code.
      format: OrganizationFiscalCode
      x-import: '@pagopa/ts-commons/lib/strings'
      example: '12345678901'
    NotificationChannelStatusValue:
      type: string
      description: "The status of a notification (one for each channel).\n\"SENT\": the notification was succesfully sent to the channel (ie. email or push notification)\n\"THROTTLED\": a temporary failure caused a retry during the notification processing;\n  the notification associated with this channel will be delayed for a maximum of 7 days or until the message expires\n\"EXPIRED\": the message expired before the notification could be sent;\n  this means that the maximum message time to live was reached; no notification will be sent to this channel\n\"FAILED\": a permanent failure caused the process to exit with an error, no notification will be sent to this channel"
      x-extensible-enum:
      - SENT
      - THROTTLED
      - EXPIRED
      - FAILED
      example: SENT
    FiscalCode:
      type: string
      description: User's fiscal code.
      format: FiscalCode
      x-import: '@pagopa/ts-commons/lib/strings'
      example: SPNDNL80R13C555X
    EUCovidCert:
      type: object
      description: Paylod with access token to retrieve a EU Covid Certificate
      properties:
        auth_code:
          type: string
      required:
      - auth_code
    PaymentData:
      allOf:
      - $ref: '#/components/schemas/PaymentDataBase'
      - type: object
        properties:
          payee:
            $ref: '#/components/schemas/Payee'
  parameters:
    FiscalCode:
      name: fiscal_code
      in: path
      required: true
      description: The fiscal code of the user, all upper case.
      x-example: SPNDNL80R13C555X
      schema:
        type: string
        maxLength: 16
        minLength: 16
        pattern: '[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]'
  securitySchemes:
    SubscriptionKey:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: The API key obtained through the Backoffice IO or both getService or cmsGetServiceKeys operation.
    ManageSubscriptionKey:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
      description: The `manage` API key obtained through the Backoffice IO.
x-refined-from:
- io-functions-services.yaml
- pagopa-io-services-openapi.yml