openapi: 3.0.0
info:
  description: |
    I am MasSubscriptions Sales API. My intention is to provide a set of REST services for handling sales requests.
  version: 1.0.0
  title: MasSubscriptionsSales
servers:
  - description: production
    url: 'https://subscriptions.masstack.com/v3/'
  - description: staging
    url: 'https://subscriptions.sta.masstack.com/v3/'

tags:
  - name: Promotions
    description: Contains all the information related to promotion commercial operations
  - name: CommercialTransactions
    description: Contains all the information related to any commercial transaction operations
  - name: Contracts
    description: Contract documents associated with commercial transaction

paths:
  '/orgs/{org}/sales/subscriptions/{subscription_id}/promotions':
    post:
      tags:
        - Promotions
      summary: Validates/Performs promotions sale.
      description: Validates/Performs promotions sale.
      operationId: salePromotions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalePromotionsRequest'
      responses:
        '201':
          description: Promotions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalePromotionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/bundles/{subscriptions_bundle_id}/subscriptions/promotions':
    post:
      tags:
        - Promotions
      summary: Validates/performs the sale of promotions for all applicable subscriptions in a given bundle.
      description: Validates/performs the sale of promotions for all applicable subscriptions in a given bundle according to the catalogue definition.
      operationId: saleBundlePromotions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalePromotionsRequest'
      responses:
        '201':
          description: Promotions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalePromotionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/subscriptions/{subscription_id}/promotions/{promotion_id}/terminate':
    post:
      tags:
        - Promotions
      summary: Terminates a promotion from a subscription.
      description: Terminates a promotion from a subscription.
      operationId: terminateSubscriptionPromotion
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/PromotionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateSubscriptionPromotionRequest'
      responses:
        '202':
          description: Termination process started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/bundles/{subscriptions_bundle_id}/promotions/terminate':
    post:
      tags:
        - Promotions
      summary: Terminate all subscriptions promotions that match the catalogue id, found in the given bundle when they apply according to catalogue definition.
      description: Terminate all subscriptions promotions that match the catalogue id, found in the given bundle when they apply according to catalogue definition.
      operationId: terminateBundleSubscriptionsPromotions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminatePromotionInAllBundleSubscriptionsRequest'
      responses:
        '202':
          description: Termination process started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions':
    get:
      tags:
        - CommercialTransactions
      summary: Get commercial transactions
      description: Returns a list of commercial transactions filtering by provided query params
      operationId: getCommercialTransactions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CustomersAccountIdQueryParam'
        - $ref: '#/components/parameters/LegacyFraudRequestIdQueryParam'
      responses:
        '200':
          description: List of commercial transactions matching the criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionSetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundles':
    post:
      tags:
        - CommercialTransactions
      summary: Creates the new bundle and starts the sale process
      description: Creates the new bundle and starts the sale process according to the provided information and validating against the catalogue definitions.
      operationId: sellBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleSaleRequest'
      responses:
        '201':
          description: Bundle and subscriptions created and sale started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleSaleCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundles/{subscriptions_bundle_id}/modify':
    post:
      tags:
        - CommercialTransactions
      summary: Modify an existing bundle to add, remove or modify subscriptions
      description: Modify an existing bundle to add, remove or modify subscriptions
      operationId: modifyBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleModificationRequest'
      responses:
        '201':
          description: Bundle modification requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleModifyCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/subscriptions/{subscription_id}/terminate':
    post:
      tags:
        - CommercialTransactions
      summary: Terminates a subscription
      description: Terminates an internally managed optional subscription or mandatory AgileTV subscription.
      operationId: terminateSubscription
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateSubscriptionRequest'
      responses:
        '200':
          description: Subscription termination requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/subscriptions/{subscription_id}/devices/{device_id}/swap':
    post:
      tags:
        - CommercialTransactions
      summary: Swap a subscription device
      description: Requests a device swap for a subscription
      operationId: swapSubscriptionDevice
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/SubscriptionIdPathParam'
        - $ref: '#/components/parameters/DeviceIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSwapRequest'
      responses:
        '200':
          description: Device swap requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundles/{subscriptions_bundle_id}/migrate':
    post:
      tags:
        - CommercialTransactions
      summary: Migrates an existing bundle
      description: Migrates an existing bundle. This also supports adding, removing or modifying subscriptions
      operationId: migrateBundle
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/BundleIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundleMigrationRequest'
      responses:
        '201':
          description: Bundle migration requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleMigrationCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_sale':
    get:
      tags:
        - CommercialTransactions
      summary: Get bundle sale commercial transaction list
      description: |
        Returns a list of bundle sale commercial transactions filtered by account or bundle.
        At least one of `customers_account_id` or `subscriptions_bundle_id` must be provided.
      operationId: getBundleSaleCommercialTransactions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CustomersAccountIdQueryParam'
        - $ref: '#/components/parameters/SubscriptionsBundleIdQueryParam'
      responses:
        '200':
          description: Bundle sale commercial transactions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleSaleCommercialTransactionSetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_sale/{commercial_transaction_id}':
    get:
      tags:
        - CommercialTransactions
      summary: Get a bundle sale commercial transaction
      description: Returns the bundle sale commercial transaction for the given identifier.
      operationId: getBundleSaleCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      responses:
        '200':
          description: Bundle sale commercial transaction response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleSaleCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_modify':
    get:
      tags:
        - CommercialTransactions
      summary: Get bundle modify commercial transaction list
      description: |
        Returns a list of bundle modify commercial transactions filtered by account or bundle.
        At least one of `customers_account_id` or `subscriptions_bundle_id` must be provided.
      operationId: getBundleModifyCommercialTransactions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CustomersAccountIdQueryParam'
        - $ref: '#/components/parameters/SubscriptionsBundleIdQueryParam'
      responses:
        '200':
          description: Bundle modify commercial transactions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleModifyCommercialTransactionSetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_modify/{commercial_transaction_id}':
    get:
      tags:
        - CommercialTransactions
      summary: Get a bundle modify commercial transaction
      description: Returns the bundle modify commercial transaction for the given identifier.
      operationId: getBundleModifyCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      responses:
        '200':
          description: Bundle modify commercial transaction response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleModifyCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_migration':
    get:
      tags:
        - CommercialTransactions
      summary: Get bundle migrate commercial transaction list
      description: |
        Returns a list of bundle migrate commercial transactions filtered by account or bundle.
        At least one of `customers_account_id` or `subscriptions_bundle_id` must be provided.
      operationId: getBundleMigrationCommercialTransactions
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CustomersAccountIdQueryParam'
        - $ref: '#/components/parameters/SubscriptionsBundleIdQueryParam'
      responses:
        '200':
          description: Bundle migrate commercial transactions response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleMigrationCommercialTransactionSetResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/bundle_migration/{commercial_transaction_id}':
    get:
      tags:
        - CommercialTransactions
      summary: Get a bundle migrate commercial transaction
      description: Returns the bundle migrate commercial transaction for the given identifier.
      operationId: getBundleMigrationCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      responses:
        '200':
          description: Bundle migrate commercial transaction response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleMigrationCommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/{commercial_transaction_id}':
    get:
      tags:
        - CommercialTransactions
      summary: Get a commercial transaction
      description: Returns a commercial transaction by its identifier.
      operationId: getCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      responses:
        '200':
          description: Commercial transaction response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    patch:
      tags:
        - CommercialTransactions
      summary: Patch a commercial transaction
      description: Applies a set of operations to a commercial transaction.
      operationId: patchCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationsSet'
      responses:
        '200':
          description: Commercial transaction patched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialTransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/{commercial_transaction_id}/contracts/{contract_id}':
    get:
      tags:
        - Contracts
      summary: Get commercial transaction contract by identifier
      description: Get info for a specific contract associated with a commercial transaction
      operationId: getCommercialTransactionContract
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
        - $ref: '#/components/parameters/ContractIdPathParam'
      responses:
        '200':
          description: Contract found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResponse'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          description: Contract not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/{commercial_transaction_id}/contracts/{contract_id}/documents':
    get:
      tags:
        - Contracts
      summary: Get commercial transaction contract documents
      description: Get documents associated with a specific contract in a commercial transaction
      operationId: getCommercialTransactionContractDocuments
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
        - $ref: '#/components/parameters/ContractIdPathParam'
      responses:
        '200':
          description: Contract documents found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractDocumentsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          description: Contract not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Document service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/orgs/{org}/sales/commercial_transactions/{commercial_transaction_id}/contracts':
    get:
      tags:
        - Contracts
      summary: Get commercial transaction contracts
      description: Get all contracts associated with a commercial transaction
      operationId: getCommercialTransactionContracts
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
        - $ref: '#/components/parameters/OffsetQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/DocumentsContractIdQueryParam'
      responses:
        '200':
          description: Contracts found for the commercial transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractsSet'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'
    post:
      tags:
        - Contracts
      summary: Add contract to commercial transaction
      description: Add a new contract to an existing commercial transaction
      operationId: addContractToCommercialTransaction
      parameters:
        - $ref: '#/components/parameters/OrgPathParam'
        - $ref: '#/components/parameters/CommercialTransactionIdPathParam'
      requestBody:
        description: Contract data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractRequest'
      responses:
        '201':
          description: Contract successfully added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/ForbiddenAccess'
        '404':
          $ref: '#/components/responses/CommercialTransactionNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

