openapi: 3.0.3
info:
  title: Outbound ASN
  description: >
    The Outbound ASN API allows clients to be notified when a shipment is
    leaving the Optoro WMS.

    This allows clients to notify other systems so that the inventory can be
    received at the destination.


    For very large shipments or pallets multiple ASNs may be sent. Your systems
    should expect to receive multiple messages for a single carton. Each message
    will have a unique asn number though.


    ## Failure Handling


    <p>When Optoro receives a 401 HTTP status, Optoro will request a new
    Authentication Token from the client’s services and retry the request.</p>

    <p>When Optoro receives any other error (as described above and identified
    by a 4xx (not 401) or 5xx range http status code) Optoro will retry five
    times with the same message.  The retries will happen at an exponential
    backoff cadence in order not to overload machines.  If the failure persists,
    the message will be stored in a failure queue and Optoro will have a
    technical contact person reach out to client tech support to report a
    problem.  When the problem has been resolved, Optoro can manually retry
    failed requests.</p>

    <p>For Outbound ASN acknowledgement, all errors are handled the same since
    this is not in a user facing flow.  However, the differentiation of status
    codes will help Optoro when reporting an issue.</p>
  version: 1.0.0
paths:
  /outbound_asn:
    post:
      summary: Outbound ASN Event
      operationId: outbound_asns
      description: >
        Client endpoint to which Outbound ASN is posted to. <br/>This endpoint
        along with any authentication mechanisms needed must be communicated to
        client's account manager.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - from
                - to
                - asn_number
                - channel
                - shipment_identifier
                - ship_date
                - status
                - details_type
                - cartons
              type: object
              properties:
                from:
                  description: The location this ASN is being sent from.
                  type: object
                  properties:
                    identifier:
                      type: string
                      description: >
                        Identifier for the from location.<br/>

                        When from.type is warehouse:

                        - If an External Identifier is configured for the
                        warehouse, this will surface that identifier.

                        - If not, this will default to the internal OT warehouse
                        ID.
                      example: '16'
                    type:
                      type: string
                      description: >-
                        Type of the from location options include [warehouse,
                        store]. This will typically be “warehouse”.
                      example: warehouse
                to:
                  description: The location this ASN is being sent to.
                  type: object
                  properties:
                    identifier:
                      type: string
                      description: >
                        Identifier for the to location.

                        - When stock transferring, this value is the stock
                        transfer identifier configured in warehouse settings

                        - For freight shipments, this value is the external
                        warehouse identifier configured for the warehouse.

                        - For vendor shipments, this value is a number
                        signifying the internal OptiTurn vendor ID
                      example: '07'
                    type:
                      type: string
                      description: >-
                        Type of the from location options include [warehouse,
                        store]. This will typically be “warehouse”.
                      example: warehouse
                    address:
                      $ref: '#/components/schemas/address'
                asn_number:
                  type: string
                  description: >-
                    A number generated by Optiturn uniquely identifying this
                    ASN. The regex for this value is:
                    /[A-Za-z0-9-_]{1,255}/.<br/><br/> Sometimes Outbound ASNs
                    are split into multiple messages depending on the size of
                    the shipment. In this case each asn_number will be appended
                    by an incremental number, for example: “_1, _2, etc”.
                  example: '1498456_7417412'
                channel:
                  type: string
                  description: >-
                    The channel which the inventory is being fulfilled for -
                    e.g. RTV, RTS, Outlet.
                  example: active_ret
                shipment_identifier:
                  type: string
                  description: >-
                    An identifier for this shipment, representing the Order
                    Number, RA number, or other reference for that shipment.
                  example: WS3710296-213344
                tracking_number:
                  type: string
                  description: >-
                    The tracking number or PRO number for containers in the
                    shipment. If there are multiple different PRO numbers we
                    only pass the first one scanned. There is no character limit
                    on this attribute, Optoro will pass what is scanned. For
                    stock transfers this will always be null.
                  example: 1ZA0000000
                carrier:
                  type: string
                  description: >-
                    The carrier for the shipment. For stock transfers this will
                    always be null.
                  example: UPS GROUND
                carrier_payment_type:
                  type: string
                  description: >-
                    How the carrier will be paid for this shipment, one of:
                    “prepaid” or “collect”. For stock transfers this will always
                    be null.
                  example: collect
                ship_date:
                  type: string
                  description: >-
                    An iso8601 formatted date string representing when the ASN
                    was or will be shipped (YYYY-MM-DDT00:00:00) in UTC. This
                    value can be updated using the update endpoint (below).
                  example: '2023-08-28T04:49:50.693Z'
                status:
                  type: string
                  description: >-
                    Allowed values: “pending”, “shipped”, “delivered”,
                    “canceled”.
                  example: shipped
                details_type:
                  type: string
                  description: This will always be “unit”.
                  example: unit
                cartons:
                  $ref: '#/components/schemas/cartons'
                bol_number:
                  type: string
                  description: The BOL number on the freight shipment.
                  example: '21'
                timestamp:
                  type: string
                  description: iso8601 formatted date string (YYYY-MM-DDT00:00:00) in UTC
                  example: '2023-08-29T03:41:16.848Z'
      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':
          description: Bad Request
        '401':
          description: >-
            Not Authorized. A new Authentication Token from the client’s
            services and retry the request.
        '422':
          description: Validation Failure
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - errors
                properties:
                  message:
                    type: string
                    description: Summary of the error(s).
                  errors:
                    type: array
                    description: Containes 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
        '500':
          description: Internal Server Error
        '502':
          description: Client Server Unavailable
