TOMP-API-6-AFTER-SALES.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:
    - after-sales
tags:
  - name: after sales
    description: This part of the API describes how the financial settlement should be done. All kinds of fares, fees, debits, and credits are described.

paths:
  /collections/redress-options/items:
    get:
      operationId: getRedressOptions
      summary: "Retrieve redress options for a guarantee"
      description: Returns possible refund or replacement options for a guarantee
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
        - name: packageId
          in: query
          description: the id of the package that contains a purchased product
          required: true
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
        - name: offerId
          in: query
          description: the offer with a guarantee
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/offerReference"
        - name: legId
          in: query
          description: the offer with a guarantee
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/legReference"
        - name: guaranteeId
          in: query
          description: the unfulfilled guarantee 
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
        - name: travellerId
          in: query
          description: to request redresses for a single traveller
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/travellerReference"
        - name: ancillaryId
          in: query
          description: to request redresses for a not-used ancillary or ancillary to remove
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/ancillaryReference"
        - name: supportTicket
          in: query
          description: reference to support ticket(s) to claim redress options
          explode: true
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
      tags:
        - after sales
      x-semantics:
      - transmodel: REFUND QUERY
      responses:
        "200":
          $ref: "#/components/responses/redressResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/claim-redress-option/execution:
    post:
      operationId: redressOptionRequest
      description: redress options must be claimed & confirmed
      tags:
        - after sales
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      x-semantics:
      - transmodel: REDRESS QUERY
      requestBody:
        $ref: "#/components/requestBodies/redressOptionRequest"
      responses:
        "200":
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/packageResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/confirm-redress-option/execution:
    post:
      operationId: confirmRedressOptionRequest
      description: confirm the claimed redress option
      tags:
        - after sales
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      requestBody:
        $ref: "#/components/requestBodies/redressOptionRequest"
      responses:
        "200":
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/packageResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/refund-deposit/execution:
    post:
      operationId: refundDepositRequest
      summary: "Request to refund a deposit"
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      tags:
        - after sales
      requestBody:
        $ref: "#/components/requestBodies/refundDepositRequest"        
      responses:
        "204":
          description: the payment is acknowledged
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /collections/payments/items:
    get:
      operationId: getPaymentOverview
      summary: "Retrieve financial details"
      description: Returns all the JOURNAL ENTRIES that should be paid
      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/limit"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/offset"
        - name: startTime
          in: query
          description: start of the selection
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
        - name: endTime
          in: query
          description: end of the selection
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
        - name: invoiceState
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/paymentState"
        - name: package
          in: query
          required: false
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
        - name: category
          in: query
          description: type of PAYMENT DETAIL (e.g. fare, addition costs, fines, ...)
          required: false
          schema:
            $ref: "#/components/schemas/paymentCategory"
        - name: onBehalveOf
          in: header
          description: the identity of the reseller. Only to be used in a PSP (externalized payments) setup.
          required: false
          schema:
            type: string
      tags:
        - after sales
      responses:
        "200":
          $ref: "#/components/responses/paymentResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/confirm-payment/execution:
    post:
      operationId: confirmPaymentEntry
      summary: "Confirm a financial transaction"
      description: The MP (reseller) confirms a payment
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      tags:
        - after sales
      requestBody:
        $ref: "#/components/requestBodies/confirmPaymentRequest"
      responses:
        "204":
          description: the payment is acknowledged
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

  /processes/cancel-package/execution:
    post:
      operationId: cancelPackageOperation
      summary: "Cancel a package in confirmed state for (technical issues)."
      description: 
        Cancel this package. This endpoint is only there to correct (technical) issues.<br>
        Normally, after purchase, you have to request redress options, claim it and confirm the claim.<br>
        <br>
        Before purchase you release a package.<br>
        During the purchase you rollback a package.<br>
      parameters:
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/acceptLanguage"
        - $ref: "TOMP-API-1-CORE.yaml#/components/parameters/authorization"
      tags:
        - after sales
      x-semantics:
      - transmodel: TRAVEL PACKAGE CANCELLATION QUERY
      requestBody:
        $ref: "TOMP-API-1-CORE.yaml#/components/requestBodies/packageRequest"
      responses:
        "200":
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/packageResponse"
        default:
          $ref: "TOMP-API-1-CORE.yaml#/components/responses/errorResponse"