components:
  schemas:
    SalePromotionsRequest:
      type: object
      required:
        - execution_mode
        - requested_promotions
      properties:
        execution_mode:
          description: Defines whether the operation is simulated or actually performed
          allOf:
            - $ref: '#/components/schemas/ExecutionMode'
          example: VALIDATION
        validation_id:
          description: Identifier of the previously performed sale validation. Required only when execution mode is set to `EXECUTION`. This identifier expires after a limited time window, after which the sale must be validated again.
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        requested_promotions:
          description: List of promotions to be applied
          type: array
          items:
            $ref: '#/components/schemas/PromotionRequest'

    SalePromotionsResponse:
      type: object
      required:
        - validation_id
        - has_incompatibilities
        - subscriptions
      properties:
        validation_id:
          description: Identifier of the previously performed sale validation. Required only when execution mode is set to `EXECUTION`. This identifier expires after a limited time window, after which the sale must be validated again.
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        has_incompatibilities:
          type: boolean
          description: Indicates if there are any incompatibilities with the requested promotions
          example: true
        subscriptions:
          description: List of subscriptions affected by the sale
          allOf:
            - $ref: '#/components/schemas/SaleSubscriptionPromotionResponseSet'

    SaleSubscriptionPromotionResponseSet:
      type: array
      items:
        $ref: '#/components/schemas/SaleSubscriptionPromotionResponse'

    SaleSubscriptionPromotionResponse:
      type: object
      required:
        - subscription_id
        - incompatible_promotions
        - created_promotions
      properties:
        subscription_id:
          description: Subscription unique identifier
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        incompatible_promotions:
          description: List of promotions the subscription currently has that are incompatible with the sale. When `ExecutionMode` is set to `Execution`, these promotions will be automatically cancelled or deactivated as part of the sale process
          allOf:
            - $ref: '#/components/schemas/PromotionsResponseSet'
          type: string
        created_promotions:
          description: List of new created promotions
          allOf:
            - $ref: '#/components/schemas/PromotionsResponseSet'
          type: string

    SalePromotionsResponseSet:
      type: array
      items:
        $ref: '#/components/schemas/SalePromotionsResponse'

    TerminateSubscriptionPromotionRequest:
      type: object
      required:
        - reason
      properties:
        termination_date:
          type: string
          description: Date and time when the termination should take place. Format according to ISO 8601
          format: date
          example: 2022-12-01
        reason:
          $ref: '#/components/schemas/PromotionTerminationReasons'

    TerminatePromotionInAllBundleSubscriptionsRequest:
      type: object
      required:
        - reason
        - catalogue_promotion_id
      properties:
        termination_date:
          type: string
          description: Date and time when the termination should take place. Format according to ISO 8601
          format: date
          example: 2022-12-01
        reason:
          $ref: '#/components/schemas/PromotionTerminationReasons'
        catalogue_promotion_id:
          type: string
          description: Catalogue promotion ID to be terminated in all applicable subscriptions within the bundle
          example: "123"

    PromotionTerminationReasons:
      type: string
      enum:
        - AUTOMATICALLY_REMOVED
        - MANUALLY_REMOVED
        - OTHER
        - PROMOTION_INCOMPATIBILITY
        - SUBSCRIPTION_DEACTIVATION
      description: Reason for the termination
      example: "SUBSCRIPTION_DEACTIVATION"

    ExecutionMode:
      type: string
      enum:
        - EXECUTION
        - VALIDATION
      example: EXECUTION

    CatalogueSaleType:
      type: string
      description: Type of commercial process used to validate against catalogue. These values are standardized in this API and will be mapped to the specific catalogue values.
      enum:
        - NEW_SALE
        - CROSS_SELL
        - MIGRATION
        - ADD_SUBSCRIPTION
      example: NEW_SALE

    CommercialTransactionStatus:
      type: string
      description: Current status of the commercial transaction
      enum:
        - IN_PROGRESS
        - COMPLETED
        - CANCELLED
      example: COMPLETED

    CommercialTransactionType:
      type: string
      description: Type of commercial transaction
      enum:
        - BUNDLE_SALE
        - BUNDLE_MIGRATION
        - BUNDLE_MODIFICATION
        - ADDRESS_CHANGE
        - TECH_CHANGE
        - TERMINATE_SUBSCRIPTION
      example: BUNDLE_SALE

    SubscriptionTerminationReason:
      type: string
      description: Reason for the termination
      enum:
        - ACCOUNT_MIGRATION
        - BUNDLE_CANCELLATION
        - BUNDLE_DEACTIVATION
        - BUNDLE_MIGRATION
        - FRAUD_CHECK_REJECTION
        - NON_PAYMENT
        - OTHER
        - PAYMENT_ERROR
        - PROVISIONING_ISSUE
        - SUBSCRIBER_RESIGNATION
        - DEACTIVATED_ON_THIRD_PARTY
        - AUTOMATICALLY_REMOVED
      example: SUBSCRIBER_RESIGNATION

    ContractDeliveryChannel:
      type: string
      description: Delivery channel used to send the contract. Default value is UNKNOWN
      enum:
        - APPLICATION
        - PAPER
        - EMAIL
        - UNKNOWN
      example: EMAIL

    BundleSaleRequest:
      type: object
      required:
        - catalogue_bundled_product_id
        - customers_account_id
        - dealers_dealer_id
        - risk_evaluation_data
        - subscriptions
        - type
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/CatalogueSaleType'
        catalogue_bundled_product_id:
          type: string
          description: Bundled product id according to catalogue definition
          example: 8432
        customers_account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer according to dealers system
          example: "1234"
        risk_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/RiskEvaluationData'
        financial_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/FinancialEvaluationData'
        signature_process_id:
          type: string
          description: ID of the resource containing subscriber valid signature to purchase subscription
          example: 18395
        legacy_sell_id:
          type: string
          description: Legacy field to relate bundle to external sale operation
          example: 242940268
        payment_data:
          allOf:
            - $ref: '#/components/schemas/PaymentData'
        subscriptions:
          allOf:
            - $ref: '#/components/schemas/BundleSubscriptions'
        contract_delivery_channel:
          allOf:
            - $ref: '#/components/schemas/ContractDeliveryChannel'
        legacy_origin_app_id:
          type: integer
          description: Application ID according to MySim. Required if not Orange TV Libre sale
          example: 4

    TerminateSubscriptionRequest:
      type: object
      required:
        - reason
        - dealers_dealer_id
      properties:
        reason:
          allOf:
            - $ref: '#/components/schemas/SubscriptionTerminationReason'
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer according to dealers system
          example: "1234"
        promotion_commitments_excluded:
          type: array
          items:
            type: string
            format: uuid
          description: Promotion commitment IDs excluded from the deactivation process
        device_commitments_excluded:
          type: array
          items:
            type: string
            format: uuid
          description: Device commitment IDs excluded from the deactivation process
        add_on_commitments_excluded:
          type: array
          items:
            type: string
            format: uuid
          description: Add-on commitment IDs excluded from the deactivation process

    DeviceSwapRequest:
      type: object
      description: Device swap request. dealers_dealer_id and transfer_with are required. Only transfer swaps are supported in sales.
      required:
        - dealers_dealer_id
        - transfer_with
      properties:
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer according to dealers system
          example: "1234"
        transfer_with:
          type: string
          format: uuid
          description: Device identifier to transfer with
          example: fd2fcd90-2218-4ef1-917b-7ce5f35eee1c

    BundleModificationRequest:
      type: object
      required:
        - dealers_dealer_id
        - customers_account_id
      properties:
        customers_account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer
          example: "1234"
        risk_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/RiskEvaluationData'
        financial_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/FinancialEvaluationData'
        signature_process_id:
          type: string
          description: ID of the resource containing subscriber valid signature to purchase subscription
          example: 18395
        legacy_sell_id:
          type: string
          description: Legacy field to relate bundle to external sale operation
          example: 242940268
        payment_data:
          allOf:
            - $ref: '#/components/schemas/PaymentData'
        add_subscriptions:
          description: List of subscriptions to add to the bundle. Currently only OTT subscriptions can be added using this endpoint
          allOf:
            - $ref: '#/components/schemas/BundleSubscriptions'
        remove_subscriptions:
          description: List of subscription IDs to remove from the bundle. Currently only OTT subscriptions can be removed using this endpoint
          type: array
          items:
            type: string
            format: uuid
        contract_delivery_channel:
          allOf:
            - $ref: '#/components/schemas/ContractDeliveryChannel'
        legacy_origin_app_id:
          type: integer
          description: Application ID according to MySim. Required if not Orange TV Libre sale
          example: 4

    BundleMigrationRequest:
      type: object
      required:
        - customers_account_id
        - dealers_dealer_id
        - risk_evaluation_data
      properties:
        customers_account_id:
          type: string
          description: Unique identifier of the account
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
          format: uuid
        catalogue_bundled_product_id:
          type: string
          description: Bundled product ID of the new bundle according to catalogue definition
          example: 8432
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer
          example: "1234"
        risk_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/RiskEvaluationData'
        financial_evaluation_data:
          allOf:
            - $ref: '#/components/schemas/FinancialEvaluationData'
        signature_process_id:
          type: string
          description: ID of the resource containing subscriber valid signature to purchase subscription
          example: 18395
        legacy_sell_id:
          type: string
          description: Legacy field to relate bundle to external sale operation
          example: 242940268
        payment_data:
          allOf:
            - $ref: '#/components/schemas/PaymentData'
        add_subscriptions:
          description: List of subscriptions to add to the bundle. Currently only OTT subscriptions can be added using this endpoint
          allOf:
            - $ref: '#/components/schemas/BundleSubscriptions'
        remove_subscriptions:
          description: List of subscription IDs to remove from the bundle. Currently only OTT subscriptions can be removed using this endpoint
          type: array
          items:
            type: string
            format: uuid
        modify_subscriptions:
          description: List of subscriptions to modify in the bundle
          allOf:
            - $ref: '#/components/schemas/BundleMigrationModifySubscriptions'
        contract_delivery_channel:
          allOf:
            - $ref: '#/components/schemas/ContractDeliveryChannel'
        legacy_origin_app_id:
          type: integer
          description: Application ID according to MySim. Required if not Orange TV Libre sale
          example: 4

    BundleMigrationModifySubscriptions:
      type: object
      properties:
        mobile:
          type: array
          items:
            $ref: '#/components/schemas/BundleMigrationModifySubscriptionRequest'
        tv:
          type: array
          items:
            $ref: '#/components/schemas/BundleMigrationModifySubscriptionRequest'

    BundleMigrationModifySubscriptionRequest:
      type: object
      properties:
        id:
          type: string
          description: Subscription unique identifier
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        catalogue_bundled_commercial_product_id:
          type: string
          description: Catalogue bundled commercial product ID
          example: "9543_BUNDLED_XP"
        promotions:
          type: array
          description: Promotions to apply to the subscription
          items:
            $ref: '#/components/schemas/PromotionRequest'
        devices_related_info:
          description: Info about devices associated to the subscription
          allOf:
            - $ref: '#/components/schemas/DevicesRelatedInfo'
        free_units_packages:
          type: array
          description: Ids of free units packages according to catalogue definition
          items:
            $ref: '#/components/schemas/FreeUnitsPackage'

    ModifySubscriptionRequest:
      type: object
      properties:
        id:
          type: string
          description: Subscription unique identifier
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        #        promotions:
        #          type: array
        #          description: Ids of applicable promotions according to catalogue definition
        #          items:
        #            $ref: '#/components/schemas/PromotionRequest'
        #        add_ons:
        #          type: array
        #          description: Ids of applicable add-ons(value added services) according to catalogue definition
        #          items:
        #            $ref: '#/components/schemas/AddOn'
        #        free_units_packages:
        #          type: array
        #          description: Ids of free units packages according to catalogue definition
        #          items:
        #            $ref: '#/components/schemas/FreeUnitsPackage'
        devices_related_info:
          description: Info about devices associated to the subscription
          allOf:
            - $ref: '#/components/schemas/DevicesRelatedInfo'

    FinancialEvaluationData:
      type: object
      required:
        - credit_limit
        - credit_limit_available
      properties:
        credit_limit:
          type: number
          description: Credit limit assigned to the subscriber
          example: 1000
        credit_limit_available:
          type: number
          description: Credit limit available for the subscriber
          example: 1000

    RiskEvaluationData:
      type: object
      required:
        - pre_scoring_id
      properties:
        pre_scoring_id:
          type: string
          description: |
            A subscriber scoring check is required before bundle creation and the scoring request id must be provided 
            in this field
          example: 18395
        score_value:
          type: integer
          description: Score value calculated by risk system
          example: 71
        upfront:
          type: number
          description: Upfront calculated by risk system
          example: 0.0

    PaymentData:
      type: object
      required:
        - total_amount
        - tax_amount
      properties:
        total_amount:
          type: number
          description: Total amount of the payment
          example: 149.0
        tax_amount:
          type: number
          description: Tax amount of the payment
          example: 10
        first_invoice_payment:
          type: number
          description: First invoice advance payment amount
          example: 5.0
        point_of_sale_payment:
          type: number
          description: Point of sale payment amount
          example: 33.0
        platform:
          type: string
          description: |
            Platform used for the payment
          x-extensible-enum:
            - ADYEN
          example: "ADYEN"
        transaction_id:
          type: string
          description: Transaction ID of the payment
          example: "PLC6640C65E45847BC"
        link:
          type: string
          description: Link to the payment platform
          example: "https://test.adyen.link/PLC6640C65E45847BC"
        external_reference:
          type: string
          description: External reference of the payment
          example: "2311BDXI1880"

    BundleSubscriptions:
      type: object
      description: Set of subscriptions to include on bundle grouped by type
      properties:
        mobile:
          type: array
          description: Mobile subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Mobile'
        broadband:
          type: array
          description: Broadband subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Broadband'
        landline:
          type: array
          description: Landline subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Landline'
        tv:
          type: array
          description: Legacy tv subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Tv'
        amazon_prime:
          type: array
          description: Amazon Prime subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/AmazonPrime'
        agile_tv:
          type: array
          description: Agile Tv subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/AgileTv'
        netflix:
          type: array
          description: Netflix subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Netflix'
        max:
          type: array
          description: Max subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Max'
        orange_tv:
          type: array
          description: Orange Tv subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/OrangeTv'
        disney:
          type: array
          description: Disney subscriptions included in the bundle
          items:
            $ref: '#/components/schemas/Disney'

    Subscription:
      type: object
      required:
        - mandatory
      properties:
        catalogue_bundled_commercial_product_id:
          type: string
          description: Bundle commercial product id associated to subscription according to catalogue definition
          example: 8432_BUNDLED_3P
        mandatory:
          type: boolean
          description: Specifies if subscription is mandatory for the given bundle
          example: true
        promotions:
          type: array
          description: Ids of applicable promotions according to catalogue definition
          items:
            $ref: '#/components/schemas/PromotionRequest'
        add_ons:
          type: array
          description: Ids of applicable add-ons(value added services) according to catalogue definition
          items:
            $ref: '#/components/schemas/AddOn'
        free_units_packages:
          type: array
          description: Ids of free units packages according to catalogue definition
          items:
            $ref: '#/components/schemas/FreeUnitsPackage'
        devices_related_info:
          description: Info about devices associated to the subscription
          allOf:
            - $ref: '#/components/schemas/DevicesRelatedInfo'

    Mobile:
      type: object
      required:
        - msisdn
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        msisdn:
          type: string
          description: MSISDN (Mobile Station International Subscriber Directory Number) formatted following E.164 format
          example: 34611223344
        mobile_portability_info:
          allOf:
            - $ref: '#/components/schemas/MobilePortabilityInfo'
        sim:
          allOf:
            - $ref: '#/components/schemas/Sim'

    Broadband:
      type: object
      description: Broadband subscriptions included in the bundle
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - territory_owner
      properties:
        access_id:
          type: string
          description: Id that identifies the specific access to the network used by the subscription
          example: IUA-XXX
        vacant_loop:
          type: boolean
          description: Indicates if there is a vacant loop for provision
        territory_owner:
          type: string
          description: Territory owner of the network infrastructure
          example: FIBMM01
        access_reuse_info_allowed:
          type: boolean
          description: Indicates if the client consents the access to installation info for access reuse
          example: true
        legacy_service_id:
          type: string
          description: Legacy service id that identifies the broadband service in OSS
          example: MYSIM_2331123
        installation_address:
          description: Indicates the address where the service is installed
          allOf:
            - $ref: '#/components/schemas/Address'

    Landline:
      type: object
      description: Landline subscriptions included in the bundle
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - contact_info
        - fixed_phone_number
      properties:
        fixed_phone_number:
          type: string
          description: Landline fixed phone number
          example: "913312244"
        installation_address:
          description: Indicates the address where the service is installed
          allOf:
            - $ref: '#/components/schemas/Address'
        contact_info:
          description: Contact info of the person that must be contacted for installation process
          allOf:
            - required:
                - phone_number
            - $ref: '#/components/schemas/ContactInfo'
        fixed_portability_info:
          allOf:
            - $ref: '#/components/schemas/FixedPortabilityInfo'

    AmazonPrime:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object

    AgileTv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - devices_related_info

    Netflix:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object

    Max:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object

    OrangeTv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      required:
        - registration_email
        - devices_related_info
      properties:
        registration_email:
          type: string
          description: Email address linked to the Orange TV subscription
          example: john.doe@mail.com

    Disney:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object

    Sim:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: SIM type
          x-extensible-enum:
            - SIM
            - MICROSIM
            - ESIM
            - NANOSIM
          example: ESIM
        iccid:
          type: string
          description: ICCID(Integrated Circuit Card ID) that identifies the SIM and is visible for the customer
          example: "12341234123412341234123412341234"

    MobilePortabilityInfo:
      type: object
      required:
        - donor_operator_id
        - donor_data
      description: Data required to perform mobile portability
      properties:
        donor_operator_id:
          type: string
          description: Donor operator id according to applicable country authority
          example: 31
        donor_data:
          $ref: '#/components/schemas/DonorData'
        portability_process_initial_date:
          type: string
          format: date-time
          description: Initial date of the portability process. Format according to ISO 8601
          example: "2017-09-15T22:00:00Z"
        internal_portability:
          type: boolean
          description: Indicates if the portability is done between operators that share infrastructure
          example: true
        donor_iccid:
          type: string
          description: ICCID of the donor SIM card
          example: "8934000000000000002"
        donor_billing_type:
          type: string
          description: Billing type of the donor
          example: PREPAY
        one_time_password_id:
          type: string
          description: One time password process id used for line ownership check
          example: ee0881ff-6050-43bd-a4b3-b7e8fd0474d9

    FixedPortabilityInfo:
      type: object
      required:
        - donor_operator_id
        - internal_portability
        - installation_required
        - donor_data
      properties:
        donor_operator_id:
          type: string
          description: |
            Donor operator id according to applicable country authority. e.g: Spain -> CNMC (https://numeracionyoperadores.cnmc.es)
          example: 31
        scheduled_portability_date:
          type: string
          format: date-time
          description: |
            Earliest portability date if the portability must not be done as soon as possible as it would be done by default. Format according to ISO 8601
          example: "2017-09-15T22:00:00Z"
        internal_portability:
          type: boolean
          description: This indicates if the portability is done between operators that share infrastructure
          example: true
        installation_required:
          type: boolean
          description: This indicates if a technician visit to the house is required for installation
          example: false
        donor_data:
          $ref: '#/components/schemas/DonorData'

    DonorData:
      type: object
      required:
        - name
        - identity_document
      description: Personal data of the owner before portability
      properties:
        name:
          type: string
          description: Person's name
        surname:
          type: string
          description: Person's surname
        second_surname:
          type: string
          description: Person's second surname
        identity_document:
          $ref: '#/components/schemas/IdentityDocument'

    ContactInfo:
      type: object
      required:
        - name
        - surname
        - identity_document
      properties:
        name:
          type: string
          example: Diego
        surname:
          type: string
          example: Landolfi Espi
        identity_document:
          $ref: '#/components/schemas/IdentityDocument'
        phone_number:
          type: string
          example: "696288378"
        email_address:
          type: string
          example: diego@hotmail.com

    Address:
      type: object
      required:
        - street_name
        - city
        - postal_code
      properties:
        street_type:
          type: string
          example: Calle
        street_name:
          type: string
          example: Tellez
        house_number:
          type: string
          example: "12"
        additional_info:
          type: string
          example: Esc. Dcha 3 C
        city:
          type: string
          example: Riaza
        province:
          type: string
          example: Segovia
        country:
          type: string
          example: es
        postal_code:
          type: string
          example: "40500"
        address_code:
          type: string
          example: "28000010758100012    OA   004C       "
        address_additional_id:
          description: Additional address info to improve the accuracy of feasibility check of access reuse
          type: string
          example: "123443554"

    IdentityDocument:
      type: object
      description: Identification document
      properties:
        type:
          type: string
          enum:
            - NIF
            - PASSPORT
            - CIF
            - NIE
            - UNKNOWN
          example: NIF
        id:
          type: string
          example: "5012341234"

    AddOn:
      type: object
      required:
        - catalogue_value_added_service_id
      properties:
        catalogue_value_added_service_id:
          type: string
          description: Catalogue add-on ID
          example: "124"
        promotions:
          type: array
          description: Ids of applicable promotions according to catalogue definition
          items:
            $ref: '#/components/schemas/PromotionRequest'

    FreeUnitsPackage:
      type: object
      required:
        - catalogue_free_units_package_id
      properties:
        catalogue_free_units_package_id:
          type: string
          description: Catalogue free units packages ID
          example: "124"

    DevicesRelatedInfo:
      type: object
      required:
        - devices
      properties:
        devices:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Device'
        pre_booking:
          $ref: '#/components/schemas/PreFinancingBooking'
        delivery_info:
          $ref: '#/components/schemas/DeliveryInfo'

    DeliveryInfo:
      description: Info to grant delivery of devices
      type: object
      required:
        - delivery_type
        - address
        - contact_info
      properties:
        contact_info:
          $ref: '#/components/schemas/ContactInfo'
        address:
          $ref: '#/components/schemas/Address'
        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"

    Device:
      type: object
      description: Devices associated to the subscription
      required:
        - catalogue_commercial_device_id
      properties:
        catalogue_commercial_device_id:
          type: string
          description: Commercial device id according to catalogue definition
          example: CDCVPU_150f5badaa706651e67c59061d373d7e7e
        reservation_id:
          type: string
          description: Id for device reservation
          example: "1567"
        signature_process_id:
          type: string
          description: Id of the resource containing subscriber valid signature to purchase device
          example: "18395"
        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
        imei:
          type: string
          description: The International Mobile Equipment Identity of the device
          example: AA-BBBBBB-CCCCCC-D
        commitments:
          type: array
          items:
            $ref: '#/components/schemas/Commitment'
        insurable_amount:
          type: number
          description: |
            The insurable value of the device, representing the maximum coverage amount for insurance purposes. A null value indicates that the device is not insurable
          example: 135.49
        promotions:
          type: array
          description: Ids of applicable promotions according to catalogue definition
          items:
            $ref: '#/components/schemas/PromotionRequest'

    PreFinancingBooking:
      type: object
      required:
        - order_id
        - financial_entity
        - agreed_commercial_consents
        - agreed_gdpr
        - status
        - granted_amount
        - credit_line_amount
      properties:
        order_id:
          type: string
          description: Order identifier
          example: 123213asdsa
        authorization_id:
          type: string
          description: Authorization identifier
          example: ''
        financial_entity:
          type: string
          description: Financial entity involved
          enum:
            - MASMOVIL
            - XCF
            - CELETEMLC
            - SABADELL
            - CETELEMLC
            - CETELEM
            - BBVA
            - NONE
            - UNKNOWN
          example: BBVA
        agreed_commercial_consents:
          type: boolean
          description: Indicates if the commercial consents have been agreed
          example: true
        agreed_gdpr:
          type: boolean
          description: Indicates if the GDPR has been agreed
          example: true
        status:
          type: string
          description: Status of the pre-booking
          enum:
            - ACCEPTED
            - REJECTED
        granted_amount:
          type: number
          description: Granted amount in the pre-booking
          example: 100.0
        credit_line_amount:
          type: number
          description: Credit line amount in the pre-booking
          example: 10.0

    Commitment:
      type: object
      properties:
        catalogue_term_id:
          type: string
          description: Catalogue term id
          example: "123"

    PromotionRequest:
      type: object
      required:
        - catalogue_promotion_id
      properties:
        catalogue_promotion_id:
          type: string
          description: Catalogue promotion ID
          example: "123"
        activation_date:
          type: string
          description: Promotion activation date. Format according to ISO 8601
          format: date
          example: 2022-12-01

    PromotionsResponseSet:
      type: array
      items:
        $ref: '#/components/schemas/PromotionResponse'

    PromotionResponse:
      type: object
      required:
        - catalogue_id
      properties:
        id:
          description: Promotion unique identifier
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        catalogue_id:
          type: string
          description: Catalogue promotion ID
          example: "123"
        activation_date:
          type: string
          description: Promotion activation date. Format according to ISO 8601
          format: date
          example: 2022-12-01
        expiration_date:
          type: string
          description: Promotion expiration date. Format according to ISO 8601
          format: date
          example: 2022-12-01
        deactivation_date:
          type: string
          description: Promotion expiration date. Format according to ISO 8601
          format: date
          example: 2022-12-01

    CommercialTransactionResponse:
      type: object
      required:
        - id
        - customers_account_id
        - status
        - type
        - dealers_dealer_id
        - creation_date
        - creation_user
        - creation_system
        - last_updated_date
      properties:
        id:
          type: string
          format: uuid
          description: Commercial transaction unique identifier
          example: "123e4567-e89b-12d3-a456-426614174000"
        legacy_id:
          type: string
          description: Legacy identifier for backward compatibility
          example: "242940268"
        customers_account_id:
          type: string
          description: Account unique identifier
          example: "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39"
        status:
          description: Current status of the commercial transaction
          allOf:
            - $ref: '#/components/schemas/CommercialTransactionStatus'
        type:
          description: Type of commercial transaction
          allOf:
            - $ref: '#/components/schemas/CommercialTransactionType'
        dealers_dealer_id:
          type: string
          description: Unique identifier of the dealer according to dealers system.
          example: "1234"
        creation_date:
          type: string
          format: date-time
          description: Date and time when the transaction was created. Format according to ISO 8601
          example: "2024-01-15T10:30:00Z"
        creation_user:
          type: string
          description: User who created the transaction
          example: "john.doe@example.com"
        creation_system:
          type: string
          description: System that created the transaction
          example: "SALES_API"
        last_updated_date:
          type: string
          format: date-time
          description: Date and time of the last update. Format according to ISO 8601
          example: "2024-01-15T10:35:00Z"
        contract_id:
          type: string
          format: uuid
          description: Contract document identifier
          example: "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39"
        legacy_fraud_request_id:
          type: string
          description: Legacy fraud request identifier according to MySim
          example: "FRD_18395"
        legacy_work_order_id:
          type: string
          description: Legacy work order identifier according to MySim
          example: "WO_2024_5678"
        status_detail:
          type: string
          description: Additional detail about the commercial transaction status
          example: FRAUD_CHECK_REJECTION

    CommercialTransactionSubscriptionResponse:
      type: object
      properties:
        subscription_type:
          $ref: '#/components/schemas/CommercialTransactionSubscriptionType'
        catalogue_commercial_product_id:
          type: string
          description: Catalogue bundled commercial product ID
          example: "8139_BUNDLED_3P"
        devices:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionDeviceResponse'
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionAddOnResponse'
        free_units_packages:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionFreeUnitsPackageResponse'

    CommercialTransactionFreeUnitsPackageResponse:
      type: object
      properties:
        catalogue_free_units_package_id:
          type: string
          description: Catalogue free units package ID
          example: "FUP_001"

    CommercialTransactionAddOnResponse:
      type: object
      properties:
        catalogue_value_added_service_id:
          type: string
          description: Catalogue value added service ID
          example: "VAS_001"

    CommercialTransactionDeviceResponse:
      type: object
      properties:
        catalogue_commercial_device_id:
          type: string
          description: Catalogue commercial device ID
          example: "01389691380"

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

    BundleSaleCommercialTransactionResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommercialTransactionResponse'
        - type: object
      required:
        - subscriptions_bundle_id
        - catalogue_bundled_product_id
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionSubscriptionResponse'
          description: Subscriptions added in the commercial transaction
        subscriptions_bundle_id:
          type: string
          format: uuid
          description: Created bundle's unique identifier
        catalogue_bundled_product_id:
          type: string
          description: Created bundle's catalogue bundled product ID according to catalogue definition
          example: 8432

    CommercialTransactionSetResponse:
      type: array
      items:
        $ref: '#/components/schemas/CommercialTransactionResponse'

    BundleSaleCommercialTransactionSetResponse:
      type: array
      items:
        $ref: '#/components/schemas/BundleSaleCommercialTransactionResponse'

    BundleModifyCommercialTransactionSetResponse:
      type: array
      items:
        $ref: '#/components/schemas/BundleModifyCommercialTransactionResponse'

    BundleMigrationCommercialTransactionSetResponse:
      type: array
      items:
        $ref: '#/components/schemas/BundleMigrationCommercialTransactionResponse'

    OperationsSet:
      type: array
      items:
        $ref: '#/components/schemas/Operation'

    Operation:
      type: object
      required:
        - op
      properties:
        op:
          type: string
          description: Operation to be performed on th entity
          enum:
            - replace
          example: "replace"
        path:
          type: string
          description: Path to the field to be updated
          example: "/status"
        value:
          description: Value to use for the operation
          example: "DEACTIVATED"

    BundleModifyCommercialTransactionResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommercialTransactionResponse'
        - type: object
      properties:
        subscriptions_bundle_id:
          type: string
          format: uuid
          description: Origin bundle's unique identifier
        subscriptions_added:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionSubscriptionResponse'
          description: Subscriptions added in the commercial transaction
        subscriptions_removed:
          description: List of subscription IDs removed in the commercial transaction
          type: array
          items:
            type: string
            format: uuid

    BundleMigrationCommercialTransactionResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/CommercialTransactionResponse'
        - type: object
      required:
        - subscriptions_bundle_id
        - catalogue_bundled_product_id
      properties:
        subscriptions_bundle_id:
          type: string
          format: uuid
          description: Origin bundle's unique identifier
        catalogue_bundled_product_id:
          type: string
          description: Origin bundle's catalogue bundled product ID according to catalogue definition
          example: 8432
        destination_subscriptions_bundle_id:
          type: string
          format: uuid
          description: Destination bundle's unique identifier
        destination_catalogue_bundled_product_id:
          type: string
          description: Destination bundle's catalogue bundled product ID according to catalogue definition
          example: 8432
        subscriptions_added:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionSubscriptionResponse'
          description: Subscriptions added in the commercial transaction
        subscriptions_removed:
          description: List of subscription IDs removed in the commercial transaction
          type: array
          items:
            type: string
            format: uuid
        subscriptions_modified:
          type: array
          items:
            $ref: '#/components/schemas/CommercialTransactionSubscriptionResponse'
          description: Subscriptions modified in the commercial transaction

    Tv:
      type: object
      allOf:
        - $ref: '#/components/schemas/Subscription'
        - type: object
      properties:
        specific_data:
          $ref: '#/components/schemas/TvSpecificData'

    TvSpecificData:
      type: object
      description: TV subscription specific info
      required:
        - registration_email
        - contact_number
        - identity_document
      properties:
        service_id:
          type: string
          description: TV service id that identifies the subscription on the TV provider side
          example: 959608034
        registration_email:
          type: string
          description: Email address linked to the TV subscription
          example: john.doe@mail.com
        technical_installation_required:
          type: boolean
          description: Indicates if a technician visit required for the installation
          example: false
        contact_number:
          type: string
          description: Contact number for the TV subscription
          example: 696288378
        identity_document:
          $ref: '#/components/schemas/IdentityDocument'

    ContractRequest:
      type: object
      required:
        - documents_contract_id
        - documents_owner_id
      properties:
        documents_contract_id:
          type: string
          description: Documents service contract id
          example: 12345678-1234-1234-1234-123456789012
        documents_owner_id:
          type: string
          description: Documents service owner id
          example: 87654321-4321-4321-4321-210987654321

    ContractResponse:
      type: object
      required:
        - documents_contract_id
      properties:
        id:
          type: string
          format: uuid
          description: Contract id
          example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39
        documents_contract_id:
          type: string
          description: Documents service contract id
          example: 12345678-1234-1234-1234-123456789012
        creation_date:
          type: string
          description: Creation date according to ISO 8601
          format: date-time
          example: 2025-01-05T03:30:15Z
        creation_user:
          type: string
          description: User who created the contract
          example: john.doe@masorange.es
        creation_system:
          type: string
          description: System that created the contract
          example: mas-subscriptions.auth.masmovil.com
        last_updated_date:
          type: string
          description: Last update date according to ISO 8601
          format: date-time
          example: 2025-01-06T10:30:15Z
        last_updated_user:
          type: string
          description: User who last updated the contract
          example: jane.smith@masorange.es

    ContractDocumentResponse:
      type: object
      description: Contract document information
      properties:
        url_expiration_date:
          type: string
          format: date-time
          description: Expiration date of the public URL
          example: 2023-01-27T03:44:52.000Z
        public_url:
          type: string
          description: Public URL to access the document
          example: https://storage.googleapis.com/mas-documents-prod/cbd2e693-d71a-4cee-8313-1972acc0394d
        media_type:
          type: string
          description: Media type of the document
          example: application/pdf
        name:
          type: string
          description: Name of the document
          example: my_doc_name
        documents_contract_id:
          type: string
          description: Documents service contract id
          example: a570614e-8a66-4d93-b329-7a2c9d6f0ce8

    ContractDocumentsSet:
      type: object
      description: Set of contract documents
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/ContractDocumentResponse'

    ContractsSet:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContractResponse'
      allOf:
        - $ref: '#/components/schemas/PaginationData'
        - type: object

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

    ErrorDetails:
      type: object
      required:
        - code
        - message
        - reference

    PaginationData:
      type: object
      required:
        - limit
        - offset
        - total
      properties:
        limit:
          type: integer
          description: Limit of items per response
          example: 5
        offset:
          type: integer
          description: Limit of items per response
          example: 15
        total:
          type: integer
          description: Total number of results for search criteria
          example: 33

  parameters:
    OrgPathParam:
      in: path
      name: org
      description: Organization name
      required: true
      schema:
        type: string
      example: yoigo

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

    DeviceIdPathParam:
      in: path
      name: device_id
      description: Device unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: fd2fcd90-2218-4ef1-917b-7ce5f35eee1c

    PromotionIdPathParam:
      in: path
      name: promotion_id
      description: Promotion unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    BundleIdPathParam:
      in: path
      name: subscriptions_bundle_id
      description: Bundle unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    CommercialTransactionIdPathParam:
      in: path
      name: commercial_transaction_id
      description: Commercial transaction unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    ContractIdPathParam:
      in: path
      name: contract_id
      description: Contract unique identifier
      required: true
      schema:
        type: string
        format: uuid
      example: a570614e-8a66-4d93-b329-7a2c9d6f0ce8

    CustomersAccountIdQueryParam:
      name: customers_account_id
      in: query
      description: Account id linked to the commercial transaction
      required: false
      schema:
        type: string
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    LegacyFraudRequestIdQueryParam:
      name: legacy_fraud_request_id
      in: query
      description: Legacy fraud request id linked to the commercial transaction
      required: false
      schema:
        type: integer
      example: 113996

    SubscriptionsBundleIdQueryParam:
      name: subscriptions_bundle_id
      in: query
      description: Bundle id linked to the commercial transaction
      required: false
      schema:
        type: string
        format: uuid
      example: ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39

    OffsetQueryParam:
      in: query
      name: offset
      description: Pagination offset
      required: false
      schema:
        type: integer
      example: 0

    LimitQueryParam:
      in: query
      name: limit
      description: Pagination limit
      required: false
      schema:
        type: integer
      example: 50

    DocumentsContractIdQueryParam:
      name: documents_contract_id
      in: query
      required: false
      schema:
        type: string
      description: Filter by documents contract identifier

  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

    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

    CommercialTransactionNotFound:
      description: Commercial transaction not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: XXX
            message: Commercial transaction not found
            reference: https://developers.masstack.com/en/guides/subscriptions/errorcatalogue