components:
  schemas:
    address:
      type: object
      description: The address this shipment is going to. See below for fields.
      required:
        - name
        - street
        - state
        - city
        - zip
      properties:
        name:
          type: string
          description: The address to name.
          example: Bliss Diamond
        company:
          type: string
          description: The address company line (under name)
          example: Acme
        street:
          type: string
          description: The street address.
          example: 6001 N Dr South
        street2:
          type: string
          description: >-
            An optional second line for the street address, for suite or other
            similar additions.
          example: 60 N Dr North
        city:
          type: string
          description: The city for this address.
          example: LIBERTYVILLE
        state:
          type: string
          description: The state for this address.
          example: OH
        zip:
          type: string
          description: The zip code for this address.
          example: '43125'
    reference:
      type: object
      description: >-
        Reference to a Stock Transfer Order, Return Authorization, RMA, Forward
        Order or Returns Portal Order which can be used to reconcile against.
        See below for fields.
      required:
        - type
        - identifier
      properties:
        type:
          type: string
          description: >-
            Reference type, allowed values are: StockTransferOrder, RA, RMA,
            ForwardOrder or ReturnsPortalOrder.
          example: RA
        identifier:
          type: string
          description: >-
            Reference identifier - for example: the RMA number or RA Number
            associated with this shipment. This is a pass through from the
            inbound ASN.
          example: '573001000000'
        alternate_identifier:
          type: string
          description: Secondary reference identifier.
          example: '742769019332'
    details:
      type: array
      description: >-
        The sku or unit lines expected in this carton. See below for details
        fields.
      items:
        required:
          - line_identifier
          - program_identifier
          - unit_identifier
          - sku
          - quantity
          - condition
        type: object
        properties:
          line_identifier:
            type: string
            description: identifier for this line, unique within this ASN.
            example: '1'
          program_identifier:
            type: string
            description: >-
              Identifies which program the unit was received into. The value
              will be provided by Optoro during implementation.
            example: 16_rma
          unit_identifier:
            type: string
            description: The Optiturn LP for this unit.
            example: A0393197881
          client_unit_identifier:
            type: string
            description: Client unique Identifier
            example: B04847382
          inbound_received_asn:
            type: string
            description: Inbound ASN Number associated with the unit at receiving
            example: d470a87c-4f63-4f0e-bc76-4683247bc434
          sku:
            type: string
            description: The SKU for this item
            example: '768983020002'
          upc:
            type: string
            description: The UPC for this item
            example: '500097771079'
          quantity:
            type: integer
            description: >-
              Always 1 for now, present to match up with standard ASN fields,
              but all Optiturn generated ASNs will be unit level.
            example: 1
          vendor_identifier:
            type: string
            description: The identifier for this unit’s vendor or supplier.
            example: Bradtke and Streich
          serial_number:
            type: string
            description: Serial number for this unit
            example: '11'
          condition:
            type: string
            description: >-
              Condition determined by Optiturn driven warehouse processes.  One
              of N,A,R,B,TT,C,X
            enum:
              - 'N'
              - A
              - R
              - B
              - TT
              - C
              - X
            example: TT
          eligibility_flags:
            type: array
            description: >-
              These are the eligibility flags passed on the inbound ASN and
              configured in OptiTurn
            example:
              - '64'
          merchant:
            type: string
            description: Merchant name for the unit
            example: POLO RALPH LAUREN
    cartons:
      type: array
      description: >-
        Each object (carton) below represents a single box or pallet which has
        been shipped.
      items:
        required:
          - details
        type: object
        properties:
          identifier:
            type: string
            description: The scannable identifier for this carton.
            example: T00028546
          reference:
            $ref: '#/components/schemas/reference'
          details:
            $ref: '#/components/schemas/details'
          sorting_template_name:
            type: string
            description: Name of the last assigned directed sorting template to this carton
            example: Disposable Items
