TOMP-API-5-SUPPORT.yaml

openapi: 3.1.0
info:
  title: Transport Operator MaaS Provider API
  description: "<h2>Context</h2>
    <p>This API allows technical communication between Transport Operators (TO) and MaaS providers (MP, and other resellers), to fulfill a complete MaaS user journey<br>
    For more information: <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-entry-page'>TOMP-API wiki</a>, and <a href='https://github.com/TOMP-WG/TOMP-API/wiki/OpenAPI-code-convention'>Coding conventions</a>"
  version: "2.0.0"
  contact:
    name: TOMP working group
    url: https://github.com/TOMP-WG/TOMP-API
  license:
    name: Apache 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
  x-modules:
    - support
tags:
  - name: support
    description: This part of the API facilitates in handling exceptions, like delays, flat tires, accidents or broken equipment reports.

paths:
  /collections/support-tickets/items:
    get:
      operationId: getSupportTickets
      summary: "Get for support tickets of a package/leg"
      description: returns support tickets in their current state, based on the parameters
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/packageId"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/legId"
        - $ref: "#/components/parameters/supportTicketStatus"
      tags:
        - support
      responses:
        "200":
          $ref: "#/components/responses/ticketsResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/request-support/execution:
    post:
      operationId: requestSupport
      summary: "Create a support ticket"
      description: creates a request for SUPPORT from end user via MP
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      tags:
        - support
      requestBody:
        $ref: "#/components/requestBodies/supportRequest"
      responses:
        "200":
          description: support request acknowledged, the response contains a support ticket with a unique ID. Multiple support tickets can be created on one single leg.
          headers:
            Content-Language:
              $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/supportTicket"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"
          
components:
  requestBodies:
    supportRequest:
      x-semantics:
      - transmodel: none
      content:
        application/json:
          schema:    
            type: object
            required:
            - inputs
            properties:
              inputs:
                $ref: "#/components/schemas/supportTicket"

  responses:
    ticketsResponse:
      x-semantics:
      - transmodel: none
      description: a list of tickets
      headers:
        Version:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/version"
        Content-Language:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
      content:
        application/geo+json:
          schema:
            type: object
            properties:
              type:
                type: string
                pattern: "^(FeatureCollection)$"
              features:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      pattern: "^(Feature)$"
                    id:
                      $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
                    properties:
                       $ref: "#/components/schemas/supportTicket"                 
              links:
                type: array
                description:
                  actions that can be performed on this package, but also alternative (rel=alternative+1, alternative+2) offers or references to other resources
                  In case it is an alternative, specify clearly in the description what the financial consequences are.
                items:
                  $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
  
  parameters:
    supportTicketStatus:
      x-semantics:
      - transmodel: none
      name: supportTicketStatus
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/supportTicketStatus"

  schemas:
    supportTicket:
      x-semantics:
      - transmodel: none
      type: object
      required:
        - supportType
        - type
        - location
        - timestamp
      properties:
        id:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
          description: ticketID, to be provided when created. Mandatory when status != REQUESTED
        type:
          type: string
          pattern: "^(supportTicket)$"
        status:
          $ref: "#/components/schemas/supportTicketStatus"
        supportType:
          type: string
          description: these are the currently enlisted support requests<br>
            _BROKEN_DOWN_ The asset doesn't work anymore<br>
            _NOT_AT_LOCATION_ The asset isn't available at the specified time/location<br>
            _MISSING_AFTER_PAUSE_ The asset is missing (stolen?)<br>
            _NOT_CLEAN_ The asset is not clean<br>
            _NOT_AVAILABLE_ The asset is at the location, but unreachable<br>
            _UNABLE_TO_OPEN_ The asset cannot be unlocked (malfunctioning)<br>
            _UNABLE_TO_CLOSE_ The asset cannot be closed (malfunctioning)<br>
            _ACCIDENT_ Accident occurred<br>
            _OTHER_ unspecified<br>
            _REPORT_DAMAGE_ Oeps. Photo sent with slight damage<br>
            _REQUEST_ASSISTANCE_ request personal assistance, e.g. to get into the train<br>
            _EVIDENCE_ Send evidence to the TO for redress functions<br>
          enum: [ BROKEN_DOWN,
                  NOT_AT_LOCATION,
                  MISSING_AFTER_PAUSE,
                  NOT_CLEAN,
                  NOT_AVAILABLE,
                  UNABLE_TO_OPEN,
                  UNABLE_TO_CLOSE,
                  ACCIDENT,
                  OTHER,
                  REPORT_DAMAGE,
                  REQUEST_ASSISTANCE,
                  EVIDENCE
                ]
                
        context:
          type: object
          properties:
            asset:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/assetReference"    
            leg:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/legReference"    
            product:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/productReference"    
            package:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
        
        location:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/placeReference"
        timestamp:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
          description: the reporting timestamp of the support request
        priority:
          type: string
          description: the priority of the support request.
          enum: [ ERROR_CANNOT_CONTINUE,
                  ERROR_CAN_CONTINUE,
                  DISTURBING_ISSUE,
                  QUESTION,
                  OTHER ]
        contactInformationEndUser:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/normalString"
          description: contact information of the end user in case of direct response requests, like phone number
        comment:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/longString"
        urls:
          type: array
          description: urls to clarify the support request e.g. pictures showing damage or digital scans with evidence documents
          maxItems: 10
          items:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/url"
        requestedResponseTime:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortInt"
          description: time to respond in minutes.
        timeToResolution:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortInt"
          description: time in minutes to the expected resolution of support request
        damage:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/damage"
        sequence:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/tinyInt"
          description: the sequence number of the status of tickets on this issue
        links:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/links"
          
    supportTicketStatus:
      x-semantics:
      - transmodel: none
      type: string
      description:
        _ISSUE_REQUESTED_ the ticket is new, to be processed by the TO<br>
        _ISSUE_OPEN_ the ticket is open, we're on our way<br>
        _ISSUE_UPDATE_REQUESTED_ we're waiting on a response of the traveller(s)<br>
        _ISSUE_RESOLVED_ Issue succesfully closed<br>
        _ISSUE_REVOKED_ Issue revoked<br>
      enum: [ ISSUE_REQUESTED,
              ISSUE_OPEN,
              ISSUE_UPDATE_REQUESTED,
              ISSUE_RESOLVED,
              ISSUE_REVOKED ]