Telenor Sverige Order Item Cancellation Request API

openapi: 3.2.0
info:
  title: Product Ordering Management Order Item Cancellation Request…
  description: 'The Product Ordering API provides a standardized mechanism for placing a product order with all of the

    necessary order parameters. The API consists of a simple set of operations that interact with CRM/Order

    Negotiation systems in a consistent manner. A product order is created based on a product offer that is

    defined in a catalog. The product offer identifies the product or set of products that are available to a

    customer, and includes characteristics such as pricing, product options and market.


    This API is intended for software developers and system integrators implementing client applications for

    handling product orders. It is assumed that the reader is familiar with software API

    concepts such as REST, JSON and the OpenAPI specification. For more information about OpenAPI see

    OpenAPI Specification.


    ### Response Codes


    This API follows standard response codes defined in the

    HTTP RFC by W3C

    Note that not all 4xx HTTP Status Codes are explicit documented in each API-operation such as

    **401 (UNAUTHORIZED)** and **403 (FORBIDDEN)**. These are considered generic ones and clients should be aware

    their presence at all operations.


    ### Notifications


    When an Order is sent to the backend systems, its lifecycle state changes and an event is sent to the

    Event Notification API. The notification `detailedMessage` attribute will have the following content:


    ```


    {

    "operation": "ORDER_IN_PROGRESS",

    "message": "The order is in progress.",

    "type": "order",

    "id": "bf13697e-ab73-4a75-bc1b-903147594d11",

    "orderState": "RECEIVED",

    "siteIds": [

    {

    "externalId": "clientDefinedSiteId",

    "siteId": "45234",

    "products": [

    {

    "id": "SID4123123",

    "name": "Nordic Connect Managed Complete 200M",

    "promisedDate": "2021-09-02T00:00:00.000+0200",

    "state": "TO_BE_INSTALLED",

    "orderItemId": "clientDefinedOrderItemId"

    }

    ]

    }

    ]

    }'
  termsOfService: https://www.telenor.se/globalassets/mediabibliotek/telenor-foretag/pdfer/priser-och-villkor/general-terms-and-conditions-october-2012.pdf
  contact:
    name: Telenor Support
    url: https://www.telenor.se/foretag/kundservice/
  version: 2.22.0
servers:
- url: https://apis-test.telenor.se/corporate/fixed-network/order-management
  description: Test environment
tags:
- name: Order Item Cancellation Request
  description: Endpoints for requesting to cancel an order item.
paths:
  /corporate/fixed-network/order-management/v1/product-order/cancellation-request:
    get:
      tags:
      - Order Item Cancellation Request
      summary: Lists all cancellation requests
      operationId: listCancellations
      parameters:
      - name: pageSize
        in: query
        description: The number of items each page should contain.
        required: false
        schema:
          type: integer
          format: int32
        example: 10
      - name: pageNumber
        in: query
        description: The number of the page in the list of results.
        required: false
        schema:
          type: integer
          format: int32
        example: 1
      - name: sort
        in: query
        description: Sort order
        required: false
        schema:
          type: string
          enum:
          - CREATED_DATE_DESC
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Cancellations retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCancellationsResponse'
    post:
      tags:
      - Order Item Cancellation Request
      summary: Creates a cancellation request for an order item
      description: The cancellation request will be reviewed by Telenor manually, and updated with what it would cost the customer to cancel the order item. After the cancellation request has been updated with the cancellation cost, the order item can be cancelled using the POST /confirm endpoint.
      operationId: createOrderItemCancellationRequest
      parameters:
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      - name: X-Transaction-Id
        in: header
        description: A unique identifier for this transaction.
        example: acd10307-aaf1-4b7f-85bb-09deb638597d
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancellationRequest'
        required: true
      responses:
        '201':
          description: Cancellation request successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationResponse'
  /corporate/fixed-network/order-management/v1/product-order/cancellation-request/{id}/confirm:
    post:
      tags:
      - Order Item Cancellation Request
      summary: Confirms the cancellation of an order item
      description: Confirms the cancellation of the order item and updates the state of the order item to be cancelled. The cancellation request must be in state REVIEWED_BY_TELENOR and its expiration date must not have been reached.
      operationId: confirmCancellation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Transaction-Id
        in: header
        description: A unique identifier for this transaction.
        example: acd10307-aaf1-4b7f-85bb-09deb638597d
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Cancellation successfully confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationResponse'
        '400':
          description: Cancellation is not in a confirmable state.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Cancellation not found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
  /corporate/fixed-network/order-management/v1/product-order/cancellation-request/{id}:
    get:
      tags:
      - Order Item Cancellation Request
      summary: Retrieves an existing cancellation request
      operationId: getCancellation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      - name: X-Transaction-Id
        in: header
        description: A unique identifier for this transaction.
        example: acd10307-aaf1-4b7f-85bb-09deb638597d
      responses:
        '200':
          description: Cancellation retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancellationResponse'
        '404':
          description: Cancellation not found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CancellationContactPerson:
      type: object
      properties:
        firstName:
          type: string
          description: The first name of the person to be contacted.
          example: Jane
        lastName:
          type: string
          description: The last name of the person to be contacted.
          example: Doe
        email:
          type: string
          format: email
          description: The e-mail address of the contact person.
          example: jane.doe@telenor.se
        phoneNumber:
          type: string
          description: 'The phone number of the person to be contacted.

            Phone number should consist only of digits, spaces, dashes with optional leading plus.'
          example: 0999000009
          maxLength: 20
          minLength: 0
        mobileNumber:
          type: string
          description: 'The mobile number of the person to be contacted.

            Mobile number should consist only of digits, spaces, dashes with optional leading plus.'
          example: 0999000009
          maxLength: 20
          minLength: 0
      required:
      - email
      - firstName
      - lastName
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: The reason that caused the error.
          example: The provided product offer does not exist.
        code:
          type: string
          description: An application specific error code to differentiate error responses.
          enum:
          - MISSING_REQUIRED_PARAMETER
          - INVALID_INPUT
          - INVALID_JSON_BODY
          - INVALID_PRODUCT_OFFER
          - MISSING_SITE_ADDRESS
          - INVALID_QOS
          - INVALID_ACCESS_REDUNDANCY
          - INVALID_SLA_LEVEL
          - INVALID_SLA
          - INVALID_ACCESS_SPEED
          - INVALID_ACCESS_TYPE
          - INVALID_ADDITIONAL_SERVICE
          - INVALID_VLAN_CONFIGURATION
          - MISSING_REQUIRED_ADDITIONAL_SERVICE
          - MISSING_BILLING_ADDRESS_INFORMATION
          - INVALID_ADDITIONAL_SERVICE_PARAMETER
          - MISSING_PRODUCT
          - INVALID_ORDER_STATE_CHANGE
          - INVALID_EXTERNAL_ID
          - MISSING_AUTHORIZATION_HEADER
          - UNAUTHORIZED_AGREEMENT_ID
          - UNAUTHORIZED_HEADER_USAGE
          - FORBIDDEN_SITE_ID
          - FORBIDDEN_PRODUCT_ID
          - INVALID_SITE_ID
          - INVALID_PRODUCT_ID
          - ORDER_NOT_FOUND
          - ORDER_ITEM_NOT_CANCELLABLE
          - ONGOING_CANCELLATION_REQUEST_ALREADY_EXISTS
          - CANCELLATION_NOT_FOUND
          - NO_MATCHING_CANCELLATION_CASE_ID
          - CANCELLATION_NOT_UPDATABLE
          - CANCELLATION_STATE_NOT_CONFIRMABLE
          - CANCELLATION_EXPIRED
          - INVALID_CANCELLATION_STATE_CHANGE
          - SALESFORCE_ERROR
          - EXPIRED_QUOTE
          - REJECTED_QUOTE
          - UNAUTHORIZED_QUOTE
          - OPPORTUNITY_UPDATE_NOT_COMPLETE
          - MISSING_AGREEMENT_IN_CAS
          - METHOD_NOT_SUPPORTED
          - MEDIA_TYPE_NOT_SUPPORTED
          - URL_NOT_FOUND
          - INTERNAL_ERROR
          example: MISSING_REQUIRED_PARAMETER
        timestamp:
          type: integer
          format: int64
          description: The date and time using the epoch standard of when the error occurred.
          example: 1615292025
    PaginatedResultMeta:
      type: object
      properties:
        totalRecords:
          type: integer
          format: int64
        pageSize:
          type: integer
          format: int32
        pageNumber:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
    ListCancellationsResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PaginatedResultMeta'
        cancellations:
          type: array
          items:
            $ref: '#/components/schemas/CancellationResponse'
    CancellationRequest:
      type: object
      properties:
        orderItemIds:
          type: array
          description: The list of IDs of the order items for which the cancellation request is being made.
          example: '[''123e4567-e89b-12d3-a456-426614174000'']'
          items:
            type: string
            format: uuid
          minItems: 1
          uniqueItems: true
        contactPersons:
          type: array
          items:
            $ref: '#/components/schemas/CancellationContactPerson'
          minItems: 1
      required:
      - contactPersons
      - orderItemIds
    CancellationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the cancellation request, used for tracking and reference.
          example: c4d82b16-5f3a-4e97-8b20-3d7a9c4e1f56
        orderItemIds:
          type: array
          description: The IDs of the order items for which the cancellation request is being made.
          example:
          - 7e91b3a5-2d04-4c8f-b617-9a3e5f2c1d08
          - 1d08b3a5-2d04-4c8f-b617-7e91e5f2c1d0
          items:
            type: string
            format: uuid
        relatedOrderId:
          type: string
          format: uuid
          description: The ID of the related order.
          example: a3f7c2d1-84e6-4b29-9f05-1c3d7e8a2b4f
        state:
          type: string
          description: Current status of the cancellation request, indicating its progress in the workflow.
          enum:
          - NEW
          - UNDER_REVIEW_BY_TELENOR
          - REJECTED_BY_TELENOR
          - REVIEWED_BY_TELENOR
          - CANCELLATION_CONFIRMED
          - COMPLETED
          example: UNDER_REVIEW_BY_TELENOR
        creationDate:
          type: string
          description: The date and time when the cancellation request was created.
          example: '2024-06-30T14:30:00Z'
        cost:
          type: string
          description: What it will cost the customer to cancel the order item. This is set by Telenor.
          example: 5000
        currency:
          type: string
          description: Currency in which the cancellation cost is specified. This is set by Telenor.
          example: SEK
        expirationDate:
          type: string
          format: date-time
          description: Date and time when the item can no longer be cancelled for the specified cost. This is set by Telenor.
          example: '2024-08-30T23:59:59+02:00'
        reviewerName:
          type: string
          description: Name of the person on Telenor side who reviewed the cancellation request. This is set by Telenor.
          example: John Doe
        reviewerComment:
          type: string
          description: Comment from the reviewer. This is set by Telenor.
        contactPersons:
          type: array
          description: Contact persons on customer side.
          items:
            $ref: '#/components/schemas/CancellationContactPerson'
x-tagGroups:
- name: API Operations
  tags:
  - Order Item Cancellation Request
  - Product Orders
x-provenance:
  method: harvested
  publisher: Telenor Sverige
  source: https://developer.telenor.se/fixed-network-order/openapi
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)