suppliers_orders_cache__v1.yml

openapi: 3.0.0
info:
  version: "1"
  title: "SuppliersOrdersCache"
  description: REST CRUD for suppliers orders cache data store (https://rollun.net/SuppliersOrdersDataStore). 
servers:
  - url: http://suppliers/openapi/SuppliersOrdersCache/v1
tags:
  - name: Orders
paths:
  "/orders":
    get:
      tags:
        - Orders
      summary: "Get list of orders"
      parameters:
        - name: rql
          in: query
          required: false
          schema:
            type: string
            example: 'and(eq(supplierCode,Autodist),eq(status,Ordered))'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            example: 'name'
        - name: sortOrder
          in: query
          required: false
          schema:
            type: string
            enum:
              - "asc"
              - "desc"
            default: "asc"
            example: 'asc'
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderListResult"
        '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 | orderNumber"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        "500":
          description: 'Some internal error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
    put:
      tags:
        - Orders
      summary: 'Updating (not partial) or creating an order in the cache'
      description: |
        Partial updates are not allowed with the PUT method. 
        
        BE CAREFUL! All fields that you did not specify in the request body will be replaced with default values or null if no default value is specified for the field.
        
        UpdatedAt and CachedAt field automaticaly filled.
        
        If sum of "shippingTotalPrice", "itemsTotalPrice", itemsTax" and "totalTax" not equals to "totalPrice" than message with type "PRICES_MISMATCH" will be added (if not already added). Also, this message will be automatically deleted if prices become equal.
      parameters:
        - in: path
          name: id
          description: Order number "supplierCode | orderNumber"
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPutRequest'
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        "500":
          description: 'Some internal error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
    patch:
      tags:
        - Orders
      summary: 'Partial update of order in cache'
      description: |
        Null values for field is equivalent to undefined and will not changes the order value.
        
        If you need to set some field to null use PUT method (Do not forget to get the values of other fields before that, because PUT updates the order resource completely).
        
        If sum of "shippingTotalPrice", "itemsTotalPrice", itemsTax" and "totalTax" not equals to "totalPrice" than message with type "PRICES_MISMATCH" will be added (if not already added). Also, this message will be automatically deleted if prices become equal.
      parameters:
        - in: path
          name: id
          description: Order number "supplierCode | orderNumber"
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPatchRequest'
      responses:
        "200":
          description: 'Success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResult'
        "500":
          description: 'Some internal error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
components:
  schemas:
    # Basic results components
    ErrorResult:
      type: object
      properties:
        messages:
          type: array
          nullable: true
          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
        type:
          type: string
          enum:
            - UNDEFINED
            - ORDER_NOT_FOUND
            - INVALID_RESPONSE
          description: >
            You can expose this enum for all your errors
            UNDEFINED - Any undefined message type
            ORDER_NOT_FOUND - cannot find order by id
            INVALID_RESPONSE - A message generated by the client stating that the response could not be decoded
        text:
          type: string
          description: Message, that describes what went wrong
    SuccessResult:
      allOf:
        - $ref: '#/components/schemas/ErrorResult'
      type: object
      properties:
        data:
          type: object
          nullable: true
          
    ## Result with list of resource
    OrderListResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Order'

    ## One resource result
    OrderResult:
      allOf:
        - $ref: '#/components/schemas/SuccessResult'
      type: object
      properties:
        data:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Order'

    ## Body for put request
    OrderPutRequest:
      allOf:
        - $ref: "#/components/schemas/OrderBody"
      required:
        - supplierCode
        - orderNumber
        - status
        - checkedAt
    
    # Body for patch request
    OrderPatchRequest:
      properties:
        supplierCode:
          type: string
          nullable: true
        orderNumber:
          type: string
          nullable: true
        purchaseOrderNumber:
          type: string
          nullable: true
        idempotencyKey:
          type: string
          nullable: true
        associatedOrderNumbers:
          type: array
          items:
            type: string
          nullable: true
        paymentCard:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
          enum: ['Ordered', 'Back ordered', 'Completed', 'Problem', 'Canceled']
        shippingTotalPrice:
          type: number
          nullable: true
        itemsTotalPrice:
          type: number
          nullable: true
        itemsTax:
          type: number
          nullable: true
        totalTax:
          type: number
          nullable: true
        totalPrice:
          type: number
          nullable: true
        receiver:
          allOf:
            - $ref: '#/components/schemas/Customer'
          nullable: true
        items:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/OrderItem'
        shipments:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Shipment'
        messages:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/OrderMessage"
        createRequest:
          type: string
          nullable: true
        createResponse:
          type: string
          nullable: true
        originalOrder:
          type: string
          nullable: true
        checkedAt:
          type: string
          nullable: true
          format: date-time
        createdAt:
          type: string
          nullable: true
          format: date-time
    
    ## Resource object
    Order:
      allOf:
        - $ref: "#/components/schemas/OrderBody"
      properties:
        id:
          type: string
          description: >
            Unique identificator of order in format "supplierCode | orderNumber"
          example: "Autodist | AP7734"
        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 null.
            
            Changes in 'messages', 'createRequest', 'createResponse', 'originalOrder', 'updatedAt', 'checkedAt', 'cachedAt' field do not update 'updatedAt'.
            
            Comparison of arrays (fields 'item', 'shipment' e.t.c) is order dependent. ['a', 'b'] and ['b', 'a'] is different arrays.
        cachedAt:
          type: string
          format: date-time
          description: >
            Time when record with order was created in the cache
    
    OrderBody:
      type: object
      properties:
        supplierCode:
          type: string
          example: Autodist
          description: Code of supplier (same as id from https://rollun.net/suppliers)
        orderNumber:
          type: string
          example: AP7734
          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.
        purchaseOrderNumber:
          type: string
          description: Original p.o. number value if supplier has one
          nullable: true
        idempotencyKey:
          type: string
          description: >
            An idempotency key is a unique value generated by the client which the server uses to avoid duplication. How you create unique keys is up to you. Since order can be created manualy in user interface we cannot ensure that this field is unique.
          nullable: true
        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 autodist, 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.
        paymentCard:
          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.
        status:
          type: string
          enum: ['Ordered', 'Back ordered', 'Completed', '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.
            
            Completed - For orders which was fully complete. All items were sent or picked up and order has invoice.
            
            Problem - The order has at least one problem that is not described in the manifest.
            
            Canceled - Order cancelled. Prices in this status are equal to the values that were actually paid (in most cases, this is zero, but some cancellation penalties can be removed)
        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
        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
          nullable: true
          items:
            $ref: '#/components/schemas/OrderItem'
        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'
        messages:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/OrderMessage"
          description: Messages with warning level (or below)
          default: []
        createRequest:
          type: string
          nullable: true
          example: "{}"
          description: Serialized in json request for creating createOrderTask
        createResponse:
          type: string
          nullable: true
          example: "{}"
          description: Serialized to json the raw data of the supplier response when requesting to create an order.
        originalOrder:
          type: string
          nullable: true
          example: "{}"
          description: Serialized in json last saved raw order data from a supplier.
        checkedAt:
          type: string
          format: date-time
          description: >
            Time in UTC of the last check of the order data.
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: |
            Time in UTC 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.
    
    OrderMessage:
      type: object
      properties:
        level:
          type: string
          enum:
            - warning
            - notice
            - info
        type:
          type: string
          enum:
            - UNDEFINED
            - ORDER_NOT_FOUND
            - RID_BY_CSN_NOT_FOUND
            - IDEMPOTENCY_KEY_PROBLEM
            - UNPARSED_ADDRESS_FIELD
            - PRICES_MISMATCH
            - RECEIVER_MISMATCH
            - SHIPPING_METHOD_MISMATCH
            - SUPPLIER_MISMATCH
            - ITEMS_MISMATCH
          description: >
            If you add a new type to this manifest, then also add it to the SuppliersOrders manifest.
            
            UNDEFINED - Any undefined message type
            ORDER_NOT_FOUND - Cannot find order by id
            RID_BY_CSN_NOT_FOUND - Cannot convert csn to rid. Rid in this case will be null.
            IDEMPOTENCY_KEY_PROBLEM - The idempotency key cannot be uniquely identified for an order.
            UNPARSED_ADDRESS_FIELD - Unable to parse one of the address fields. This field will contain an empty string.
            PRICES_MISMATCH - sum of prices parts ("shippingTotalPrice", "itemsTotalPrice", itemsTax" and "totalTax") not equals to totalPrice
            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
        text:
          type: string
          description: Message, that describes what went wrong
    
    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
          nullable: true
          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:
          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
          nullable: true
          description: The tracking code of the shipment this item is in. Can be null if it is impossible to match items to shipments.
          items:
            type: string
            example: '9400100000000000000000'
        warehouse:
          type: string
          description: Original warehouse field from supplier (if available)
          nullable: true
    
    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"