Optoro Dispositions API

openapi: 3.2.0
info:
  title: Disposition Update Dispositions API
  version: 1.0.0
  contact:
    name: Fulfillment
  description: '## Introduction

    The Disposition Update API is used to communicate to the client a change in state/disposition, of a unit as it moves through the ROP and is placed in its next possible value disposition.'
servers:
- url: https://developer.optoro.com
tags:
- name: Dispositions
paths:
  /dispositions:
    post:
      summary: POST a unit's disposition update
      operationId: dispositions
      description: 'Client endpoint to which disposition update data is posted to.


        This endpoint along with any authentication mechanisms needed must be communicated to client''s account manager.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispositionPayload'
      responses:
        '200':
          description: Success. Optoro recommends client APIs respond with a JSON-structured object. This is used for debugging purposes only so this guidance is technically optional.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFailure'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/ServerUnavailable'
      tags:
      - Dispositions
components:
  schemas:
    DispositionPayload:
      type: object
      description: Disposition Update Data
      properties:
        from_disposition:
          type: string
          description: 'Indicates which channel this unit is from. Options include: b2b, d2c, client_liquidation, destroy, dispose, donate, outlets, recycle, removed, rts, rts_drop_ship, rtv, stock_transfer'
          example: needs_testing
        to_disposition:
          type: string
          description: 'Indicates which channel this unit is designated to.  Options include: b2b, d2c, client_liquidation,  destroy, dispose, donate, outlets, recycle, removed, rts, rts_drop_ship, rtv, stock_transfer'
          example: recycle
        timestamp:
          type: string
          description: iso8601 formatted date string (YYYY-MM-DDT00:00:00) in UTC
          example: '2018-03-20T00:00:00'
        location_identifier:
          type: string
          description: Shared storage location identifier (present in both Optoro  and client’s system) representing the units current location
          example: RTS-1112
        warehouse_identifier:
          type: string
          description: Indicates the warehouse where the unit is located. Identifier can be configured by the client; otherwise will default to Optoro’s internal warehouse identifier
          example: '22'
        optiturn_lp:
          type: string
          description: Unique alphanumeric id of the unit
          example: LPAA1234567
        program_identifier:
          type: string
          description: Either a client-provided program name or OptiTurn’s internal program id
          example: parcel_returns
        from_sku:
          type: string
          description: Indicates the client SKU associated with the unit before a change - will be the same as to_sku if the unit didn’t change SKU
          example: '012344566700'
        to_sku:
          type: string
          description: Indicates the client SKU associated with the unit after the change - will be the same as from_sku if the unit didn’t change SKU
          example: '012344566700'
        sku:
          type: string
          description: This field is deprecated and may be removed in a future version of the API. Please use from_sku and to_sku above instead
          example: '012344566700'
        upc:
          type: string
          description: UPC for the unit
          example: 0123456789012
        from_condition:
          type: string
          description: '[N, TT, R, A, B, C, X] indicating which condition the unit was before its new disposition, a condition mapping is often created to match your internal conditions'
          enum:
          - N
          - TT
          - R
          - A
          - B
          - C
          - X
          example: N
        to_condition:
          type: string
          description: '[N, TT, R, A, B, C, X] indicating which condition the unit is at its new disposition, a condition mapping is often created to match your internal conditions'
          enum:
          - N
          - TT
          - R
          - A
          - B
          - C
          - X
          example: TT
        reference_unit_identifier:
          type: string
          description: A client-provided identifier for the unit, likely provided by an inbound integration
          example: Unit A
        store_identifier:
          type: string
          description: The identifier of the store that returned the unit to the warehouse
          example: Store A
        user_login:
          type: string
          description: OptiTurn username of the user that triggered the disposition change. Only included for client users, not 3PL
          example: client_user_login
      additionalProperties: false
      required:
      - from_disposition
      - to_disposition
      - timestamp
      - location_identifier
      - warehouse_identifier
      - optiturn_lp
      - program_identifier
      - upc
      - from_condition
      - to_condition
    ValidationFailure:
      type: object
      required:
      - message
      - errors
      properties:
        message:
          type: string
          description: Summary of the error(s).
        errors:
          type: array
          description: Contains one or more error objects.
          items:
            type: object
            required:
            - field
            - code
            description: Describes a single validation failure.
            properties:
              field:
                type: string
                description: JSON path of the field that failed validation.
              code:
                type: string
                description: Categorization of validation failure. Defaults to 'invalid'.
                enum:
                - missing_field
                - invalid_type
                - invalid
  responses:
    InternalServerError:
      description: Internal Server Error
    BadRequest:
      description: Bad Request
    ServerUnavailable:
      description: Client Server Unavailable
    Unauthorized:
      description: Not Authorized. A new authentication token will be requested from the client's services and the request will be retried.