marketplaces_orders__v1.yml

openapi: 3.0.0
info:
  version: "1"
  title: "MarketplacesOrders"
  description: Long running tasks interface
servers:
  #- url: http://marketplaces/openapi/Marketplaces/v1
  - url: http://l.service-marketplaces/openapi/MarketplacesOrders/v1
tags:
  - name: Orders
  - name: TrackNumbers
paths:
  "/orders":
    get:
      tags:
        - Orders
      summary: "Get list of orders"
      description: "Get list of orders"
      parameters:
        - name: marketplaceName
          in: query
          description: "Name of marketplace (e.g. Amazon Shoptimistic, Ebay Rollun, Ebay Plaisir, Rollun Walmart)"
          example: "Ebay Rollun"
          required: false
          schema:
            type: string
        - name: fromDate
          in: query
          description: "Get order list from date"
          example: "2021-01-01 10:00:00"
          required: false
          schema:
            type: string
        - name: toDate
          in: query
          description: "Get order list to date"
          example: "2021-02:01 09:59:59"
          required: false
          schema:
            type: string
        - name: orderNumbers
          in: query
          description: "A comma-separated list of the unique identifiers of the orders to retrieve. If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored"
          required: false
          #style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          description: The number of orders to return per page of the result set. Default 1000
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: The number of orders to skip in the result set before returning the first order in the paginated response. Default 0
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderListResult"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResult"
        '500':
          description: "Internal error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
  "/orders/{id}":
    get:
      tags:
        - Orders
      summary: 'Get info about specific order'
      description: "Returns information of order by orderId"
      parameters:
        - in: path
          name: id
          description: Order identifier"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        "400":
          description: "Bad request. See messages type field for details."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        "500":
          description: 'Some internal error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
  "/trackNumbers":
    post:
      tags:
        - TrackNumbers
      summary: "Set tracking number to marketplace order"
      description: ""
      requestBody:
        description: ""
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackNumberPostRequest'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskInfoResult'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
        500:
          description: 'Some internal error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'

components:
  schemas:
    ErrorResult:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
      description: "Message field is not required"
    Message:
      type: object
      properties:
        level:
          type: string
          enum:
            - emergency
            - alert
            - critical
            - error
            - warning
            - notice
            - info
            - debug
        type:
          type: string
          enum:
            - UNDEFINED
            - TRACKNUMBER_ALREADY_EXIST
            - ORDER_NOT_FOUND
            - UNKNOWN_SHIPPING_METHOD
            - UNAVAILABLE_SHIPPING_METHOD
            - INVALID_RESPONSE
          description: >
            UNDEFINED - Any undefined message type
            TRACKNUMBER_ALREADY_EXIST - A tracking number already exists
            ORDER_NOT_FOUND - Order not found by order number
            UNKNOWN_SHIPPING_METHOD - The selected supplier does not have this shipping method (or needs to be added)
            UNAVAILABLE_SHIPPING_METHOD - A shipping method exists but is not available for this order
        text:
          type: string
          description: Message, that describes what went wrong
    SuccessResult:
      allOf:
        - $ref: '#/components/schemas/ErrorResult'
      type: object
      properties:
        data:
          type: object
    Collection:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
          default: 1000
        next:
          type: string
        total:
          type: integer

    OrderList:
      allOf:
        - $ref: '#/components/schemas/Collection'
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    OrderResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Order'
    OrderListResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          $ref: '#/components/schemas/OrderList'
    TrackNumberResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TrackNumber'

    ## Requests

    TrackNumberPostRequest:
      type: object
      required:
        - orderId
        - items
        - trackNumber
        - shippment
      properties:
        orderId:
          type: string
        items:
          type: array
          description: List of items to order
          items:
            $ref: '#/components/schemas/Item'
        trackNumber:
          type: string
        shipment:
          $ref: '#/components/schemas/Shipment'

    Item:
      type: object
      required:
        - orderItemId
        - quantity
      properties:
        orderItemId:
          type: string
          description: Marketplace order item id
          example: 283346427419
        quantity:
          type: integer
          description: Quantity of products
          example: 2

    Shipment:
      type: object
      properties:
        trackNumber:
          type: string
          description: The tracking code provided by the carrier (if order items has sended)
          example: '9400100000000000000000'
          nullable: true
        shippingMethodName:
          type: string
          example: USPS Priority
          description: Name of shipping method (same as name in shippingMethod)
        shippingPrice:
          type: number
          description: "Total price of this shipment"
          example: 9.45
          nullable: true
        carrierCode:
          # TODO: Move as separate enum component
          type: string
          description: The name of the carrier handling the shipment

    ## Resources
    Order:
      type: object
      required:
        - id
        - marketplaceName
        - shippingMethod
        - status
        - receiver
        - items
        - createdDate
      properties:
        id:
          type: string
          description: Unique identificator of marketplace order
          example: 09-04655-72127
        marketplaceName:
          type: string
          example: EbayPlaisir
        shippingMethod:
          type: string
          example: SecondDay
        status:
          type: string
          description: "Order Status"
          enum:
            - "pending"
            - "paid"
            - "processing"
            - "fulfilled"
        totalTax:
          description: Total price of taxes including item taxes and ?
          type: number
          nullable: true
          example: 0
        totalPrice:
          type: number
          nullable: true
          example: 30.39
          description: The total price of the order including taxes and any additional costs
        itemsTax:
          type: number
          nullable: true
          example: 0
        shippingTotalPrice:
          type: number
          nullable: true
          example: 9.45
        itemsTotalPrice:
          type: number
          nullable: true
          example: 20.94
        totalMarketplaceFee:
          type: number
          nullable: true
          example: 1.97
        buyer:
          nullable: true
          description: Buyer of the order
          allOf:
            - $ref: '#/components/schemas/Buyer'
        receiver:
          allOf:
            - $ref: '#/components/schemas/Receiver'
          description: Receiver of products
        items:
          type: array
          description: List of purchased items
          items:
            $ref: '#/components/schemas/OrderItem'

        createdDate:
          type: string
          format: date-time
        paidDate:
          type: string
          format: date-time
        shipDate:
          type: string
          nullable: true
          format: date-time
        deliveryDate:
          type: string
          nullable: true
          format: date-time

        note:
          type: string
          nullable: true
        shipments:
          type: array
          nullable: true
          description: List of all parcels that sent this order
          items:
            $ref: '#/components/schemas/Shipment'

    #        createdAt:
    #          type: string
    #          format: date-time
    #        updatedAt:
    #          type: string
    #          format: date-time
    #          nullable: true
    OrderItem:
      type: object
      properties:
