Telenor Sverige CSTA Line API

openapi: 3.2.0
info:
  description: '# Important endpoints for using the Partner CSTA API:

    ## getUserInfo (in the Partner Catalog API)

    This method would typically be the first method called by a partner application towards the Partner APIs.

    It returns information that is needed in other API calls.

    This endpoint is accessed with:


    ```http GET /catalog/userInfo ```


    Following attributes are returned:

    - **uid** Identifies a User

    - **groupId** Identifies the Company that the user belongs to (not used in Telenor Sweden solution)

    - **userName** The user name (not used in Telenor Sweden solution)

    - **products** A list of product codes that the user has access to. Different product codes gives access to certain endpoints.

    - **agreementAccesses** A list of accesses to companies and/or departments within a company. This contains an attribute **agreementId** the value of this is to be used in API calls when a groupId or companyId is to be provided.


    ## getToken (in the Partner Status API)

    For usage of the mbn-partner-csta API it is necessary to initially use 2 endpoint calls:

    1. getToken, that should return e newly generated token

    2. loginByToken, with the token returned by getToken.

    getToken is accessed with:


    ```http GET /status/token ```

    ## loginByToken

    This endpoint is used to log onto the mbn-partner-csta-api and establish a valid HTTP session identified by a JSESSIONID cookie.

    In addition, this endpoint will return a LSV cookie, and is important that the partner application use both the JSESSIONID and LSV cookie in subsequent operations in the mbn-partner-csta API.

    This endpoint is accessed with:


    ```http POST /csta/authentication/token ```


    with the following header parameters:

    - **token** The token value returned from *getToken*

    - **groupId** A valid *groupId* obtained from *getUserInfo*. Use the agreementId instead.


    ## logout

    A partner application that has been using the mbn-partner-csta API and wishes to end that usage in a clean fashion, can call this endpoint.

    This will end the HTTP session.

    This endpoint is accessed with:


    ```http DELETE /csta/authentication/token ```


    # CSTA usage

    ## Prerequisite steps

    To be able to:

    - Receive events

    - Perform call handling


    these prerequisite steps need to be completed:

    1. Authentication

    2. Perform getToken

    3. Perform loginByToken


    ## Starting monitor(s)

    No events can be received by the partner client before one or more monitors have been started.

    The partner application can start one or multiple monitors.

    Currently it is only one type of monitor that can be started:

    ### Whole enterprise monitor

    This monitor type will provide events for a whole enterprise and all its users.

    The events are related to:

    - Phone calls made by or to any user in the enterprise. Certain number fields in the events have been removed in the events to prevent gathering information about who is calling who.


    - Availability of any user in the enterprise.


    Such a monitor can be started by calling *monitorStart*:


    ```http POST /csta/line/monitor/company/{companyId} ```


    If successful, this operation will return a monitorId that is "GROUP-{companyId}". All events generated by this monitor will include the field monitorId = "GROUP-{companyId}".


    ## Event polling

    The partner client should maintain a continuous event polling loop.

    A single event polling can be made by calling *getEvents*:


    ```http GET /csta/events ```


    When invoking this endpoint, one of two should happen:

    - It will hang for 30 seconds and return no events (because no events were generated)

    - It will return before 30 seconds with one or more events as soon as new events were generated.


    A partner application should invoke a new *getEvents* as soon as possible after the previous *getEvents* returned.

    The first *getEvents* can be issued either immediately before or after the monitors are started.

    ## Stopping monitors

    Monitors can also be stopped.

    ### Whole enterprise monitor

    Such a monitor is stopped by issuing a *monitorStop*:


    ```http DELETE /csta/line/monitor/company/{companyId} ```'
  version: '1.0'
  title: Partner CSTA CSTA Line API
