openapi: 3.0.0
info:
  title: Barrings API
  description: Barrings REST API
  version: '2.1'
  contact:
    name: administrator
    email: mas-barrings@masmovil.com
servers:
  - url: https://barrings.masstack.com/v2/
    description: production
  - url: https://barrings.sta.masstack.com/v2/
    description: staging
tags:
  - name: Masks
    description: Barrings operations masks
  - name: Services
    description: Barrings operations services
paths:
  /orgs/{orgId}/subscriptions/{subscriptionId}/barrings-masks/operations:
    post:
      tags: [ Masks ]
      summary: Post apply or remove masks
      description: Request a barring masks set operation over a subscription.
      operationId: operateMasks
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      requestBody:
        description: Contains the operation and the masks code set, that contains
          the barrings masks to operate over a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MasksOperationRequest'
        required: true
      responses:
        "202":
          description: Successfully accepted the operation request, returned the evaluation
            of mask, network services new status application pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MasksOperationResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: SubscriptionId not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "409":
          description: Conflict to apply or remove barrings with subscription with
            invalid status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgs/{orgId}/subscriptions/{subscriptionId}/services/{serviceId}:
    get:
      tags: [ Services ]
      summary: Get one service
      description: Request a service
      operationId: getService
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
        - $ref: "#/components/parameters/serviceIdParam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatusDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [ Services ]
      summary: Patch update one service
      description: Request a service barring over a subscription.
      operationId: operateService
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
        - $ref: "#/components/parameters/serviceIdParam"
      requestBody:
        description: Contains services set and the reason to operate over a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceOperationRequest'
        required: true
      responses:
        "202":
          description: Successfully accepted the operation request, returned the externalId and subscriptionId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOperationResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgs/{orgId}/subscriptions/{subscriptionId}/services:
    get:
      tags: [ Services ]
      summary: Get all subscription service
      description: Request all subscription service
      operationId: getSubscriptionServices
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatusListDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [ Services ]
      summary: Patch update services
      description: Request services barring over a subscription.
      operationId: operateServices
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      requestBody:
        description: Contains services set and the reason to operate over a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiServicesOperationRequest'
        required: true
      responses:
        "202":
          description: Successfully accepted the operation request, returned the externalId and subscriptionId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceOperationResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgs/{orgId}/masks:
    get:
      tags: [ Masks ]
      summary: Get barring masks catalogue
      description: Gets the barring masks catalogue
      operationId: getMaskCatalogue
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/operationTypeCodeParam"
        - $ref: "#/components/parameters/codeParam"
        - $ref: "#/components/parameters/subscriptionTypeParam"
      responses:
        "200":
          description: Successfully returned the barring mask catalogue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaskCatalogueListDto'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgs/{orgId}/masks/{maskId}:
    get:
      operationId: getMaskById
      summary: Get mask by id
      description: Return a mask if exists
      tags: [ Masks ]
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/maskIdParam"
      responses:
        200:
          description: The mask
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaskCatalogueDto"
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /orgs/{orgId}/subscriptions/{subscriptionId}/masks:
    get:
      tags: [ Masks ]
      operationId: getSubscriptionMasks
      summary: Get masks applied to a subscription
      description: Get masks applied to a subscription
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      responses:
        "200":
          description: Successfully returned the masks associated to a subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionMasksResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [ Masks ]
      summary: Patch for apply or remove masks
      description: Request a barring masks set operation over a subscription.
      operationId: operateSubscriptionMasks
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      requestBody:
        description: Contains the operation and the masks code set, that contains
          the barrings masks to operate over a subscription
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MasksOperationRequest'
        required: true
      responses:
        "202":
          description: Successfully accepted the operation request, returned the evaluation
            of mask, network services new status application pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MasksOperationResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "403":
          description: Forbidden resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: SubscriptionId not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "409":
          description: Conflict to apply or remove barrings with subscription with
            invalid status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgs/{orgId}/subscriptions/{subscriptionId}/masks/history:
    get:
      tags: [ Masks ]
      parameters:
        - $ref: "#/components/parameters/orgIdParam"
        - $ref: "#/components/parameters/subscriptionIdParam"
      operationId: getSubscriptionMasksHistory
      summary: Get masks applied history to a subscription
      description: Return a history list of of barred masks
      responses:
        200:
          description: History list of masks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionMasksHistoryResponse"
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        500:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  parameters:
    orgIdParam:
      name: orgId
      in: path
      required: true
      description: A masmovil tenant
      schema:
        type: string
      example: masmovil
    subscriptionIdParam:
      name: subscriptionId
      in: path
      required: true
      description: Subscription identifier
      schema:
        type: integer
        format: int64
      example: 22222
    serviceIdParam:
      name: serviceId
      in: path
      required: true
      description: Service identifier
      schema:
        type: integer
        format: int64
      example: 11111
    maskIdParam:
      name: maskId
      schema:
        type: integer
        format: int64
      in: path
      required: true
      description: Mask Id
      example: 1
    operationTypeCodeParam:
      name: operationTypeCode
      in: query
      required: false
      description: The operation type code of the mask
      schema:
        type: string
      example: DEBT
    codeParam:
      name: code
      in: query
      required: false
      description: The name code of the mask
      schema:
        type: string
      example: DEBT_MOBILE_HOTLP
    subscriptionTypeParam:
      name: subscriptionType
      in: query
      required: false
      description: The subscription type code of the mask
      schema:
        type: string
      example: MOBILE
  schemas:
    MasksOperationRequest:
      type: object
      required:
        - action
        - barringsMasksCodes
      properties:
        action:
          type: string
          description: Action of the operation, the operation that applies the set
            of masks provided
          enum:
            - APPLY
            - REMOVE
          example: APPLY
        barringsMasksCodes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
        reason:
          type: string
          description: Reason of barring operation
          enum:
            - DEBT
            - RISK
            - MIGRATION
            - ATC
            - CUST
          example: MIGRATION
          minItems: 1
    MasksOperationResponse:
      type: object
      required:
        - externalId
      properties:
        externalId:
          type: string
          description: External identifier of the business process operation triggered
            and associated to the request
          example: 1234451112-a3a2
    ServiceOperationRequest:
      type: object
      required:
        - reason
        - active
      properties:
        reason:
          type: string
          description: Reason
          example: CUST
          enum:
            - CUST
            - PROD
        active:
          type: boolean
          example: true
      description: Request to update one service
    MultiServicesOperationRequest:
      type: object
      required:
        - reason
        - services
      properties:
        reason:
          type: string
          description: Reason
          example: CUST
          enum:
            - CUST
            - PROD
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceDto'
          minItems: 1
          uniqueItems: true
      description: Request to update many services
    ServiceOperationResponse:
      type: object
      required:
        - externalId
      properties:
        externalId:
          type: string
          description: External identifier of the business process operation triggered
            and associated to the request
          example: 1234451112-a3a2
      description: Barrings services operation result
    ServiceDto:
      type: object
      required:
        - serviceId
        - active
      properties:
        serviceId:
          type: integer
          description: Service Id
          format: int64
          example: 10
        active:
          type: boolean
          example: true
          description: Desired service status
      description: Service with status
    ServiceStatusDto:
      type: object
      required:
        - serviceId
        - serviceName
        - active
        - statusReason
        - order
      properties:
        serviceId:
          type: integer
          description: Service Id
          format: int64
          example: 1111
        serviceName:
          type: string
          description: Service Name
          example: "OUTGOING_VOICE"
        active:
          type: boolean
          example: true
          description: Service status
        statusReason:
          type: array
          items:
            type: string
        order:
          type: object
          $ref: '#/components/schemas/OrderDto'
    OrderDto:
      type: object
      required:
        - running
        - orders
      properties:
        running:
          type: boolean
          description: Order running status
          example: true
        orders:
          type: array
          items:
            type: string
          description: External id list
    ServiceStatusListDto:
      type: array
      items:
        $ref: '#/components/schemas/ServiceStatusDto'
    SubscriptionMasksResponse:
      type: object
      required:
        - subscriptionId
        - masks
      properties:
        subscriptionId:
          type: integer
          description: Subscription Id
          format: int64
          example: 1234451113
        masks:
          uniqueItems: true
          type: array
          description: Mask code list
          items:
            type: string
            description: Mask code
            example: DEBT_MOBILE_LP
    SubscriptionMasksHistoryResponse:
      type: array
      items:
        $ref: "#/components/schemas/MaskHistoryResponse"
    MaskHistoryResponse:
      type: object
      required:
        - id
        - mask
        - subscription_id
        - operation
        - user
        - date
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: 'history id'
        mask:
          $ref: "#/components/schemas/ReducedMaskDto"
        operation:
          type: string
          enum: [ "APPLY", "REMOVE" ]
        subscription_id:
          type: integer
          format: int64
          example: 14
          description: 'subscription id'
        user:
          type: string
          example: "MB_username"
        date:
          type: string
          format: date-time
    ReducedMaskDto:
      type: object
      required:
        - id
        - code
        - name
        - description
      properties:
        id:
          type: integer
          format: int64
          example: 14
          description: 'The mask id'
        code:
          type: string
          example: DEBT_MOBILE_RESTRICTED
          description: Then mask code
        name:
          type: string
          example: Restringido
        description:
          type: string
          example: DEBT_MOBILE_RESTRICTED description
          description: Then mask description
    MaskCatalogueListDto:
      type: array
      items:
        $ref: '#/components/schemas/MaskCatalogueDto'
      description: List of barring masks
    MaskCatalogueDto:
      required:
        - id
        - code
      type: object
      properties:
        id:
          type: integer
          description: Mask Id
          format: int64
          example: 10
        code:
          type: string
          description: Barrings mask code, external identifier
          example: DEBT_MOBILE_LP
        description:
          type: string
          description: Barrings mask description
          example: Line services suspension due to debt
        name:
          type: string
          description: Barrings mask business name
          example: Redireccion Internet
        operationTypeCode:
          type: string
          description: Operation type group code
          example: DEBT
        subscriptionTypeCode:
          type: string
          description: Subscription type code
          example: MOBILE
        services:
          $ref: '#/components/schemas/ServiceCatalogueListDto'
          description: List of mask services
      description: Barring mask
    ServiceCatalogueListDto:
      type: array
      items:
        $ref: '#/components/schemas/ServiceCatalogueDto'
    ServiceCatalogueDto:
      required:
        - id
        - code
      type: object
      properties:
        id:
          type: integer
          description: Service Id
          format: int64
          example: 10
        code:
          type: string
          description: Service code
          example: OUTGOING_VOICE
        description:
          type: string
          description: Service description
          example: Outgoing Voice
    ErrorResponse:
      type: object
      required:
        - code
        - tracingId
      properties:
        tracingId:
          type: string
          description: Trace id of the related request to track the exception
          example: 0e3f7e20-6a4b-4344-bad0-fe8576e72adc
        code:
          type: string
          description: Error code string for fast identification
          example: INVALID_BARRING_MASK
        message:
          type: string
          description: Message description or detail of error
          example: 'OA3_400_01: Validation error in some parameters. See swagger documentation'
      description: Rest service error response
  x-releaseInfo:
    description: >
      
      
      ### Release Notes
      
      * **0.2.6** : Create GET /orgs/{orgId}/subscriptions/{subscriptionId}/masks/history
        - Get subscription masks history
      * **0.1.1** : Changes GET /orgs/{orgId}/subscriptions/{subscriptionId}/services/
        - Add current orders data to services endpoints
      * **0.1.0** : Added new endpoint 
        - New Patch in url /orgs/{orgId}/subscriptions/{subscriptionId}/masks
      * **0.0.17** : Changes POST /orgs/{orgId}/subscriptions/{subscriptionId}/barrings-masks/operations
        - added customers masks