components:
  requestBodies:
    redressOptionRequest:
      x-semantics:
      - transmodel: none
      content:
        application/json:
          schema:    
            type: object
            required:
            - inputs
            properties:
              inputs:
                type: object
                required:
                - package
                - guarantee
                - option
                properties:
                  package:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
                  offer:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/offerReference"
                  guarantee:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
                  option:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"

    refundDepositRequest:
      x-semantics:
      - transmodel: none
      content:
        application/json:
          schema:    
            type: object
            required:
            - inputs
            properties:
              inputs:
                type: object
                properties:
                  package:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
                  leg:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/legReference"

    confirmPaymentRequest:
      x-semantics:
      - transmodel: none
      content:
        application/json:
          schema:    
            type: object
            required:
            - inputs
            properties:
              inputs:
                type: object
                required:
                - paymentId
                properties:
                  paymentId:
                    $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"                    

  responses:
    redressResponse:
      x-semantics:
      - transmodel: none
      description: a list of redress options
      headers:
        Version:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/version"
        Content-Language:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
        Expires:
          schema:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/httpDate"
          required: true
      content:
        application/geo+json:
          schema:
            $ref: "#/components/schemas/redressOptions"

    paymentResponse:
      x-semantics:
      - transmodel: none
      description: journal entries
      headers:
        Content-Language:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/contentLanguage"
        Version:
          $ref: "TOMP-API-1-CORE.yaml#/components/headers/version"
      content:
        application/geo+json:
          schema:
            $ref: "#/components/schemas/payments"    

  schemas:
    redressOptions:
      x-semantics:
      - transmodel: TRAVEL REDRESSes
      type: object
      required:
        - type
      properties:
        type:
          type: string
          pattern: "^(FeatureCollection)$"
        features:
          type: array
          items:
            type: object
            properties:
              id: 
                $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
              type:
                type: string
                pattern: "^(Feature)$"
              properties:
                $ref: "#/components/schemas/redressOption"
              links:
                type: array
                items:
                  $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
        properties:
          type: object
          properties:
            type: 
              type: string
              pattern: "^(redressOptions)$"
            package:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
            offer:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/offerReference"
            guarantee:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
        numberMatched:
          type: number
        numberReturned:
          type: number
        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" 

    redressOption:
      x-semantics:
      - transmodel: TRAVEL REDRESS
      type: object
      properties:
        type:
          type: string
          pattern: "^(RedressOption)$"
        id:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
        packageState:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageStatus"
        redressType:
          type: string
          enum: [ PACKAGE_REFUND,
                OFFER_REFUND,
                LEG_REFUND,
                ANCILLARY_REFUND,
                REPLACEMENT ]
        reason:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/guarantee"
        compensations:
          type: array
          items:
            $ref: "#/components/schemas/financialDetail"
        replacements:
          type: array
          items: 
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageProperties"

    paymentCategory:
      x-semantics:
      - transmodel: none
      type: string
      description: The category of the journalled item <br>
        _ALL_ - for filtering purposes only<br>

        <h2>TO initiated payments </h2>
        To request these payments, use the notifications, send a notification containing the payment confirmation.<br>
        _DEPOSIT_ - a deposit, to refund, use _REFUND_<br>
        _DAMAGE_ - extra costs that must be paid by the MP due to damage to the asset or ancillaries<br>
        _LOSS_ - extra costs that must be paid by the MP due to loss of asset or ancillaries<br>
        _STOLEN_ - the asset (and ancillaries) are stolen and should be paid for<br>
        _EXTRA_USAGE_ - the asset is paid for in advance, additional usage must be paid for (can also be a refund when used less! The amount should be negative in that case)<br>
        _FINE_ - a fine that arrived later on<br>
        _OTHER_ASSET_USED_ - additional costs for a replaced asset<br>
        _FARE_ - the normal costs of the purchased and executiond leg(s)<br>
        _OTHER_ - unspecified<br>

        _CREDIT_ - generic CREDIT, e.g. for kick-backs <br>
        _VOUCHER_ - part of the fare that is covered by a voucher (no need to pay)<br>
        _REFUND_ - refund of the deposit or upfront paid fare<br>
        _REBATE_ - (partial) rebate of the fare<br>
        _REIMBURSEMENT_ - reimbursement of the fare<br>
      enum: [ ALL,
              DAMAGE,
              LOSS,
              STOLEN,
              EXTRA_USAGE,
              REFUND,
              REBATE,
              REIMBURSEMENT,
              FINE,
              OTHER_ASSET_USED,
              CREDIT,
              VOUCHER,
              DEPOSIT,
              OTHER,
              FARE ]

    financialDetail:
      x-semantics:
      - transmodel: none
      allOf:
      - $ref: "TOMP-API-1-CORE.yaml#/components/schemas/amountOfMoney"
      - type: object
        properties:
          id:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/uuid"
            description: id of the JOURNAL ENTRY, the LEG id should be used
          category:
            $ref: "#/components/schemas/paymentCategory"

          state:
            $ref: "#/components/schemas/paymentState"
          expirationDate:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"

          sequenceId:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/tinyInt"
            description: sequence id of the JOURNAL ENTRY, in combination with **id** unique from TO perspective.
          invoiceId:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
            description: the number of the invoice. Should be filled in when invoiced (**state**=_INVOICED_).
          invoiceDate:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
          comment:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/longString"
          units:
            type: array
            items:
              type: object
              properties:
                unitCategory:  
                  type: string
                  enum: [DISTANCE, DURATION, USAGE, OTHER]
                description:
                  type: string
                unit: 
                  type: string
                  enum: [KM, MILE, HOURS, MINUTES, DAYS, LITER, KILOWATTHOUR, CO2_COMPENSATION, OTHER]
                amount:
                  $ref: "TOMP-API-1-CORE.yaml#/components/schemas/float"

          vatNumber:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
            description: VAT identification number.
          bankAccount:
            $ref: "#/components/schemas/bankAccount"
            description: this account will be used
          customFields:
            $ref: "TOMP-API-1-CORE.yaml#/components/schemas/customProperties"

    paymentState:
      x-semantics:
      - transmodel: none
      type: string
      description: the state of the payment detail
      enum: [TO_INVOICE, INVOICING, INVOICED]

    payments:
      x-semantics:
      - transmodel: none
      description: a list of offers.
      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/financialDetail"
              links:
                type: array
                items:
                  $ref: "TOMP-API-1-CORE.yaml#/components/schemas/link"
        properties:
          type: object
          description: this object contains the filter parameters
          properties:
            type:
              type: string
              pattern: "^(paymentCollection)$"
            limit:
              type: integer
            offset:
              type: integer
            startTime:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
            endTime:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/dateTime"
            invoiceState:
              $ref: "#/components/schemas/paymentState"
            package:
              $ref: "TOMP-API-1-CORE.yaml#/components/schemas/packageReference"
            category:
              $ref: "#/components/schemas/paymentCategory"          
        numberMatched:
          type: number
        numberReturned:
          type: number
        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"

    bankAccount:
      x-semantics:
      - transmodel: none
      type: object
      description: bank account
      additionalProperties: false
      required:
        - name
        - number
      properties:
        name:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
          description: account name
        number:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
          description: account number
        country:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/country"
        bankIdentification:
          $ref: "TOMP-API-1-CORE.yaml#/components/schemas/shortString"
          description: bank identification, like BIC code