trip-order.yaml

swagger: '2.0'
info:
  description: >-
    Order Service 2.0 - Next version of On Demand Mobility Microservice with local cache of data for 
    trips and orders.  (Invoice and Payment is not in scope here.)
    
    This service has very simple endpoints. For each domain object there are two REST resources:
    <ol>
      <li>.../my -> query for all objects of the currently logged in user.</li>
      <li>.../search -> query for all itmes that match the given filter parameters with sorting and paging
    </ol>
  version: 2.0.0
  title: Trips and Orders
host: odm-order-service.int.odm.reachnow.cn
basePath: /odmxcn-order2-service
schemes:
  - http
paths:
  /trips/my:
    get:
      summary: "Get the list of past trips of a member"
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ArrayOfTrips'
  
  /trips/search:
    post:
      summary: "Search for trips"
      consumes:  
        - application/json
      produces:
        - application/json
      parameters:
      - in: "body"
        name: "Search parameters"
        description: >-
          All filter parameters are optional. But at least one filter should be given.
          Filters can be combined. Only trips that match all given filters will be returned.
        required: true
        schema:
          $ref: "#/definitions/SearchTripsQuery"  
      responses:
        '200':
          description: "Result of search query"
          schema:
            properties:
              numResults:
                type: integer
                description: "number of results that match the given filter"
                example: 1234
              page: 
                type: integer
                description: "the page number that was requested"
                example: 5
              lastPage:
                type: integer
                description: "last page number that has results in it for these filters"
                example: 12
              result:
                $ref: '#/definitions/ArrayOfTrips'
  
            
  /orders/my:
    get:
      summary: "Get a list of all orders for the currently logged in member"
      description: "Fetch a list of orders for the currently logged in member from the internal cache."
      produces:
        - application/json
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/ArrayOfOrders'
            
  /orders/search:
    post:
      summary: "Search for orders"
      consumes:  
        - application/json
      produces:
        - application/json
      parameters:
      - in: "body"
        name: "Search parameters"
        description: >-
          All filter parameters are optional. But at least one filter should be given.
          Filters can be combined. Only orders that match all given filters will be returned.
        required: true
        schema:
          $ref: "#/definitions/SearchOrdersQuery"  
      responses:
        '200':
          description: "Result of search query"
          schema:
            properties:
              numResults:
                type: integer
                description: "number of results that match the given filter"
                example: 1234
              page: 
                type: integer
                description: "the page number that was requested"
                example: 5
              lastPage:
                type: integer
                description: "last page number that has results in it for these filters"
                example: 12
              result:
                $ref: '#/definitions/ArrayOfOrders'
  
  
            
