openapi: 3.0.1
info:
  title: Get PUK Code
  description: |
    This microservice enables B2B customers to retrieve the PUK code for a SIM associated with a given MSISDN.
    Each request supports a single MSISDN lookup.

    **Security note:** The PUK code is security-sensitive information. Consumers must handle the value securely and must not log, cache, or persist it.
  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" 
tags:
  - name: PUK Code
    description: SubscriptionManagement SIM PUK Code
paths:
  /sim/pukcode/{msisdn}:
    get:
      tags:
        - PUK Code
      description: Retrieve the PUK code for a SIM associated with a single MSISDN.
      security:
        - oAuth2ClientCredentials: []
      operationId: getPukCode
      summary: Get PUK Code
      parameters:
        - in: path
          name: msisdn
          description: |-
                        MSISDN of the subscriber. Must be a numeric string of 10 to 15 digits.
                        
                        **Sample MSISDNs:** 31652728368, 31652728188, 31652727627, 31652728278
          required: true
          schema:
            type: string
            pattern: '^[0-9]{10,15}$'
            minLength: 10
            maxLength: 15
            example: "31652728368"
        - 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: "019d6248-3eaa-7f99-bb30-2bb1efa5b52e"
        - 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: "261783"
      responses:
        '200':
          description: Success
          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/PukCodeResponse'

        '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.'
                invalidMsisdn:
                  summary: Invalid MSISDN format
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'Invalid MSISDN. Must be a numeric value of 10 to 15 digits.'
                invalidCustomerAccount:
                  summary: Invalid or missing customerAccount
                  value:
                    statusCode: '400'
                    statusMessage: 'Bad Request'
                    errorMessage: 'The header customerAccount is required.'
        '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-pukcode: "Scope for PukCode"
 


  schemas:
    XCorrelator:
      type: string
      pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
      example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
    AuthErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        error:
          type: integer
          description: HTTP response status code
        error_description:
          type: string
          description: Detailed error description 
    PukCodeResponse:
      type: object
      required:
        - pukcode
      properties:
        pukcode:
          type: string
          description: |
            PUK (Personal Unblocking Key) code for the SIM associated with the requested MSISDN.
            **Security note:** This value is sensitive. Consumers must handle it securely and must not log, cache, or persist it.
          example: "9886677"

    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 