openapi: 3.0.1
info:
  title: Block SIM
  description: This microservice allows B2B customers to block a SIM card. Securely blocks a subscriber’s SIM card in real time to prevent unauthorized network usage and protect against fraud or misuse.
  version: 1.1.1
servers:
  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com/subscription-management/b2b/v1
    description: "Sandbox"
  - url: https://api.vf-dmp.engineering.vodafone.com/subscription-management/b2b/v1
    description: "Production" 

paths:
  /sim/block:
    post:
      tags:
        - BlockSim
      description:  |-
                   Block a SIM card for the given MSISDN and account.
                    

      security:
        - oAuth2ClientCredentials: []
      operationId: blockSim
      summary: Block SIM card
      parameters:
        - in: header
          name: businessTransactionId
          description: Consumer of API must provide the businessTransactionId which is a unique identifier or reference number associated with a particular business transaction. Should preferably be in UUID format.
          required: true
          schema:
            type: string
            example: "2447fba1-bcaa-4bc1-91e8-54a4a09d9f6e"
        - in: header
          name: transactionId
          description: Consumer of API can provide the transactionId which is a unique identifier or reference number associated with a session. Could be used as correlationId for subsequent callback(s) if required. If not provided the system generates a unique id. Must be in UUID format.
          schema:
            type: string
            format: uuid
        - in: header
          name: customerAccount
          description: Customer Account
          required: true
          schema:
            type: string
            example: "267441"
      requestBody:
        required: true
        description: |
                          **Sample MSISDNs:** 31652728368, 31652728188, 31652727627, 31652728278
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockSimRequest'
            example:
              simNumber: "8931089318107296009"
              msisdn: "31611223344"
      responses:
        '200':
          description: Success - SIM card blocked successfully
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
                format: uuid
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s). Must be in UUID format.
              schema:
                type: string
                format: uuid
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockSimResponse'
              example:
                message: 'SIM card blocked successfully'

        '400':
          description: Bad request - Invalid Request.
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
                format: uuid
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s). Must be in UUID format.
              schema:
                type: string
                format: uuid
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingBusinessTransactionId:
                  summary: Missing required header
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'businessTransactionId is required.'
                invalidSimNumber:
                  summary: Invalid SIM number format
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'Invalid SIM number: must be 19-20 digits (ICCID format)'
                invalidMsisdn:
                  summary: Invalid MSISDN format
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'Invalid MSISDN: must be 10-15 digits'
                invalidCustomerAccount:
                  summary: Invalid or missing customerAccount
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'The header customerAccount is required.'
                simAlreadyBlocked:
                  summary: SIM is already in the blocked state
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'The SIM is already blocked.'
        '401':
          description: Unauthorized
          headers:
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '401'
                statusMessage: 'Unauthorized'
                errorMessage: 'Request not authenticated due to missing, invalid, or expired credentials.'
        '403':
          description: Forbidden
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
                format: uuid
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s). Must be in UUID format.
              schema:
                type: string
                format: uuid
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '403'
                statusMessage: 'Forbidden'
                errorMessage: 'Insufficient Privileges'
        '404':
          description: Not Found
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
                format: uuid
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s). Must be in UUID format.
              schema:
                type: string
                format: uuid
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '404'
                statusMessage: 'Not Found'
                errorMessage: 'Application Not Found'
        '500':
          description: Server encountered unexpected condition.
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
                format: uuid
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s). Must be in UUID format.
              schema:
                type: string
                format: uuid
            businessTransactionId:
              description: businessTransactionId echoed from the request. Should preferably be in UUID format.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '500'
                statusMessage: 'Internal Server Error'
                errorMessage: 'Error Message'

  /ping:
    get:
      tags:
        - Monitoring
      summary: Check the upstream system is up and running.
      description: |-
        This API is to check the upstream system is up and running.

      security:
        - oAuth2ClientCredentials: []

      operationId: getPing

      parameters:
        - in: header
          name: x-correlator
          description: Correlation id for the different services
          required: false
          schema:
            $ref: "#/components/schemas/XCorrelator"

      responses:
        '200':
          description: "**OK**"
          content:
            application/json:
              examples:
                success_response:
                  value: {
                            "suffix": "/ping",
                            "client": "35.191.13.203",
                            "startTime": "2023-06-05T19:47:16.794Z",
                            "endTime": "2023-06-05T19:47:16.888Z",
                            "responseTime": 94,
                            "message": "PONG"
                          }
        '400':
          description: Bad request - Invalid Request.
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s).
              schema:
                type: string
            businessTransactionId:
              description: businessTransactionId
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '400'
                statusMessage: 'Bad Request'
                errorMessage: 'businessTransactionId is required.'
        '401':
            description: Unauthorized
            headers:
              x-correlator:
                description: Correlation id for the different services
                schema:
                  type: string
                  example: b4333c46-49c0-4f62-80d7-f0ef930f1c46
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Error'
                examples:
                  GENERIC_401_UNAUTHENTICATED:
                    summary: Unauthenticated
                    description: Request cannot be authenticated
                    value:
                      status: '401'
                      code: 'UNAUTHENTICATED'
                      message: 'Request not authenticated due to missing, invalid, or expired credentials.'
        '403':
          description: Forbidden
          headers:
            requestId:
              description: Unique id always generated by system to identify the specific API call. It is in UUID format.
              schema:
                type: string
            transactionId:
              description: transactionId will be generated by system if not supplied in the initial request and could be used as correlationId for subsequent callback(s).
              schema:
                type: string
            businessTransactionId:
              description: businessTransactionId
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: '403'
                statusMessage: 'Forbidden'
                errorMessage: 'Insufficient Privileges'

 
 



components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: Oath2 grant type clientCredentials
      flows: 
        clientCredentials: 
          tokenUrl: /oauth2/v1/token
          scopes: 
           subscription-management:sim-block: "Scope sim-block"
  
  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    BlockSimRequest:
      type: object
      required:
        - simNumber
        - msisdn
      properties:
        simNumber:
          type: string
          description: SIM number (ICCID) to be blocked for the given MSISDN
          pattern: '^\d{19,20}$'
          example: "8931089318107296009"
        msisdn:
          type: string
          description: MSISDN associated with SIM number (international format without + or spaces)
          pattern: '^\d{10,15}$'
          example: "31611223344"

    BlockSimResponse:
      type: object
      properties:
        message:
          type: string
          description: Response message
          example: "SIM card blocked successfully"

    Error:
      type: object
      required:
        - statusCode
        - statusMessage
        - errorMessage
      properties:
        statusCode:
          type: string
          description: HTTP status code
        statusMessage:
          type: string
          description: HTTP status message
        errorMessage:
          type: string
          description: Error message