openapi: 3.0.3
info:
  title: Wholesale Data API
  description: API documentation for Wholesale Data Partners.
  version: 1.0.0
paths:
  /partnerUserBusinessAcceptance:
    post:
      summary: Partner User Business Acceptance (Async)
      description: provides the ability to activate, modify and delete Resources.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  maxLength: 500
                  description: API Gateway access token
                  example: abc123xyz
                method:
                  type: string
                  maxLength: 64
                  description: API name
                  example: partnerUserBusinessAcceptance
                version:
                  type: string
                  maxLength: 10
                  description: API version
                  example: '1.0'
                content:
                  type: object
                  properties:
                    msgId:
                      type: string
                      maxLength: 30
                      description: Unique Message ID generated by the third-party system.
                      example: MSG123456789
                    orderItem:
                      type: object
                      properties:
                        base:
                          type: object
                          properties:
                            serviceActionId:
                              type: string
                              maxLength: 1
                              description: Service Action type
                              example: A
                            orderItemId:
                              type: string
                              maxLength: 16
                              pattern: ^\d+$
                              description: >
                                External Order ID. Numbers only, alphabet not
                                supported. System will use orderItemId pair with
                                trigerSource to be the unique key for order
                                query. Zsmart SPN cannot do the unique
                                validation on orderItemId since the validation
                                will impact the performance. Need each partner
                                to make sure the unique of orderItemId generated
                                by itself.
                              example: '12345678'
                            trigerSource:
                              type: string
                              maxLength: 20
                              description: Trigger source
                              example: SYSTEM_X
                        orderDetail:
                          type: object
                          properties:
                            resource:
                              type: object
                              properties:
                                dn:
                                  type: object
                                  properties:
                                    current:
                                      type: object
                                      properties:
                                        dn:
                                          type: string
                                          maxLength: 12
                                          description: >-
                                            Malaysia mobile number without country
                                            code
                                          example: '123456789012'
                                        org:
                                          type: string
                                          maxLength: 30
                                          description: MSISDN organization
                                          example: OrgName
                                        prefix:
                                          type: string
                                          maxLength: 2
                                          description: Country code fixed- 60
                                          example: '60'
                                simCard:
                                  type: object
                                  properties:
                                    current:
                                      type: object
                                      properties:
                                        imsi:
                                          type: string
                                          maxLength: 15
                                          description: IMSI
                                          example: '123456789012345'
                            products:
                              type: object
                              properties:
                                accessproducts:
                                  type: object
                                  properties:
                                    product:
                                      type: object
                                      properties:
                                        serviceType:
                                          type: string
                                          maxLength: 1
                                          description: User Service type. Fixed value 1
                                          example: '1'
                                functionproducts:
                                  type: object
                                  properties:
                                    product:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          operationType:
                                            type: string
                                            maxLength: 1
                                            description: Operation type (A, M, D)
                                            example: A
                                          serviceType:
                                            type: string
                                            maxLength: 30
                                            description: Fixed to 174
                                            example: '174'
                                          benefitList:
                                            type: object
                                            properties:
                                              benefit:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    acctResCode:
                                                      type: string
                                                      maxLength: 60
                                                      description: >-
                                                        UM will assign a dedicated PAKID for
                                                        each wholesale partner
                                                      example: PAK12345
                                                    amount:
                                                      type: integer
                                                      description: Quota amount
                                                      example: 1000
                                                    absEffDate:
                                                      type: string
                                                      format: date-time
                                                      description: Quota effective date
                                                      example: '2025-02-10T00:00:00Z'
                                                    absExpDate:
                                                      type: string
                                                      format: date-time
                                                      description: Quota expiry date
                                                      example: '2025-12-31T23:59:59Z'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  res_code:
                    type: string
                    maxLength: 10
                    description: Response code, 00000 for success
                    example: '00000'
                  res_message:
                    type: string
                    maxLength: 255
                    description: Response description
                    example: Success
                  result:
                    type: object
                    properties:
                      resultCode:
                        type: string
                        maxLength: 60
                        description: Service result code
                        example: SUCCESS
                      resultMsg:
                        type: string
                        maxLength: 255
                        description: Service result message
                        example: Operation completed successfully.
  /pccDataInquiry:
    post:
      summary: PCC Data Inquiry (Sync)
      description: >-
        This API allows wholesale data partners to query information about
        available data packages for their end-users through the PCC system.
      operationId: pccDataInquiry
      x-consumption-style: Synchronous
      x-transaction-processing-style: Synchronous
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: API Gateway access token
                  maxLength: 500
                  example: abcdef1234567890
                method:
                  type: string
                  description: API name
                  maxLength: 64
                  example: getSubscriberInfo
                version:
                  type: string
                  description: API version
                  maxLength: 10
                  example: v1.0
                content:
                  type: object
                  description: Refer to content for detail.
                  properties:
                    msgId:
                      type: string
                      maxLength: 30
                      description: Refer to orderItem for detail.
                      example: ORD567890
                    trigerSource:
                      type: string
                      maxLength: 20
                      description: >
                        Value to be provided upon request. New 'PTR_WD_CU_T2A'
                        value for Wholesale Data Partner (China Unicom). Note:
                        trigerSource will be configurable and unique for each
                        wholesale data partners and MVNO partners.
                      example: PTR_WD_CU_T2A
                    msisdn:
                      type: string
                      maxLength: 12
                      description: Malaysia mobile number with country code
                      example: '60123456789'
                    realTIMEFLAG:
                      type: integer
                      maximum: 1
                      description: >-
                        Fixed value '1'. to query data package information via
                        PCC.
                      example: 1
                    org:
                      type: string
                      maxLength: 30
                      description: >
                        Partner's organization Code.Unique. UM will define an
                        organization for each wholesale data partner, and assign
                        IMSI and MSISDN to partner's organization. System will
                        check if inputted MSISDN and IMSI have been assigned to
                        partner's organization. If not, system will reject the
                        request.
                      example: ORG_WHOLESALE_X
                  required:
                    - msgId
                    - trigerSource
                    - msisdn
                    - realTIMEFLAG
                    - org
              required:
                - access_token
                - method
                - version
                - content
          responses:
            '200':
              description: Successful response with data package details.
  /provStatusInquiry:
    post:
      summary: Provisioning Status Inquiry (Sync)
      description: >-
        This API allows wholesale data partners to query the provisioning status
        for the corresponding order item.
      operationId: provStatusInquiry
      x-consumption-style: Synchronous
      x-transaction-processing-style: Synchronous
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - access_token
                - method
                - version
                - content
              properties:
                access_token:
                  type: string
                  maxLength: 500
                  description: API Gateway access token
                  example: >-
                    abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
                method:
                  type: string
                  maxLength: 64
                  description: API name
                  example: getOrderStatus
                version:
                  type: string
                  maxLength: 10
                  description: API version
                  example: v1.0
                content:
                  type: object
                  description: Refer to content for detail.
                  required:
                    - msgId
                    - trigerSource
                    - orderItemId
                    - org
                  properties:
                    msgId:
                      type: string
                      maxLength: 30
                      description: >
                        Unique Message ID generated by 3rd party system. Format:
                        [AAAYYYYMMDDHH24MISSCCCC] AAA: Channel Identifier
                        (3-digit), value to be provided by Zsmart. Datetime:
                        YYYYMMDDHH24MISS. CCCC: Sequence number (4-digit), value
                        range [0000-9999].
                      example: WEB202504221200000001
                    trigerSource:
                      type: string
                      maxLength: 20
                      description: >
                        Value to be provided upon request. New 'PTR_WD_CU_T2A'
                        value for Wholesale Data Partner (China Unicom). Note:
                        trigerSource will be configurable and unique for each
                        wholesale data partner and MVNO partner.
                      example: PTR_WD_CU_T2A
                    orderItemId:
                      type: string
                      maxLength: 16
                      pattern: ^[0-9]+$
                      description: >
                        External Order ID. Numbers only, alphabet not supported.
                        System will use orderItemId paired with trigerSource to
                        form the unique key for order query. Zsmart SPN cannot
                        perform uniqueness validation on orderItemId due to
                        performance impact. Each partner must ensure orderItemId
                        is unique on their end.
                      example: '202404220001'
                    org:
                      type: string
                      maxLength: 30
                      pattern: ^[A-Z0-9_]+$
                      description: >
                        Partner's organization Code. Must be unique. UM will
                        define an organization for each wholesale data partner,
                        and assign IMSI and MSISDN to partner's organization.
                        System will check if inputted MSISDN and IMSI have been
                        assigned to partner's organization. If not, system will
                        reject the request.
                      example: ORG_UM_PARTNER
                    msisdn:
                      type: string
                      maxLength: 12
                      description: Malaysia mobile number with country code
                      example: '60123456789'
      responses:
        '200':
          description: Successful response with provisioning status.
          content:
            application/json:
              schema:
                type: object
                required:
                  - res_code
                  - res_message
                  - result
                properties:
                  res_code:
                    type: string
                    maxLength: 10
                    description: Response code, "00000" for success.
                    example: '00000'
                  res_message:
                    type: string
                    maxLength: 255
                    description: Response description.
                    example: Provisioning successful
                  result:
                    type: object
                    description: Response result.
                    required:
                      - resultCode
                      - resultDescr
                    properties:
                      resultCode:
                        type: string
                        maxLength: 60
                        description: Service result code
                        example: '20001'
                      resultDescr:
                        type: string
                        maxLength: 255
                        description: Service result message
                        example: Package activated successfully
                      provStatus:
                        type: integer
                        description: >
                          Provisioning status. - 1: Successful - 2: Processing -
                          3: Failed
                        example: 1
        '400':
          description: Bad Request - The request is invalid or missing required parameters.
          content:
            application/json:
              schema:
                type: object
                required:
                  - res_code
                  - res_message
                  - error_details
                properties:
                  res_code:
                    type: string
                    maxLength: 10
                    description: Response code, '400' for bad request.
                    example: '400'
                  res_message:
                    type: string
                    maxLength: 255
                    description: Description of the error.
                    example: Invalid request parameters or missing required fields.
                  error_details:
                    type: object
                    description: Details of the error.
                    properties:
                      error_code:
                        type: string
                        maxLength: 50
                        description: Specific error code.
                        example: INVALID_ORDER_ITEM_ID
                      error_message:
                        type: string
                        maxLength: 255
                        description: Detailed error message.
                        example: >-
                          The orderItemId provided is not valid. Please ensure
                          it only contains numeric characters.
                      invalid_fields:
                        type: array
                        items:
                          type: string
                        description: List of fields that caused the error.
                        example:
                          - orderItemId
                          - trigerSource
  /synCallServiceActiveResult:
    post:
      summary: Sync Call Service Active Result (Async)
      description: >
        Zsmart to notify wholesale data partner the business provisioning
        result.

        MSISDN and SIM status maintenance: - After New Connection order
        archived, SPN will call SIC service to activate the resource for sync-up
        purpose: 
          SIM = C (In Use), MSISDN = C (In Use).
        - After Termination order archived, SPN will call SIC service to
        terminate the resource for sync-up purpose: 
          SIM = D (Disable), MSISDN = T (Terminated).
        - MSISDNs will be automatically recycled to the public pool as part of
        BAU. 
          UM must manually transfer these recycled MSISDNs to the partner organization accordingly.
        - No SIM recycle is handled by UM.
      operationId: synCallServiceActiveResult
      x-consumption-style: Asynchronous
      x-transaction-processing-style: Asynchronous
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - notifyTime
                - resultCode
                - resultMsg
                - orderItemId
              properties:
                notifyTime:
                  type: string
                  maxLength: 40
                  description: >
                    Asynchronous notification trigger time. Format: yyyy-MM-dd
                    HH:mm:ss
                  example: '2025-04-22 14:30:00'
                resultCode:
                  type: string
                  maxLength: 10
                  description: >
                    Provisioning return code. Provisioning status. 0:
                    Provisioning Success
                  example: '0'
                resultMsg:
                  type: string
                  maxLength: 10000
                  description: Provisioning Response message from NE
                  example: Provisioning completed successfully.
                orderItemId:
                  type: string
                  maxLength: 16
                  pattern: ^\d{1,16}$
                  description: >
                    orderItemId in wholesale data partner system. Numbers only,
                    alphabet not supported. System will use orderItemId pair
                    with trigerSource to be the unique key for order query.
                    Zsmart SPN cannot do the unique validation on orderItemId
                    since the validation will impact the performance. Need each
                    partner to make sure the unique of orderItemId generated by
                    itself.
                  example: '1234567890123456'
      responses:
        '200':
          description: Successful asynchronous notification
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the operation
                    example: success
                  timestamp:
                    type: string
                    description: Response timestamp
                    example: '2025-04-22T14:30:01Z'
        '400':
          description: Bad request. Input validation failed or missing required fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    description: Application-specific error code
                    example: '40001'
                  errorMessage:
                    type: string
                    description: Explanation of the error
                    example: 'Missing required field: resultCode'
        '500':
          description: Internal server error. Unexpected condition encountered by server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    description: Server error code
                    example: '50001'
                  errorMessage:
                    type: string
                    description: Error message returned by server
                    example: Unexpected server error while processing request
servers:
  - url: https://sandbox.zsmart.com
    description: Sandbox Server
  - url: https://api.zsmart.com
    description: Production Server
components: {}
