openapi: 3.2.0
info:
  title: Pagopa Subscriptions Feed 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 Subscriptions Feed 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: Subscriptions Feed
paths:
  /subscriptions-feed/{date}:
    get:
      operationId: getSubscriptionsFeedForDate
      summary: Get Subscriptions Feed
      description: 'Returns the **hashed fiscal codes** of users that **subscribed to** or

        **unsubscribed from** your service **on the provided date** (UTC).


        By querying this feed everyday, you will be able to retrieve the

        "delta" of users that subscribed and unsubscribed from your service.

        You will have to keep a list of users somewhere in your infrastructure

        that you will keep updated at all times by adding the subscribed users and

        removing the unsubscribed users.


        You will then be able to query this local list to know which users you

        can send messages, to without having to query `getProfile` for each message.


        To avoid sharing the citizens fiscal codes, the API will

        provide the hex encoding of the SHA256 hash of the upper case fiscal code.

        In pseudo code `CF_HASH = LOWERCASE(HEX(SHA256(UPPERCASE(CF))))`.


        Access to this feed is subject to case-by-case authorization, and it is

        primarily intended for large-scale services, such as those pertaining

        to organizations that have an extensive user base (including geographically),

        and/or need to send very high volumes of messages per day.


        This feed serves the purpose of minimizing data processing activities

        while preserving optimization of API calls and data accuracy.

        Organizations allowed are required to query this feed everyday.'
      security:
      - SubscriptionKey: []
      responses:
        '200':
          description: Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsFeed'
              example:
                dateUTC: '2019-09-03'
                subscriptions:
                - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
                unsubscriptions: []
        '401':
          description: Unauthorized
        '403':
          description: Forbidden.
        '404':
          description: Subscriptions feed not available yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '429':
          description: Too many requests
      parameters:
      - $ref: '#/components/parameters/DateUTC'
      tags:
      - Subscriptions Feed
    servers:
    - url: https://api.io.pagopa.it/api/v1
components:
  schemas:
    DateUTC:
      type: string
      maxLength: 10
      minLength: 10
      description: A date in the format YYYY-MM-DD.
      pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2}'
      x-example: '2019-09-15'
    FiscalCodeHash:
      type: string
      maxLength: 16
      minLength: 16
      description: 'To avoid sharing the citizens fiscal codes, the API will

        provide the hex encoding of the SHA256 hash of the upper case fiscal code.'
      pattern: '[0-9a-f]{64}'
      x-example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    SubscriptionsList:
      type: array
      items:
        $ref: '#/components/schemas/FiscalCodeHash'
    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.'
    SubscriptionsFeed:
      type: object
      properties:
        dateUTC:
          $ref: '#/components/schemas/DateUTC'
        subscriptions:
          $ref: '#/components/schemas/SubscriptionsList'
        unsubscriptions:
          $ref: '#/components/schemas/SubscriptionsList'
      required:
      - dateUTC
      - subscriptions
      - unsubscriptions
  parameters:
    DateUTC:
      name: date
      in: path
      required: true
      description: A date in the format YYYY-MM-DD.
      x-example: '2019-09-15'
      schema:
        type: string
        maxLength: 10
        minLength: 10
        pattern: '[0-9]{4}-[0-9]{2}-[0-9]{2}'
  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