openapi: 3.0.0
info:
  description: |
    I am MasSubscriptions Subscription Creation Service. My intention is to provide a set of REST services for migrating subscriptions into existing subscriptions databases.
  version: 0.1.0
  title: MasSubscriptionsSubscriptionCreationService
servers:
  - description: production
    url: 'https://subscriptions.masstack.com/v3/'
  - description: staging
    url: 'https://subscriptions.sta.masstack.com/v3/'
security:
  - bearerAuth: [ ]

tags:
  - name: Health
    description: Health check endpoints for monitoring service availability
  - name: Credit Limits
    description: Credit limit migration endpoints for subscriptions
  - name: Segments
    description: Segment migration endpoints for subscriptions
  - name: Max Subscriptions
    description: Max streaming subscription migration endpoints
  - name: Disney Subscriptions
    description: Disney streaming subscription migration endpoints
  - name: Amazon Prime Subscriptions
    description: Amazon Prime streaming subscription migration endpoints

paths:
  '/health':
    get:
      tags:
        - Health
      summary: Health check endpoint
      description: Returns the health status of the Subscription Creation service and its dependencies (database connectivity).
      operationId: getHealth
      security: [ ]
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                persistence: "pass"
                global: "pass"
        '500':
          description: Service is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                persistence: "fail"
                global: "fail"

  '/ready':
    get:
      tags:
        - Health
      summary: Readiness check endpoint
      description: Returns the readiness status of the Subscription Creation service. Used by Kubernetes to determine if the service is ready to receive traffic.
      operationId: getReadiness
      security: [ ]
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                persistence: "pass"
                global: "pass"
        '500':
          description: Service is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                persistence: "fail"
                global: "fail"

  '/orgs/{org}/migrations/subscriptions/{legacy_id}/credit_limits':
    post:
      tags:
        - Credit Limits
      summary: Migrate credit limits for a subscription
      description: Creates credit limits for a subscription identified by legacy_id. This is a migration endpoint that creates initial credit limit data.
      operationId: createCreditLimits
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - name: legacy_id
          in: path
          description: Legacy subscription ID (Integer from V1 database)
          required: true
          schema:
            type: integer
            format: int32
          example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCreditLimitsRequest'
      responses:
        '201':
          description: Credit limits created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Credit Limits
      summary: Delete subscription credit limits
      description: Deletes subscription credit limits for a subscription identified by legacy_id. This is a rollback endpoint for credit limits migration.
      operationId: deleteCreditLimits
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - in: path
          name: legacy_id
          description: Legacy subscription ID
          required: true
          schema:
            type: string
          example: "12345"
      responses:
        '204':
          description: Credit limits deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/{legacy_id}/segments':
    post:
      tags:
        - Segments
      summary: Create subscription segment
      description: Creates a subscription segment for a subscription identified by legacy_id. This is a migration endpoint that creates initial credit limit data.
      operationId: createSubscriptionSegment
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - in: path
          name: legacy_id
          description: Legacy subscription ID
          required: true
          schema:
            type: string
          example: "12345"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
      responses:
        '201':
          description: Segment created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Segments
      summary: Delete subscription segment
      description: Deletes subscription segment(s) for a subscription identified by legacy_id. This is a rollback endpoint for segment migration.
      operationId: deleteSubscriptionSegment
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - in: path
          name: legacy_id
          description: Legacy subscription ID
          required: true
          schema:
            type: string
          example: "12345"
      responses:
        '204':
          description: Segment deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/max':
    post:
      tags:
        - Max Subscriptions
      summary: Migrate Max subscription
      description: |
        Creates a Max subscription with all related entities (promotions, commitments, bundle history).
        This is a migration-only endpoint that bypasses fraud validation and event generation.
      operationId: createMaxSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Max'
      responses:
        '201':
          description: Max subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Max'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/max/{id}':
    delete:
      tags:
        - Max Subscriptions
      summary: Rollback Max subscription migration
      description: |
        Deletes a migrated Max subscription and all related entities (promotions, commitments, history).
        This endpoint is used exclusively for migration rollback purposes.
      operationId: deleteMaxSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '204':
          description: Max subscription deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/disney':
    post:
      tags:
        - Disney Subscriptions
      summary: Migrate Disney subscription
      description: |
        Creates a Disney subscription with all related entities (promotions, commitments, bundle history).
        This is a migration-only endpoint that bypasses fraud validation and event generation.
      operationId: createDisneySubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Disney'
      responses:
        '201':
          description: Disney subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disney'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/disney/{id}':
    delete:
      tags:
        - Disney Subscriptions
      summary: Rollback Disney subscription migration
      description: |
        Deletes a migrated Disney subscription and all related entities (promotions, commitments, history).
        This endpoint is used exclusively for migration rollback purposes.
      operationId: deleteDisneySubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '204':
          description: Disney subscription deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/amazon':
    post:
      tags:
        - Amazon Prime Subscriptions
      summary: Migrate Amazon Prime subscription
      description: |
        Creates an Amazon Prime subscription with all related entities (promotions, commitments, bundle history).
        This is a migration-only endpoint that bypasses fraud validation and event generation.
      operationId: createAmazonPrimeSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonPrime'
      responses:
        '201':
          description: Amazon Prime subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonPrime'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/amazon/{id}':
    delete:
      tags:
        - Amazon Prime Subscriptions
      summary: Rollback Amazon Prime subscription migration
      description: |
        Deletes a migrated Amazon Prime subscription and all related entities (promotions, commitments, history).
        This endpoint is used exclusively for migration rollback purposes.
      operationId: deleteAmazonPrimeSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '204':
          description: Amazon Prime subscription deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/netflix':
    post:
      tags:
        - Netflix Subscriptions
      summary: Migrate Netflix subscription
      description: |
        Creates a Netflix subscription with all related entities (promotions, commitments, bundle history).
        This is a migration-only endpoint that bypasses fraud validation and event generation.
      operationId: createNetflixSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Netflix'
      responses:
        '201':
          description: Netflix subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Netflix'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'

  '/orgs/{org}/migrations/subscriptions/netflix/{id}':
    delete:
      tags:
        - Netflix Subscriptions
      summary: Rollback Netflix subscription migration
      description: |
        Deletes a migrated Netflix subscription and all related entities (promotions, commitments, history).
        This endpoint is used exclusively for migration rollback purposes.
      operationId: deleteNetflixSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      responses:
        '204':
          description: Netflix subscription deleted successfully
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  schemas:
    # ============================================================================
    # COMMON SCHEMAS
    # ============================================================================
    DateTime:
      type: string
      format: date-time
      description: Date and time. Format according to ISO 8601
      example: "2023-01-01T00:00:00Z"

    HealthResponse:
      type: object
      description: Health status response
      properties:
        persistence:
          type: string
          enum:
            - pass
            - fail
          description: Database connectivity status
          example: pass
        global:
          type: string
          enum:
            - pass
            - fail
          description: Overall service health status
          example: pass

    ErrorResponse:
      type: object
      description: Error response wrapper
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'

    ErrorDetails:
      type: object
      required:
        - code
        - message
        - reference
      properties:
        code:
          type: string
          description: Error code
          example: ERROR_CODE
        message:
          type: string
          description: Human-readable error message
          example: Error message
        reference:
          type: string
          format: uri
          description: Link to error documentation
          example: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    SubscriptionType:
      type: string
      description: Subscription type
      x-extensible-enum:
        - MOBILE
        - BROADBAND
        - LANDLINE
        - TV
        - SECURITY
        - DATA_SHARING
        - MULTISIM
        - DEVICE_INSURANCE
        - NETFLIX
        - APPLE_WATCH
        - AMAZON_PRIME
        - MAX
        - ORANGE_TV
        - DISNEY
      example: MAX

    # ============================================================================
    # CORE SUBSCRIPTION SCHEMAS
    # ============================================================================
    SubscriptionBase:
      type: object
      description: Base structure for subscription migration
      required:
        - status
        - creation_date
        - creation_user
        - last_status_reason
        - catalogue_commercial_product_id
        - legacy_account_id
        - bundle_related_info
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the subscription
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        type:
          description: Subscription type
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/SubscriptionType'
        status:
          type: string
          enum:
            - ACTIVE
            - DEACTIVATED
            - CANCELLED
          description: Subscription status
          example: ACTIVE
        activation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: |
                Activation date and time.
                - Required if status is ACTIVE or DEACTIVATED
                - Must be null if status is CANCELLED
        deactivation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: |
                Deactivation date and time.
                - Required if status is DEACTIVATED
                - Must be null if status is ACTIVE and CANCELLED
              example: "2025-01-05T03:30:15Z"
        last_status_update:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Last status update date and time
        last_status_reason:
          type: string
          description: |
            Reason for the last status update according to defined values. Check possible values in status table
            in https://developers.masstack.com/en/guides/subscriptions/lifecycle
          example: SUBSCRIPTION_ADDED_TO_BUNDLE
        last_updated_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Date and time when any field of the subscription was last updated
        catalogue_commercial_product_id:
          type: string
          description: Commercial product ID according to catalogue definition
          example: "7125"
        legacy_account_id:
          type: integer
          description: Legacy account id the subscription is linked to
          example: 245655
        account_id:
          type: string
          format: uuid
          description: Unique identifier of the account
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        creation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Subscription creation date and time
        creation_user:
          type: string
          description: User who created the subscription
          example: "migration.user@masmovil.com"
        creation_system:
          type: string
          description: System that created the subscription
          readOnly: true
          example: "rfm-migration-system"
        deactivation_user:
          type: string
          description: User who deactivated the subscription (if applicable)
          example: "admin.user@masmovil.com"
        deactivation_system:
          type: string
          description: System that deactivated the subscription (if applicable)
          readOnly: true
          example: "admin-portal"
        add_ons:
          type: array
          description: Ids of subscription applicable add-ons(value added services) according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/AddOn'
        free_units_packages:
          type: array
          description: Ids of free units packages according to catalogue definition
          writeOnly: true
          items:
            $ref: '#/components/schemas/FreeUnitsPackage'
        devices_related_info:
          description: Info about devices associated to the subscription
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/DevicesRelatedInfo'
        bundle_related_info:
          $ref: '#/components/schemas/BundleRelatedInfo'
        promotions:
          type: array
          description: Array of promotions associated to the subscription
          writeOnly: true
          items:
            $ref: '#/components/schemas/Promotion'
        bundles_history:
          type: array
          description: Historical bundle changes for the subscription
          items:
            $ref: '#/components/schemas/SubscriptionBundleHistory'

    AddOn:
      type: object
      required:
        - catalogue_add_on_id
        - creation_date
        - creation_user
        - last_updated_date
        - status
      properties:
        id:
          type: string
          description: Add-on unique identifier
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy add-on id linked to MySim/Apollo storage
          example: 457345
        catalogue_add_on_id:
          type: string
          description: Catalogue add-on ID
          example: "124"
        creation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: add-on creation date
        creation_system:
          type: string
          description: Info about the system that requested the addOn creation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        creation_user:
          type: string
          description: Info about the specific user that requested the addON creation. N/A if not available
          example: john.doe@masorange.es
        last_updated_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Date and time when any field of the addOn was last updated
        status:
          type: string
          description: |
            add-on status
          enum:
            - REQUESTED
            - ACTIVE
            - CANCELLED
            - DEACTIVATED
          example: "CANCELLED"
        activation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: add-on activation date
        deactivation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: add-on deactivation date
        deactivation_system:
          type: string
          readOnly: true
          example: "killflex.auth.masmovil.com"
        deactivation_user:
          type: string
          description: |
            Info about the specific user that requested the addOn deactivation. It contains the mas-stack authentication
            subject info when deactivation was requested by mas-stack authenticated user, other user info for legacy
            systems deactivations if available or N/A otherwise
          example: john.doe@masorange.es

    FreeUnitsPackage:
      type: object
      required:
        - catalogue_free_units_packages_id
        - activation_date
      properties:
        id:
          type: string
          description: Assigned Free Units Package ID
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Assigned Free Units Package legacy ID
          example: 457345
        catalogue_free_units_packages_id:
          type: string
          description: Catalogue free units packages ID
          example: "124"
        activation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Activation date and time of the package
        deactivation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Deactivation date and time of the package
              example: "2025-01-05T03:30:15Z"

    BundleRelatedInfo:
      type: object
      description: Bundle relation information for subscription migration
      required:
        - legacy_id
        - catalogue_bundled_product_id
        - catalogue_bundled_commercial_product_id
        - mandatory
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the bundle the subscription is included in
          readOnly: true
          example: abcf20cb-35df-4ffe-bca6-c0ed0c28cb00
        legacy_id:
          type: integer
          description: Legacy unique identifier of the bundle the subscription is included in
          example: 790224234
        catalogue_bundled_product_id:
          type: string
          description: Bundle product id according to catalogue definition
          example: "8342"
        catalogue_bundled_commercial_product_id:
          type: string
          description: Bundle commercial product id associated to subscription according to catalogue definition
          example: "8432_BUNDLED_XP"
        mandatory:
          type: boolean
          description: Indicates if subscription is mandatory for the bundle
          example: true

    Promotion:
      type: object
      description: Promotion data for migration
      required:
        - catalogue_promotion_id
        - creation_date
        - creation_user
        - status
      properties:
        catalogue_promotion_id:
          type: string
          description: Catalogue promotion ID
          example: "1572"
        creation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Promotion creation date
        creation_user:
          type: string
          description: User who created the promotion
          example: "migration.user@masmovil.com"
        creation_system:
          type: string
          description: System that created the promotion
          readOnly: true
          example: "rfm-migration-system"
        status:
          type: string
          enum:
            - ACTIVE
            - DEACTIVATED
            - EXPIRED
          description: Promotion status
          example: ACTIVE
        activation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Promotion activation date
        expiration_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Promotion expiration date
              example: "2025-01-05T03:30:15Z"
        deactivation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Promotion deactivation date
              example: "2025-01-05T03:30:15Z"
        deactivation_user:
          type: string
          description: User who deactivated the promotion
          example: "admin.user@masmovil.com"
        deactivation_system:
          type: string
          description: System that deactivated the promotion
          readOnly: true
          example: "admin-portal"
        status_detail:
          type: string
          description: Additional status details
          example: "AUTOMATICALLY_REMOVED"
        commitments:
          type: array
          description: Commitments associated to the promotion
          items:
            $ref: '#/components/schemas/Commitment'

    SubscriptionBundleHistory:
      type: object
      description: Bundle history record for subscription migration
      required:
        - legacy_bundle_id
        - last_status_reason
        - catalogue_bundled_product_id
        - catalogue_bundled_commercial_product_id
        - catalogue_commercial_product_id
        - start_date
        - end_date
      properties:
        bundle_id:
          type: string
          description: Unique identifier of the bundle
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        legacy_bundle_id:
          type: integer
          description: Legacy unique identifier of the bundle the subscription is included in
          example: 790224234
        last_status_reason:
          type: string
          description: Reason for bundle change
          writeOnly: true
          example: BUNDLE_MIGRATION
        catalogue_bundled_product_id:
          type: string
          description: Bundle product ID according to catalogue definition
          writeOnly: true
          example: "8342"
        catalogue_bundled_commercial_product_id:
          type: string
          description: Bundle commercial product ID according to catalogue definition
          writeOnly: true
          example: "8432_BUNDLED_3P"
        catalogue_commercial_product_id:
          type: string
          description: Commercial product ID according to catalogue definition
          writeOnly: true
          example: "7125"
        start_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Date and time when the subscription was added to the bundle
        end_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Date and time when the subscription was removed from the bundle
              example: "2025-01-05T03:30:15Z"
        mandatory:
          type: boolean
          description: Indicates if subscription is mandatory for the bundle
          example: true

    Commitment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Acquired commitment id
          readOnly: true
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        legacy_id:
          type: integer
          description: Legacy id for acquired commitment linked MySim/Apollo storage, to be deprecated but required when catalogue_term_id not available
          example: 345
        catalogue_id:
          type: string
          description: Catalogue Commitment ID
        expiration_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: End date
        cancellation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Cancellation date
        cancellation_system:
          type: string
          description: Info about the system that requested the commitment cancellation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com
        cancellation_user:
          type: string
          description: Info about the specific user that requested the commitment cancellation. N/A if not available
          example: john.doe@masorange.es
        creation_date:
          allOf:
            - $ref: '#/components/schemas/DateTime'
            - description: Commitment creation date
        creation_system:
          type: string
          description: Info about the system that requested the commitment creation. It contains the mas-stack authentication audience info.  N/A if not available
          readOnly: true
          example: killflex.auth.masmovil.com

    Device:
      type: object
      description: Devices associated to the subscription
      required:
        - catalogue_commercial_device_id
      properties:
        id:
          type: string
          format: uuid
          description: Device unique identifier
          example: "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39"
          readOnly: true
        catalogue_commercial_device_id:
          type: string
          description: "Commercial device id according to catalogue definition"
          example: "CDCVPU_150f5badaa706651e67c59061d373d7e7e"
        catalogue_device_id:
          type: string
          description: "Device id according to catalogue definition"
          example: "P09712MRC"
        shipping_order_id:
          type: string
          description: "Id of the shipping order related to the device according to logistic"
          example: "18395"
        pickup_order_id:
          type: string
          description: "Id of the pickup order related to the device according to reverse logistic"
          example: "P0000001"
        serial_number:
          type: string
          description: The serial number or any alphanumeric identifier of a particular device
          example: 9876543-AB-345
        mac_address:
          type: string
          description: A unique identifier assigned to the device network interface controller
          example: 00-B0-D0-63-C2-26
        acquisition_type:
          type: string
          description: Specifies the type of acquisition for the device
          enum:
            - BORROWED
            - FINANCED
            - ONE_TIME_PAYMENT
          example: BORROWED
        commitments:
          type: array
          items:
            $ref: '#/components/schemas/Commitment'

    DevicesRelatedInfo:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
        delivery_info:
          description: Info to grant delivery of devices
          type: object
          properties:
            delivery_type:
              type: string
              description: Delivery type
              enum:
                - SHOP
                - POST_OFFICE
                - CUSTOMER_ADDRESS
                - UNKNOWN
              example: CUSTOMER_ADDRESS
            dealer_code:
              type: string
              description: Dealer the store is associated to. Required if delivery_type is SHOP
              example: "1234"

    # ============================================================================
    # CREDIT LIMITS SCHEMAS
    # ============================================================================
    CreateCreditLimitsRequest:
      type: object
      description: Request to migrate credit limits for a subscription
      required:
        - subscription_type
        - credit_limits
      properties:
        subscription_type:
          type: string
          enum:
            - MOBILE
            - LANDLINE
          description: Type of subscription
          example: MOBILE
        credit_limits:
          type: array
          description: Array of credit limits to create
          minItems: 1
          items:
            $ref: '#/components/schemas/CreditLimit'

    CreditLimit:
      type: object
      description: Individual credit limit definition
      required:
        - credit_limit_id
        - credit_limit_value
        - reason
      properties:
        credit_limit_id:
          type: string
          enum:
            - MOBILE_SUBSCRIPTION_TOTAL_CREDIT_LIMIT
            - MOBILE_SUBSCRIPTION_PREMIUM_CREDIT_LIMIT
            - MOBILE_SUBSCRIPTION_INTERNATIONAL_VOICE_CREDIT_LIMIT
            - MOBILE_SUBSCRIPTION_ROAMING_VOICE_CREDIT_LIMIT
            - LANDLINE_SUBSCRIPTION_INTERNATIONAL_VOICE_CREDIT_LIMIT
            - LANDLINE_SUBSCRIPTION_PREMIUM_CREDIT_LIMIT
            - LANDLINE_SUBSCRIPTION_TOTAL_CREDIT_LIMIT
          description: Type of credit limit
          example: MOBILE_SUBSCRIPTION_TOTAL_CREDIT_LIMIT
        credit_limit_value:
          type: number
          format: double
          minimum: 0
          description: Credit limit value in currency units
          example: 300.0
        reason:
          type: string
          description: Reason for setting this credit limit
          example: "rfm krt migration"

    # ============================================================================
    # SEGMENT SCHEMAS
    # ============================================================================
    CreateSegmentRequest:
      type: object
      required:
        - segment_id
        - segment_value
        - reason
      properties:
        segment_id:
          type: string
          description: Segment identifier (must match pattern based on subscription type - OM% for postpaid mobile, OP% for prepaid, OC% for convergent)
          example: DEVICEOFFERSEGMENT
        segment_value:
          type: string
          description: Segment value
          example: "PREMIUM"
        reason:
          type: string
          description: Reason for segment creation
          example: "rfm krt"

    # ============================================================================
    # SPECIFIC SCHEMAS
    # ============================================================================
    Max:
      allOf:
        - $ref: '#/components/schemas/SubscriptionBase'
        - type: object
          required:
            - specific_data
          properties:
            specific_data:
              $ref: '#/components/schemas/MaxSpecificData'

    MaxSpecificData:
      type: object
      description: Max subscription specific data for migration
      required:
        - service_id
        - product_id
      properties:
        service_id:
          type: string
          description: Max internal ID that identifies the subscription
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        product_id:
          type: string
          description: Max product ID according to catalog definition
          example: "beam-max-svod-monthly"

    Disney:
      allOf:
        - $ref: '#/components/schemas/SubscriptionBase'
        - type: object
          required:
            - specific_data
          properties:
            specific_data:
              $ref: '#/components/schemas/DisneySpecificData'

    DisneySpecificData:
      type: object
      description: Disney subscription specific data for migration
      required:
        - user_id
        - service_id
        - product_id
      properties:
        user_id:
          type: string
          description: Disney internal ID that identifies the user
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        service_id:
          type: string
          description: Disney internal ID that identifies the subscription
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        product_id:
          type: string
          description: Disney product ID according to catalog definition
          example: "beam-max-svod-monthly"

    AmazonPrime:
      allOf:
        - $ref: '#/components/schemas/SubscriptionBase'
        - type: object
          required:
            - specific_data
          properties:
            specific_data:
              $ref: '#/components/schemas/AmazonPrimeSpecificData'

    AmazonPrimeSpecificData:
      type: object
      description: Amazon Prime subscription specific data for migration
      required:
        - entitlement_id
        - bundle_id
        - tier_id
        - product_id
      properties:
        entitlement_id:
          type: string
          description: Amazon Prime entitlement ID
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        bundle_id:
          type: string
          description: Amazon Prime bundle ID
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        tier_id:
          type: string
          description: Amazon Prime tier ID
          example: "prime_3_months_promo"
        product_id:
          type: string
          description: Amazon Prime product ID according to catalog definition
          example: "PRIME_3M_PROMO"

    Netflix:
      allOf:
        - $ref: '#/components/schemas/SubscriptionBase'
        - type: object
          required:
            - specific_data
          properties:
            specific_data:
              $ref: '#/components/schemas/NetflixSpecificData'

    NetflixSpecificData:
      type: object
      description: Netflix subscription specific data for migration
      required:
        - service_id
        - bundle_id
        - product_id
      properties:
        service_id:
          type: string
          description: Netflix internal ID that identifies the subscription service
          example: "Me7b7b7b7-b7b7-b7b7-b7b7-b7b7b7b7b7b7"
        bundle_id:
          type: string
          description: Netflix internal ID that identifies the bundle
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"
        product_id:
          type: string
          description: Netflix product ID according to catalog definition
          example: "d2af0bd9-c71b-42aa-a258-c9d9dc734bfc"

  parameters:
    OrgPathParam:
      in: path
      name: org
      description: Organization name (tenant)
      required: true
      schema:
        type: string
        enum:
          - euskaltel
          - telecable
          - rcable
          - racctel
      example: euskaltel

    SubscriptionIdPathParam:
      in: path
      name: id
      description: Subscription UUID
      required: true
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

  responses:
    DefaultErrorResponse:
      description: Any client or server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: ERROR_CODE
            message: Error message
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: INVALID_REQUEST
            message: The request is invalid
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    ForbiddenAccess:
      description: Forbidden access
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: FORBIDDEN_ORGANIZATION
            message: Access to organization not allowed
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: RESOURCE_NOT_FOUND
            message: The requested resource was not found
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: DATABASE_ACCESS_ERROR
            message: Internal server error
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

    Conflict:
      description: Resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: RESOURCE_ALREADY_EXISTS
            message: The requested resource already exists
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