servers:
- url: https://apis.telenor.se/mbn-partner-csta/
tags:
- name: CSTALine
paths:
  /v1/csta/line/monitor/company/{companyId}:
    post:
      tags:
      - CSTALine
      summary: monitorStart
      description: 'Start a monitor for CSTA Line. The monitor will be for the whole company and no call handling.

        Returns a monitorId


        Make sure that JSESSION and LSV cookies are included (example: Cookie: JSESSIONID=DU-l0h-evLGa6jGxXEjMH2dQVXHrw9KaWgtgvFef.tgbe1;LSV=0)'
      operationId: monitorStart
      parameters:
      - name: Authorization
        in: header
        description: OAuth 2.0 Authorization. Token provided via https://apis.telenor.se/openapi/oauth2/token API.
        required: true
        x-example: Bearer Ca5lRGqLdD9m7LXSBAo0tKEpQGkd
        schema:
          type: string
      - name: x-jwt
        in: header
        description: A jwt that has been created via https://apis.telenor.se/b2b/partner/auth/right/hasPermission/partner
        required: true
        x-example: eyJhbGciOiJsUzI1NiJ9.eyJpc3MiOiJUZwXlbm9yIFN3ZWRlbiIsImF1zCI6IlrTryIsInN1yiI6IjmyndIymJAiLcJPyzqiOje7ODB8Nzg5MzUSImv5cCI6MTy8Msy4mjAznX0.UdtcbgHUd43uTfPJ1bEfg7jXcDfvbyD04W_S5tjljSHRzYycOCqbYvMpm8AEV5KuwZxG573dDc0p_nvGKeSj4G2f-an3N3VyaAiiKNHFG2ML2Ta6nZgj_-Pi0cNzMhM6R_7_ggaCS0UGnEEUWO-GQSj0D-VnEeJ5sUOWc-SYEXdT9KBynmU5xqQKktIQz7YMc0_TPpDk4uc0XR3ja5yLLOMIx1ZuHloRITeMUZ0s-I9NYGHgD_b8H62GzL94jDjOEYSzwqPyWXeZksfQNxzdD2UrDaZdZ1YDMhz5GigSdvK07maYH8SJnjTtXIaM7jw-uGjxOElUMrgKK6ZNqqoORw
        schema:
          type: string
      - name: companyId
        in: path
        description: The id of the company to start the monitor for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: string
        '400':
          description: 'Bad request: The request was malformed or not according to the specification.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '401':
          description: 'Unauthorized: You have either not provided a valid token or the token provided is not valid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: 'Forbidden: You are authenticated, but are not authorized and can not access this resource'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: 'Internal server error: Something unexpected happened.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
    delete:
      tags:
      - CSTALine
      summary: monitorStop
      description: 'Stop a CSTA Line monitor.


        Make sure that JSESSION and LSV cookies are included (example: Cookie: JSESSIONID=DU-l0h-evLGa6jGxXEjMH2dQVXHrw9KaWgtgvFef.tgbe1;LSV=0)'
      operationId: monitorStop
      parameters:
      - name: Authorization
        in: header
        description: OAuth 2.0 Authorization. Token provided via https://apis.telenor.se/openapi/oauth2/token API.
        required: true
        x-example: Bearer Ca5lRGqLdD9m7LXSBAo0tKEpQGkd
        schema:
          type: string
      - name: x-jwt
        in: header
        description: A jwt that has been created via https://apis.telenor.se/b2b/partner/auth/right/hasPermission/partner
        required: true
        x-example: eyJhbGciOiJsUzI1NiJ9.eyJpc3MiOiJUZwXlbm9yIFN3ZWRlbiIsImF1zCI6IlrTryIsInN1yiI6IjmyndIymJAiLcJPyzqiOje7ODB8Nzg5MzUSImv5cCI6MTy8Msy4mjAznX0.UdtcbgHUd43uTfPJ1bEfg7jXcDfvbyD04W_S5tjljSHRzYycOCqbYvMpm8AEV5KuwZxG573dDc0p_nvGKeSj4G2f-an3N3VyaAiiKNHFG2ML2Ta6nZgj_-Pi0cNzMhM6R_7_ggaCS0UGnEEUWO-GQSj0D-VnEeJ5sUOWc-SYEXdT9KBynmU5xqQKktIQz7YMc0_TPpDk4uc0XR3ja5yLLOMIx1ZuHloRITeMUZ0s-I9NYGHgD_b8H62GzL94jDjOEYSzwqPyWXeZksfQNxzdD2UrDaZdZ1YDMhz5GigSdvK07maYH8SJnjTtXIaM7jw-uGjxOElUMrgKK6ZNqqoORw
        schema:
          type: string
      - name: companyId
        in: path
        description: The id of the company to stop the monitor for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
        '400':
          description: 'Bad request: The request was malformed or not according to the specification.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '401':
          description: 'Unauthorized: You have either not provided a valid token or the token provided is not valid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: 'Forbidden: You are authenticated, but are not authorized and can not access this resource'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: 'Internal server error: Something unexpected happened.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
components:
  schemas:
    ErrorDescriptionResponse:
      type: object
      properties:
        errorCode:
          type: integer
          format: int32
        description:
          type: string
x-provenance:
  method: harvested
  publisher: Telenor Sverige
  source: https://developer.telenor.se/communication/csta/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)