openapi: 3.2.0
info:
  title: Outbound Asn API
  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
tags:
- name: Outbound Asn
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
      tags:
      - Outbound Asn
components:
  schemas:
    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
    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'