#        orderItemId:
#          type: string
#          description: Marketplace order line id
        mln:
          type: string
          description: Marketplace listing number
          example: VW6A4
        quantity:
          type: integer
          description: The number of items.
        price:
          type: number
          example: 10.47
          description: price for one unit of item
          nullable: true
        msin:
          type: string
        rid:
          type: string
        shippingTemplate:
          type: string
        shippingPrice:
          type: number
    #        trackNumber:
    #          type: string
    #          description: The tracking code of the shipment this item is in
    #          example: '9400100000000000000000'
    #          nullable: true
    Customer:
      type: object
      properties:
        name:
          type: string
        phone:
          type: string
          nullable: true
          description: Phone number to reach the person
          example: "415-123-4567"
        email:
          type: string
          nullable: true
          description: Email address to reach the person
          example: "test@mail.loc"
        address:
          $ref: "#/components/schemas/Address"
    Buyer:
      allOf:
        - $ref: "#/components/schemas/Customer"
    Receiver:
      allOf:
        - $ref: "#/components/schemas/Customer"
      required:
        - name
        - address
    BaseAddress:
      type: object
      properties:
        country:
          type: string
          description: "Country code"
          nullable: true
        state:
          type: string
          description: US state code
          example: CA
        city:
          type: string
          description: Full city name
          example: San Francisco
        postalCode:
          type: string
          description: ZIP or postal code
          example: "94104"
        address1:
          type: string
          description: First line of the address
          example: "417 Montgomery St"
        address2:
          type: string
          nullable: true
          description: Second line of the address
          example: "Floor 5"
    Address:
      allOf:
        - $ref: "#/components/schemas/BaseAddress"
        - type: object
          required:
            - country
            - state
            - city
            - postalCode
            - address1
    TaxAddress:
      allOf:
        - $ref: "#/components/schemas/BaseAddress"
        - type: object
          required:
            - country
            - postalCode
    TrackNumber:
      type: object
      properties:
        orderId:
          type: string
        items:
          type: array
          items:
            type: string
        trackNumber:
          type: string
        shippment:
          $ref: '#/components/schemas/Shipment'


    TaskInfoResult:
      allOf:
        - $ref: '#/components/schemas/Result'
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TaskInfo'
    TaskInfo:
      type: object
      required:
        - id
        - timeout
        - stage
        - status
      properties:
        id:
          type: string
          example: 'qwerty123'
        timeout:
          type: integer
          example: '3'
        stage:
          $ref: '#/components/schemas/Stage'
        status:
          $ref: '#/components/schemas/Status'
        startTime:
          type: string
          description: 'Task start time UTC'
          example: '2020-11-20T13:14:15Z'
        result:
          $ref: '#/components/schemas/TrackNumberResult'

    Result:
      allOf:
        - $ref: '#/components/schemas/ErrorResult'
      type: object
      properties:
        data:
          type: object
    Stage:
      type: object
      required:
        - stage
        - all
      properties:
        stage:
          type: string
          description: 'Current stage'
          example: 'writing 2'
        all:
          type: array
          description: 'All possible stages'
          items:
            type: string
          example: [ 'writing 1','writing 2','writing 3','calc summary','done' ]
    Status:
      type: object
      required:
        - state
        - all
      properties:
        state:
          type: string
          description: 'Current state'
          example: 'pending'
        all:
          type: array
          description: 'All possible states'
          items:
            type: string
          example: [ 'pending','fulfilled','rejected' ]