openapi: 3.0.1
info:
  title: Msisdn inventory.
  description: |
    ## Definition
    Orgs is the responsible for managing the data about MasOrange's organizations (tenants). In this context, the term "organization" means "any of the brands that MasOrange uses to provide services" called tenant in mas-stack.
    
    ## Current state
    There could be a delay of 24 hours between the registration of a msisdn in certain brand and its appearance in the Discovery Tool, unless some network traffic its done.
  version: 2.0.2
servers:
- url: https://orgs.masstack.com/v2
  description: production

- url: https://orgs.sta.masstack.com/v2
  description: staging

tags:
  - name: admin
    description: API for managing msisdn inventory CRUD operations
  - name: inventory
    description: public API

security:
  - bearerAuth: []       
paths:
  /imsis/{imsi}:
    get:
      tags:
      - inventory
      summary: Retrieve info for this imsi
      description: Get info for this imsi
      operationId: retrieve-msisdn-by-imsi
      parameters:
      - name: imsi
        in: path
        description: a imsi of msisdn of Grupo Mamovil
        example: 214040119172971
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Info of msisdn
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsisdnInventory'
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
  /operatorToken/{operatorToken}:
    get:
      tags:
      - inventory
      summary: Retrieve MSISDN/IMSI info by operator token
      description: Retrieves MSISDN and IMSI information from the Entitlement Server (ES)
      operationId: retrieve-msisdn-by-operator-token
      parameters:
      - name: operatorToken
        in: path
        description: Operator token from the Entitlement Server
        example: abc123xyz456
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Info of msisdn retrieved from operator token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsisdnInventory'
        "400":
          description: Invalid operator token format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Operator token not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "502":
          description: Bad gateway - Entitlement Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
  /operatorToken:
    get:
      tags:
      - inventory
      summary: Retrieve MSISDN/IMSI info by operator token header
      description: Retrieves MSISDN and IMSI information from the Entitlement Server (ES) using an operator token provided in the X-Operator-Token header. Use this endpoint when the token is a large JWT that cannot fit in a URL path.
      operationId: retrieve-msisdn-by-operator-token-header
      parameters:
      - name: X-Operator-Token
        in: header
        description: Operator token from the Entitlement Server
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Info of msisdn retrieved from operator token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsisdnInventory'
        "400":
          description: Missing or invalid X-Operator-Token header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Operator token not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "502":
          description: Bad gateway - Entitlement Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
  /msisdns/{msisdn}:
    get:
      tags:
      - inventory
      summary: Retrieve info for this msisdn
      description: Get info for this msisdn
      operationId: retrieve-msisdn
      parameters:
      - name: imsi
        in: query
        description: a imsi of msisdn of Grupo Mamovil
        example: 214040119172971
        schema:
          type: string
      - name: msisdn
        in: path
        description: a msisdn of Grupo Mamovil
        example: 666777888
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: embed object, for example 'tenant'
        example: (tenant, imsis)
        schema:
          type: string
      - name: feature-flag.preserve-the-prefix
        in: header
        description: >
          When set to "yes", the msisdn field in the response will include
          the country code prefix (e.g. "+34666777888" instead of "666777888").
          If omitted or set to any other value, the prefix is stripped from the response.
        required: false
        schema:
          type: string
          enum: ["yes"]
        example: "yes"
      responses:
        "200":
          description: Info of msisdn
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MsisdnInventory'
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
  /orgs/{org}/msisdns/{msisdn}:
    put:
      tags:
      - admin
      summary: Update of msisdn info.
      description: Msisdn should exist.
      operationId: update-msisdn
      parameters:
      - name: msisdn
        in: path
        description: a msisdn of Grupo Mamovil
        example: 666777888
        required: true
        schema:
          type: string
      - name: org
        in: path
        description: tenant name
        example: masmovil
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundInventory'
        required: false
      responses:
        "204":
          description: ' OK'
          content: {}
        "400":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "401":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "409":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
    patch:
      tags:
      - admin
      summary: Partial update of msisdn info.
      description: Msisdn should exist.
      operationId: patch-update-msisdn
      parameters:
      - name: msisdn
        in: path
        description: a msisdn of Grupo Mamovil
        example: 666777888
        required: true
        schema:
          type: string
      - name: org
        in: path
        description: tenant name
        example: masmovil
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundPartialInventory'
        required: false
      responses:
        "204":
          description: ' OK'
          content: {}
        "400":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "401":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "409":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
    post:
      tags:
      - admin
      summary: Add this msisdn to the inventory.
      operationId: create-msisdn
      parameters:
      - name: msisdn
        in: path
        description: a msisdn of Grupo Mamovil
        example: 666777888
        required: true
        schema:
          type: string
      - name: org
        in: path
        description: tenant name
        example: masmovil
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboundInventory'
        required: false
      responses:
        "201":
          description: ' OK'
          content: {}
        "400":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "401":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "409":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
    delete:
      tags:
      - admin
      summary: Delete msisdn
      description: Delete msisdn
      operationId: delete-msisdn
      parameters:
      - name: msisdn
        in: path
        description: a msisdn of Grupo Mamovil
        example: 666777888
        required: true
        schema:
          type: string
      - name: org
        in: path
        description: tenant name
        example: masmovil
        required: true
        schema:
          type: string
      responses:
        "204":
          description: ' OK'
          content: {}
        "403":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "404":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
        "500":
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ErrorDto:
      type: object
      properties:
        componentMsg:
          example: "Error:Field validation for 'Imsi' failed on the 'required' tag"
          type: string
        id:
          example: "MM0000001"
          type: string
        msg:
          example: "Invalid inbound entity"
          type: string
        sentryCode:
          type: string
        status:
          example: $statusCode
          type: integer
          format: int64
      description: ErrorDto defines an extended error
    Imsi:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        imsi:
          type: string
          example: "2140420422222227"
        segment:
          type: string
          enum: ["B2B","B2C"]
          x-enum-varnames:
            - B2B
            - B2C
          example: B2B
    InboundInventory:
      required:
      - imsi
      type: object
      properties:
        imsi:
          type: string
          example: "2140420422222227"
    InboundPartialInventory:
      type: object
      properties:
        belongs_to:
          type: string
          enum: ["unknown","mas-stack","heos","ektnet","salesforce","qvantel","outside","qvantel-prepaid","tcnet","r","xena","osp-stack","simyo-stack"]
          example: mas-stack
        status:
          type: string
          enum: ["OK","Deleted","Migrating","Migrated"]
    MsisdnInventory:
      type: object
      properties:
        belongs_to:
          type: string
          enum: ["unknown","mas-stack","heos","ektnet","salesforce","qvantel","outside","qvantel-prepaid","tcnet","r","xena","osp-stack","simyo-stack"]
          example: mas-stack
        checked_at:
          type: string
          format: date-time
        imsi:
          $ref: '#/components/schemas/Imsi'
        imsis:
          type: array
          items:
            $ref: '#/components/schemas/Imsi'
        msisdn:
          type: string
          example: "666777888"
        org:
          type: string
          example: masmovil
        status:
          type: string
          enum: ["OK","Deleted","Migrating","Migrated"]
        tenant:
          $ref: '#/components/schemas/Tenant'
        internal_portability:
          $ref: '#/components/schemas/InternalPortability'
    InternalPortability:
      type: object
      properties:
        belongs_to:
          type: string
          enum: ["unknown","mas-stack","heos","ektnet","salesforce","qvantel","outside","qvantel-prepaid","tcnet","r","xena","osp-stack","simyo-stack"]
          example: mas-stack
        org:
          type: string
          example: yoigo
    Tenant:
      type: object
      properties:
        bit:
          type: integer
          format: uint64
          example: 2
        iam:
          type: string
          example: authz.masmovil
        name:
          type: string
          example: masmovil
        org:
          type: string
          example: masmovil
        tenant_id:
          type: integer
          format: uint64
          example: 2
        tier:
          type: integer
          format: uint64
          example: 1
          enum: [1,2,3,4,5]
  responses:
    customError:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorDto'
    inventoryResponse:
      description: Info of msisdn
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MsisdnInventory'