definitions:
  
  ArrayOfTrips:
    type: array
    items:
      $ref: '#/definitions/Trip'

  Trip:
    type: "object"
    required:
    - "timeRequested"
    - "tripType"
    description: >-
      A trip is a customer's ride from A to B. A trip has been performed by a driver at a given time.
      The trip object does not have any price information! It just contains the plain basic information
      about the trip itself, such as time, duration and distance. Later when the trip is "priced"
      in corelation to a given tarif model, then the trip becomes part of an order.
    properties:
      tripType:
        type: "string"
        description: "onDemand, scheduledHalfDay, scheduled, scheduledFullDay"
        enum:
        - scheduled
        - scheduledHalfDay
        - scheduledFullDay
        - onDemand
        example: onDemand
      drivenKilometers:
        type: "number"
        description: "Driven kilometers of this trip. Two decimal precision"
      duration:
        type: "string"
        description: "Duration of the trip, given in hh:mm:ss"
      memberId:
        type: string
        description: "id of the member who took the trip. See also Rider field, if the trip was ordered by a member for someone else."
        example: "6ebf8977-fd24-4015-8cc9-9e3eccbc9966"
      driverId:
        type: "string"
        description: "uuid of the driver"
        example: "6ebf8977-fd24-4015-8cc9-9e3eccbc9966"
      vin:
        type: "string"
        description: "vehicle identification number (VIN-17) of the vehicle which\
          \ was used for the trip"
      pickupLocation:
        $ref: "#/definitions/GeoLocation"
      dropoffLocation:
        $ref: "#/definitions/GeoLocation"
      actualPickupLocation:
        $ref: "#/definitions/GeoLocation"
      actualDropOffLocation:
        $ref: "#/definitions/GeoLocation"
      plannedPickupLocation:
        $ref: "#/definitions/GeoLocation"
      plannedDropOffLocation:
        $ref: "#/definitions/GeoLocation"
      timeRequested:
        type: "string"
        format: "date-time"
        description: "Time when the member booked the trip in the APP. (bookedTime)"
      actualPickupTime:
        type: "string"
        format: "date-time"
        description: "Time when the member was picked up for the trip"
      actualDropoffTime:
        type: "string"
        format: "date-time"
        description: "Time when the trip was finished"
      rider:
        $ref: "#/definitions/Rider"
      estimatedPickupTime:
        type: "string"
        format: "date-time"
        description: "initially estimated pickup datetime"
      canellationTime:
        type: "string"
        format: "date-time"
        description: "DateTime when the trip has been cancelled"
      fate:
        type: "string"
        description: "Finished or cancellation reason (enum value)"
        enum:
        - finished
        - canceledByCustomer
        - canceledByCic
        - canceledNoShow
        - noDriverAvailable
        example: finished

  SearchTripsQuery:
    type: object
    description: "Filter parameteres for a trip search. All filters are optional. Also supports paging and sorting in the backend."
    properties:
      tripIds:
        type: array
        description: "Array of tripIds to lookup"
        example: ["6ebf8977-fd24-4015-8cc9-9e3eccbc9966", "634577-fd24-4015-8cc9-9e3eccbc9966"]
        items:
          type: string
      tripType:
        type: string
        description: "Filter for tripType (one of the enum values)"
        enum:
        - scheduled
        - scheduledHalfDay
        - scheduledFullDay
        - onDemand
        example: onDemand
      isCanceled:
        type: boolean
        description: "Filter for canceled trips."
        example: false
      memberId:
        type: array
        description: "Array of members UUIDs"
        example: ["6ebf8977-fd24-4015-8cc9-9e3eccbc9966", "634577-fd24-4015-8cc9-9e3eccbc9966"]
        items: 
          type: string
      datePickupFrom:
        type: string
        format: "date-time"
        description: "Filter for trips that started (actualPickupTime) on or after this date. The filter result includes trips on the given date."
      datePickupTo:
        type: string
        format: "date-time"
        description: "Filter for trips that started (actualPickupTime) on or before this date. The filter result will include trips on that date, e.i. trips stat started just before midnight at the end of that day."
      dateRequestedFrom:
        type: string
        format: "date-time"
        description: "Filter for trips that were requested (requestedTime) on or after this date. The filter result includes trips on the given date."
      dateRequestedTo:
        type: string
        format: "date-time"
        description: "Filter for trips that were requested (requestedTime) on or before this date. The filter result will include trips on that date, e.i. trips stat started just before midnight at the end of that day."
      sortBy:
        type: string
        description: "Which column to sort for. Result can be sorted by any attribute that a trip has."
        enum:
        - tripId
        - memberId
        - driverId
        - vin
        - tripType
        - dateRequested
        - actualPickupTime
        - drivenKilometers
        - duration
        - fate
      itemsPerPage:
        type: integer
        description: "server side paging. How many items shall be returned per page"
        example: 100
      page:
        type: integer
        description: >-
          server side paging: which page shall be returned. page == 0 is the first page.
          When itemsPerPage * page > num results, then an empty array will be returned
      
        
        
      

  ArrayOfOrders:
    type: array
    items:
      $ref: '#/definitions/Order'


  Order:
    type: "object"
    required:
    - "memberContractId"
    - "memberUuid"
    - "orderId"
    description: >-
      An order (DE: "Warenkorb") contains one more more products. Each product has a price and 
      may be orderes once or multiple times. Each order has a type. A trip is just one possible
      type of product. Although it is the most common type. Furhter types of products are
      - TRIP
      - ADDITIONAL_FEE
      - PREPAID_PACKAGE
      - COUPON
      - SNACKS
    properties:
      orderId:
        type: string
        description: >-
          orderId as set by the service who created the order. 
          For a trip, this is the tripId generated by rh-trip-service with the prefix 
          E_ for end trip or C_ for cancel trip.
        example: "E_6ebf8977-fd24-4015-8cc9-9e3eccbc9966"
      memberUuid:
        type: string
        description: "uuid of the member who placed the order"
        example: "0c577020-d58f-4b9e-b191-0c253180e93d"
      tripId:
        type: string
        description: "If this order contains a trip, then this is the foreignKey pointing to the trip. This field is optional."
        example: "6ebf8977-fd24-4015-8cc9-9e3eccbc9966"
      currency:
        type: "string"
        description: "ISO 4217 currency code for all amounts, e.g. CNY"
      lineItems:
        $ref: "#/definitions/ArrayOfLineItems"
      orderPriceNet:
        type: number
        description: "sum of all lineItemPriceNet"
        example: 199.23
      orderPriceGross:
        type: number
        description: "sum of all lineItemPriceGross"
        example: 201.00

  SearchOrdersQuery:
    type: object
    description: "Filter parameteres for an order search. All filters are optional. Also supports paging and sorting in the backend."
    properties:
      orderIds:
        type: array
        description: "Array of orderIds to fetch"
        example: ["C_6ebf8977-fd24-4015-8cc9-9e3eccbc9966", "E_634577-fd24-4015-8cc9-9e3eccbc9966"]
        items:
          type: string
      memberIds:
        type: array
        description: "Array of memberUuids, all orders of these members match this filter. This query should be combined with other filters."
        example: ["6ebf8977-fd24-4015-8cc9-9e3eccbc9966", "634577-fd24-4015-8cc9-9e3eccbc9966"]
        items:
          type: string
      tripIds:
        type: array
        description: "Array of tripIds to lookup. Will match all orders from these trips"
        example: ["6ebf8977-fd24-4015-8cc9-9e3eccbc9966", "634577-fd24-4015-8cc9-9e3eccbc9966"]
        items:
          type: string
      sortBy:
        type: string
        description: "Which column to sort for. Result can be sorted by any attribute that a trip has."
        enum:
        - tripId
        - memberId
        - orderPriceGross
      itemsPerPage:
        type: integer
        description: "server side paging. How many items shall be returned per page"
        example: 100
      page:
        type: integer
        description: >-
          server side paging: which page shall be returned. page == 0 is the first page.
          When itemsPerPage * page > num results, then an empty array will be returned


  ArrayOfLineItems:
    description: >-
      An order (DE: "Warenkorb") contains a list of products that the customer ordered.
      Each product has a price and may be orderd multiple times.
    type: array
    items:
      $ref: '#/definitions/LineItem'


  LineItem:
    type: object
    properties:
      productType:
        type: string
        description: >-
          The type (enum value) of the product that the customer bought or used.
          This is the machine readable ID for this product.
          Remark: Coupons may have a negative cost.
          Additional Fees are just normal items within this order.
          Furhter types of products might be defined in the future.
        example: TRIP
        enum:
          - TRIP
          - ADDITIONAL_FEE
          - PREPAID_PACKAGE
          - COUPON
          - SNACKS
          - OTHER_PRODUCT
      productName:
        type: object
        description: "localized name or freetext description of this product or fee. Keys are uppercase, e.g. EN, CN"
        additionalProperties:
          type: string
        example:
          EN: Some product name in english
          CN: 一些英文产品名称
      unitCostNet:
        type: number
        description: "The net amount for one unit of this product, given in stated currency. Two decimals precision. Cost may be negative for coupons!"
        example: 17.22
      unitCostGross:
        type: number
        description: "The gross amount for one unit of this product, given in stated currency. Two decimals precision. Cost may be negative for coupons!"
        example: 18.01
      quantity:
        type: integer
        description: "Number of times this product was bought with this order"
        example: 2
      lineItemPriceNet:
        type: number
        description: "unitCostNet * quantity = lineItemPriceNet"
        example: 34.44
      lineItemPriceGross:
        type: number
        description: "unitCostGross * quantity = lineItemPriceGross "
        example: 36.01


  Rider:
    type: "object"
    required:
    - "phoneNumber"
    description: >-
      If someone requested a ride for someone else (e.g. B2B Use cases), 
      then this contains information about the actual rider.
    properties:
      phoneNumber:
        type: "string"
        example: "8618616826259"
        description: "Phone number that can be used by the driver to call the rider."
      firstName:
        type: "string"
        example: "John"
        description: "First name of the rider."
      lastName:
        type: "string"
        example: "Doe"
        description: "Last name of the rider."


  GeoLocation:
    type: "object"
    required:
    - "latitude"
    - "longitude"
    properties:
      latitude:
        type: "number"
        example: 48.133382
      longitude:
        type: "number"
        example: 11.5455068
      locationDisplayName:
        type: "string"
        example: "娴︿笢棣欐牸閲屾媺澶ч厭搴�"
        description: "Name (POI) of the geolocation. e.g. Hotel XY. May contain Chinese\
          \ and Latin characters and numbers."
      locationDisplayAddress:
        type: "string"
        example: "娴︿笢鏂板尯瀵屽煄璺�33鍙�"
        description: >-
          Address information of the geolocation. Contains information
          on country, province, city, district, town, road/lane number, building
          
          
  ErrorResponse:
    type: object
    required:
      - type
    properties:
      type:
        type: string
        example: BUSINESS
        description: error type e.g. BUSINESS
        enum:
          - BUSINESS
          - UNKNOWN
          - AUTHENTICATION
          - VALIDATION
          - CONNECTION
          - APPLICATION
      code:
        type: string
        example: B-VAL-12345
        description: error code e.g. B-VAL-12345
      message:
        type: string
        example: '[B-VAL-12345] Cannot assign coupon XY to unknown uuid abc...'
        description: Message describing error details.
      field:
        type: string
        example: productId
        description: The name of the field which makes problems e.g. productId
      token:
        type: string
        example: ae910634-0e48-11e7-93ae-92361f002671
        description: Token to find the log entry - UUID
      extraInformation:
        type: array
        description: May contain extra information about error
        items:
          type: object
    description: Default standard error response object