dropshipping__v4.yml

openapi: 3.0.0
info:
  version: "4"
  title: "Dropshipping"
  description: Long running tasks interface
servers:
  - url: http://suppliers/openapi/Dropshipping/v4
tags:
  - name: Orders
  - name: CalculatedShippingMethods
paths:
  "/orders":
    post:
      tags:
        - Orders
      summary: "Make an order"
      description: "To can make an order you need to specify order information: address, products, supplier and shipping method. Possible response errors: ITEMS_NOT_AVAILABLE"
      requestBody:
        description: ""
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPostRequest'
      responses:
        "200":
          description: "Order successfully created"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        "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'
    get:
      tags:
        - Orders
      summary: "Get list of orders"
      description: "Get list of orders"
      parameters:
        - in: query
          name: "supplierCode"
          description: "Code of supplier (same as id from https://rollun.net/suppliers)"
          required: true
          schema:
            type: string
        - in: query
          name: "fromDate"
          description: "Get order list from date"
          required: false
          schema:
            type: string
        - in: "query"
          name: "toDate"
          description: "Get order list to date"
          required: false
          schema:
            type: string
        - in: query
          name: "idempotencyKey"
          description: "Returning orders with a specific idempotencyKey. Although you cannot re-create an order with an existing idempotency key, there can still be two or more orders with the same idempotency key."
          required: false
          schema:
            type: string
        - in: query
          name: "orderNumber"
          description: "Returning orders with a specific orderNumber. This is a unique value, so it always returns at most one order."
          required: false
          schema:
            type: string
      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: Id of order. If order was created manually you can get it by id in format "supplierCode | orderId"
          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'
  "/calculatedShippingMethods":
    post:
      tags:
        - CalculatedShippingMethods
      summary: "Get all allowed shipping methods for order"
      description: "Returns list of all allowed shipping methods by order info."
      requestBody:
        description: ""
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculatedShippingMethodPostRequest'
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedShippingMethodResult'
        "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:
            - ALREADY_EXIST
            - UNDEFINED
            - INVALID_RESPONSE
            - LOGGER_MESSAGE
            - ITEMS_NOT_AVAILABLE
            - ORDER_CREATION_IS_PENDING
            - ORDER_NOT_FOUND
            - UNKNOWN_SHIPPING_METHOD
            - UNAVAILABLE_SHIPPING_METHOD
            - ORDER_SHIPMENTS_NOT_CREATED
            - CSN_BY_RID_NOT_FOUND
            - RID_BY_CSN_NOT_FOUND
            - ITEM_SHIPPING_RESTRICTED
            - INVALID_ADDRESS
            - RECEIVER_MISMATCH
            - SHIPPING_METHOD_MISMATCH
            - SUPPLIER_MISMATCH
            - ITEMS_MISMATCH
            - SERVICE_UNAVAILABLE
          description: >
            ALREADY_EXIST - An order with the given idempotency key already exists (For special cases when we cannot determine the order number by its idempotency key.)
            UNDEFINED - Any undefined message type
            INVALID_RESPONSE - A message generated by the client stating that the response could not be decoded
            LOGGER_MESSAGE - Same as undefined 
            ITEMS_NOT_AVAILABLE - Cannot create order or calculate shipping methods because items not available
            ORDER_CREATION_IS_PENDING - An order creation request has been sent and is awaiting creation from the supplier
            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
            ORDER_SHIPMENTS_NOT_CREATED - Tucker Rocky order exist, but information about it shipments is not returned
            CSN_BY_RID_NOT_FOUND - Cannot convert rid to csn.
            RID_BY_CSN_NOT_FOUND - Cannot convert csn to rid. Rid in this case will be null.
            ITEM_SHIPPING_RESTRICTED - This item cannot be shipped for various reasons
            INVALID_ADDRESS - Shipping address isn't valid
            RECEIVER_MISMATCH - Actual receiver is different from the requested.
            SHIPPING_METHOD_MISMATCH - Actual shipping method is different from the requested
            SUPPLIER_MISMATCH - Actual supplier is different from the requested
            ITEMS_MISMATCH - Actual items is different from the requested
            SERVICE_UNAVAILABLE - Service temporarly cannot handle request
        text:
          type: string
          description: Message, that describes what went wrong
    SuccessResult:
      allOf:
        - $ref: '#/components/schemas/ErrorResult'
      type: object
      properties:
        data:
          type: object

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


    ## Calculated Shipping Method Results
    CalculatedShippingMethodResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CalculatedShippingMethod'

    ## Requests
    OrderPostRequest:
      type: object
      required:
        - idempotencyKey
        - supplierCode
        - shippingMethodName
        - items
      properties:
        idempotencyKey:
          type: string
          description: An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you.
        supplierCode:
          type: string
          description: Supplier code (same as id from https://rollun.net/suppliers)
        shippingMethodName:
          type: string
          description: >
            Supplier shipping method name
            Pickup - for pickup of orders. In this case, you do not need to define a recipient, but a warehouse is required for each item.
        receiver:
          allOf:
            - $ref: '#/components/schemas/Customer'
          nullable: true
        items:
          type: array
          description: List of items to order
          items:
            $ref: '#/components/schemas/Item'

    CalculatedShippingMethodPostRequest:
      type: object
      required:
        - receiver
        - items
      properties:
        receiver:
          $ref: '#/components/schemas/Customer'
        items:
          type: array
          description: List of items to order
          items:
            $ref: '#/components/schemas/Item'

    ## Resources
    Order:
      type: object
      properties:
        id:
          type: string
          description: >
            Unique identificator of order (generated by server). In format "supplierCode | orderId"
            The order ID is not always the same as the order number. For example, for TuckerRockly, these values are different. To find out the order ID knowing its number, use the get query request
          example: "Autodist | AP7734"
        orderNumber:
          type: string
          nullable: true
          description: >
            The order number received from the supplier. 
            According to it, the order can be found in the user interface on the supplier's website.
        associatedOrderNumbers:
          type: array
          items:
            type: string
          nullable: true
          description: >
            It is used when the order is divided into several deals with different numbers. For example, this happens with a car driver, when ordered from different warehouses, they create a separate order for each warehouse. We combine such orders into one order, with one of the order numbers in the order_number field, and the rest in the associated_order_numbers.
        supplierCode:
          type: string
          example: Autodist
          description: Code of supplier (same as id from https://rollun.net/suppliers)
        paymentCardNumber:
          type: string
          nullable: true
          example: "op acct"
          description: >
            The last 4 digits of the card with which the order was paid. 
            Or the name of the payment method, if it was not paid by a card.
        type:
          type: string
          nullable: true
          enum: ['Dropship', 'Pickup', 'Other']
        status:
          type: string
          enum: ['Ordered', 'Back ordered', 'Tracknumber received', 'Picked up', 'Problem', 'Canceled']
          description: >
            Ordered - The order has been successfully placed with the supplier, but has not yet been completed.
            Back ordered - At least one of the ordered items was backordered.
            Tracknumber received - For dropshipping orders which was fully complete. All parcels that the supplier was going to send were sent, and order has invoice.
            Picked Up - For pickup orders which was complete. All items has picked up and the order has an invoice.
            Problem - The order has at least one problem that is not described in the manifest.
            Canceled - Order cancelled
        shippingTotalPrice:
          type: number
          nullable: true
          example: 9.45
          description: >
            Full shipping price (including all taxes and additional shipping costs)
            For pickup orders it can be some service charge. 
        itemsTotalPrice:
          type: number
          nullable: true
          example: 20.94
          description: Full price of all order items without taxes.
        itemsTax:
          type: number
          nullable: true
          example: 0
          description: The total amount of taxes paid for items
        totalTax:
          type: number
          nullable: true
          example: 0
          description: The total amount of all taxes (including shipping and any additional taxes)
        totalPrice:
          type: number
          nullable: true
          example: 30.39
          description: The total price of the order including taxes and any additional costs
        originalOrder:
          type: string
          nullable: true
          description: Serialized in json original response
        receiver:
          allOf:
            - $ref: '#/components/schemas/Customer'
          nullable: true
          description: Recipient of the order. (May be null for pickup orders.)
        items:
          type: array
          description: List of purchased items
          items:
            $ref: '#/components/schemas/OrderItem'
          nullable: true
        shipments:
          type: array
          nullable: true
          description: >
            Parcels that have been sent, or will be sent (differ in the presence of a track number)
            For pikcup orders there also can be some parcels. For example, when a service fee is charged, this can be considered as the price for delivery. Another example when some items have been sent
          items:
            $ref: '#/components/schemas/Shipment'
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: >
            Time when order was ordered. When the supplier has confirmed that the order has been created.
            Examples
              1. The time when we received a successful order creation response from the supplier API.
              2. The time when the parser finished work and successfully created an order on the site.
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: >
            The time when the order information was changed in the cache. 
            If the order has never changed since the moment it entered the cache, then the time will be equal to the time the order entry was created in the cache.
    CalculatedShippingMethod:
      type: object
      properties:
        supplierCode:
          type: string
          example: autodist
          description: The code of the supplier whose shipping methods are listed
        itemsTotalPrice:
          type: number
          example: 20.94
          description: The total price for the goods of this supplier
        shippingMethods:
          type: array
          items:
            $ref: '#/components/schemas/ShippingMethod'
    ShippingMethod:
      type: object
      properties:
        name:
          type: string
          description: Unique name for one supplier
          example: "USPS Priority"
        totalPrice:
          type: number
          nullable: true
          description: Price for this shipping method without taxes (if available)
          example: 9.45
        totalTax:
          type: number
          nullable: true
          description: Expected total tax
          example: 0
        carrierCode:
          nullable: true
          type: string
          description: The name of the carrier handling the shipment
        shippingSpeed:
          $ref: '#/components/schemas/ShippingSpeed'
    ShippingSpeed:
      type: object
      properties:
        estDeliveryDate:
          type: string
          format: date-time
          description: The estimated delivery date
        trackNumberReceiptDate:
          type: string
          format: date-time
          description: The estimated timestamp when the track number will be received
        firstScanDate:
          type: string
          format: date-time
          description: The estimated timestamp when the first carrier tracking scan occurred
    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)
          nullable: true
        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
    OrderItem:
      type: object
      properties:
        rid:
          type: string
          description: > 
            Rid, which corresponded to csn at the time of order creation. 
            May be null if csn to rid match not found. in this case in messages will be warning message with type RID_BY_CSN_NOT_FOUND.
          example: VW6A4
          nullable: true
        csn: 
          type: string
          description: Supplier internal item identifier
        qtyOrdered:
          type: integer
          description: >
            The number of items that the supplier accepted (The total quantity, including those goods that are in the backorder).
          
            In some cases, it may differ from the quantity we tried to order. For example, when, when creating a pick-up order, the full quantity was not available and we order the quantity that is.
        qtyShipped:
          type: integer
          description: >
            Depends on order status
              If the status is "Tracknumber received" or "Picked up", then the number of items that have been actually shipped or picked up,
              If the status is not "sent", then the number of items that are intending to be sent
          nullable: true
        qtyBackOrdered:
          type: integer
          description: The number of items that have been backordered.
          nullable: true
        unitPrice:
          type: number
          example: 10.47
          description: price for one unit of item
          nullable: true
        trackNumbers:
          type: array
          description: The tracking code of the shipment this item is in
          nullable: true
          items:
            type: string
            example: '9400100000000000000000'
        warehouse:
          type: string
          description: Original warehouse field from supplier (if available)
          nullable: true
    Item:
      type: object
      required:
        - rid
        - quantity
      properties:
        rid:
          type: string
          description: Rollun Id
          example: VW6A4
        quantity:
          type: integer
          description: Quantity of products
          example: 2
        warehouse:
          type: string
          nullable: true
          description: >
            The name of the warehouse from where you want to send the goods. Specific for each supplier.
            If no warehouse has been specified, then the supplier can choose the appropriate one, depending on its distance to the client and the availability of items.
            If a warehouse is specified, then the supplier must send from it, or report an error, why he cannot do this
            Required for pickup orders.
            TuckerRocky - ['TX']
            PartsUnlimited - ['NC']
    Customer:
      type: object
      required:
        - name
        - address
      properties:
        name:
          type: string
          description: Full name
          example: Shawn Weisweaver
        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"
    Address:
      type: object
      required:
        - country
        - state
        - city
        - postalCode
        - address1
      properties:
        country:
          type: string
          description: "Country code"
        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"