Loadsmart YMS - Spot API

openapi: 3.2.0
info:
  title: Opendock Nova API Documentation YMS - Spot API
  description: '## Welcome to Opendock Nova! #### What is Opendock Nova? Opendock is an online dock appointment scheduling tool. Facilities such as warehouses, distribution centers, and

    manufacturing plants use it to organize their docks and schedule appointments for outbound pickups and inbound

    deliveries. You can read all our knowledge base

    articles here. We now provide an SSO option for User Authentication. Read

    the docs here. ---


    ## Our APIs


    We have 3 main APIs:


    - REST API called _Neutron_ for performing standard HTTP operations. - Real-time API called _Subspace_ for receiving streaming events whenever objects are Created/Updated/Deleted. - A **"Reference Number Validation"** aka "PO Validation" _protocol_ for validating PO numbers (or similar) before an

    appointment is scheduled. Detailed documentation for it can be found

    here: PO/Ref Number Validation Implementation


    ---


    ## Neutron - REST API


    All endpoints are listed below. Depending on your User Role, some may be forbidden. Almost all endpoints expect a simple

    JWT token to be set in the `Authorization: Bearer` HTTP header. Read more about Bearer

    tokens here. ### Base URL


    The base URL is the same as it is for this document (look at the current URL in your browser''s address bar). For

    example, our production Neutron Base URL is https://neutron.opendock.com. ### Authentication


    To start, call the `POST /auth/login` endpoint to exchange your user credentials (email + password) for a simple JWT

    token. If you don''t have an account yet, reach out to your account admin or contact us for further help. If login is successful, the response will be a JWT token to use as your `Bearer` header as described above. The JWT expiration time depends on your User Role as well as other factors. You may base64-decode your JWT token to view

    more technical details about it. #### Test it:


    To test that your auth headers are set correctly, call the `GET /auth/me` endpoint. It will return a JSON payload with

    your User information. ---


    ## Subspace - Real-time Streaming API


    Subspace is a _read-only_ API that allows your system to recieve streaming real-time information about changes to your

    Appointments, Warehouses, Docks, etc. Using Subspace you can implement a "push"-based approach to your integration instead of relying only on "poll"-ing

    methods (which can be inefficient). Subpsace is based on the famous `socket.io` library. ### Choosing a socket.io Client


    The socket.io project provides a JavaScript client library that works in the browser as well as NodeJS. However there

    are also client implementations in many other languages including C#, Java, Python, and Go, so you should select the

    appropriate client for your project. A good overview of socket.io and a list of client implementations can be found

    here: Socket.IO Introduction


    **NOTE:** Currently Opendock uses socket.io server **v4.x** so please make sure to select an appropriate socket.io

    client version that is protocol compatible. ### Connecting and Authentication


    The base connection URL is the same as the base URL for Neutron above, except with the word "subspace" instead of "

    neutron". For example, our production Subspace connection URL

    is wss://subspace.opendock.com. For convenience, the same JWT token obtained from the Neutron `/auth/login` endpoint above is used for Subspace

    authentication. Connecting and Authenticating are done in a single operation: simply connect to the following `wss` URL:


    ```

    ?token=

    ```


    That can be a little confusing to parse. Here''s a real-life example connection string:


    ```

    wss://subspace.opendock.com?token=eyJhbGciOiJIUzI1Ni...(full token continues)

    ```


    **NOTE:** Currently Opendock only supports the `websocket` transport, so you must specify this in your connection

    settings. Here''s an example of connecting to Subspace using the JavaScript client:


    ```JavaScript

    // NOTE: we assume "accessToken" was already obtained earlier via a call to ''/auth/login''.'
  version: v4.144.0 - 39b4253
  contact: {}
servers:
- url: https://neutron.opendock.com
  description: Production Server
- url: https://neutron.staging.opendock.com
  description: Staging Server
tags:
- name: YMS - Spot
paths:
  /yard/spot:
    get:
      operationId: getManyBaseSpotControllerSpot
      summary: Retrieve multiple Spots
      parameters:
      - name: fields
        description: Selects resource fields. <a href="https://github.com/nestjsx/crud/wiki/Requests#select" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - name: s
        description: Adds search condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#search" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: string
      - name: filter
        description: Adds filter condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#filter" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: or
        description: Adds OR condition. <a href="https://github.com/nestjsx/crud/wiki/Requests#or" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: sort
        description: Adds sort by field. <a href="https://github.com/nestjsx/crud/wiki/Requests#sort" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: join
        description: Adds relational resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#join" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: limit
        description: Limit amount of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#limit" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: offset
        description: Offset amount of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#offset" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: page
        description: Page portion of resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#page" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
      - name: cache
        description: Reset cache (if was enabled). <a href="https://github.com/nestjsx/crud/wiki/Requests#cache" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 1
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSpotDto'
      tags:
      - YMS - Spot
      security:
      - bearer: []
    post:
      operationId: createOneBaseSpotControllerSpot
      summary: Create a single Spot
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpotDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/generate:
    post:
      operationId: SpotController_generate
      summary: Generate multiple spots
      description: Generates multiple spots in the yard
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpotManyDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/{id}:
    patch:
      operationId: updateOneBaseSpotControllerSpot
      summary: Update a single Spot
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSpotDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
    delete:
      operationId: deleteOneBaseSpotControllerSpot
      summary: Delete a single Spot
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
      tags:
      - YMS - Spot
      security:
      - bearer: []
    get:
      operationId: getOneBaseSpotControllerSpot
      summary: Retrieve a single Spot
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: fields
        description: Selects resource fields. <a href="https://github.com/nestjsx/crud/wiki/Requests#select" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - name: join
        description: Adds relational resources. <a href="https://github.com/nestjsx/crud/wiki/Requests#join" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: cache
        description: Reset cache (if was enabled). <a href="https://github.com/nestjsx/crud/wiki/Requests#cache" target="_blank">Docs</a>
        required: false
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 1
      responses:
        '200':
          description: Get one base response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/delete/bulk:
    post:
      operationId: SpotController_bulkDelete
      summary: Bulk delete spots
      description: Deletes multiple spots in the yard
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteSpotManyDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/{id}/close:
    patch:
      operationId: SpotController_closeSpot
      summary: Close a spot
      description: Closes a spot in the yard blocking spot assignments
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSpotStatusDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/{id}/open:
    patch:
      operationId: SpotController_openSpot
      summary: Open a spot
      description: Opens a spot in the yard for spot assignment
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSpotStatusDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Spot'
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/{id}/toggle-reserve:
    patch:
      operationId: SpotController_toggleReserveSpot
      summary: Toggle spot reserve
      description: Either create or remove a spotReserve entry for such spot
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToggleSpotReserveDto'
      responses:
        '200':
          description: ''
      tags:
      - YMS - Spot
      security:
      - bearer: []
  /yard/spot/{id}/events:
    get:
      operationId: SpotController_getSpotEvents
      summary: Get spot events
      description: Retrieves all events associated with a specific spot in the yard
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SpotEvent'
      tags:
      - YMS - Spot
      security:
      - bearer: []
components:
  schemas:
    CreateSpotDto:
      type: object
      properties:
        tags:
          type: object
        code:
          type: string
        type:
          $ref: '#/components/schemas/SpotType'
        spotAreaId:
          type: string
          format: uuid
        observation:
          type: string
      required:
      - code
      - type
      - spotAreaId
    ListSpotDto:
      type: object
      properties:
        entity:
          type: string
          readOnly: true
          enum:
          - Spot
        action:
          type: string
          readOnly: true
          enum:
          - read
        data:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/SpotItemDto'
      required:
      - entity
      - action
      - data
    SpotItemDto:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          format: uuid
        createDateTime:
          type: string
          readOnly: true
          format: date-time
        createdBy:
          type: string
          readOnly: true
          format: uuid
        lastChangedDateTime:
          type: string
          readOnly: true
          format: date-time
        lastChangedBy:
          type: string
          readOnly: true
          format: uuid
        isActive:
          type: boolean
          readOnly: true
        tags:
          type: array
          readOnly: true
          example:
          - external
          - waiting
        orgId:
          type: string
          readOnly: true
          format: uuid
        warehouseId:
          type: string
          readOnly: true
          format: uuid
        code:
          type: string
          readOnly: true
          example: G300
        type:
          type: string
          readOnly: true
          enum:
          - parking
          - docking
          example: parking
        spotAreaId:
          type: string
          readOnly: true
          format: uuid
        observation:
          type: string
          readOnly: true
          example: This is a spot observation.
        spotAssignments:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/SpotAssignment'
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - lastChangedBy
      - isActive
      - tags
      - orgId
      - warehouseId
      - code
      - type
      - spotAreaId
      - observation
      - spotAssignments
    DeleteSpotManyDto:
      type: object
      properties:
        tags:
          type: object
        spotIds:
          type: array
          items:
            type: string
            format: uuid
      required:
      - spotIds
    DeleteResult:
      type: object
      properties: {}
    CreateSpotManyDto:
      type: object
      properties:
        tags:
          type: object
        numberOfSpots:
          type: number
        startFromNumber:
          type: number
        leadingChar:
          type: string
        type:
          $ref: '#/components/schemas/SpotType'
        spotAreaId:
          type: string
          format: uuid
      required:
      - numberOfSpots
      - startFromNumber
      - type
      - spotAreaId
    SpotType:
      type: string
      description: The type of the spot
      enum:
      - parking
      - docking
    SpotReserveEntityEnum:
      type: string
      description: The entity type for the reserve action
      enum:
      - YardTask
    UpdateSpotStatusDto:
      type: object
      properties:
        tags:
          type: object
        reason:
          type: string
        observation:
          type: string
      required:
      - reason
    UpdateSpotDto:
      type: object
      properties:
        tags:
          type: object
        code:
          type: string
        type:
          $ref: '#/components/schemas/SpotType'
        spotAreaId:
          type: string
          format: uuid
        observation:
          type: string
    SpotAssignment:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        spotId:
          type: string
          format: uuid
          description: The id of the spot
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        assetVisitId:
          type: object
          format: uuid
          description: The id of the asset visit
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        assetContainerId:
          type: object
          format: uuid
          description: The id of the asset container
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        observation:
          type: string
          description: Extra data for the spot assignment
          example: Spot assignment for truck 4
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - spotId
      - assetVisitId
      - assetContainerId
    SpotEventTypeEnum:
      type: string
      description: The type of the event
      enum:
      - assignment
      - release
      - reserve
      - release_reserve
      - close
      - open
      - other
    Spot:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        code:
          type: string
          description: The code of the spot
          example: SP001
        type:
          $ref: '#/components/schemas/SpotType'
        spotAreaId:
          type: string
          format: uuid
          description: The id of the spot area
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        observation:
          type: string
          description: The observation of the spot
          example: Large spot for trucks
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - code
      - type
      - spotAreaId
    SpotEvent:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        createDateTime:
          format: date-time
          type: string
          description: The date and time when the record was created
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        createdBy:
          type: object
          description: The ID of the user who created the record
          example: a0e1f2c3-d4e5-6f7g-8h9i-j0k1l2m3n4o5
          readOnly: true
        lastChangedDateTime:
          format: date-time
          type: string
          description: The date and time when the record was last changed
          example: '2023-10-01T12:00:00Z'
          readOnly: true
        spotId:
          type: string
          format: uuid
          description: The id of the spot
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        eventType:
          $ref: '#/components/schemas/SpotEventTypeEnum'
        reason:
          type: string
          description: The reason for the event
          example: Spot is occupied
        observation:
          type: string
          description: The observation of the event
          example: Spot is occupied by a truck
        assetContainerId:
          type: string
          description: The ID of the asset container associated with this event
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
        assetVisitId:
          type: string
          description: The ID of the asset visit associated with this event
          example: a0e4b1c2-3d4e-5f6g-7h8i-9j0k1l2m3n4o
      required:
      - id
      - createDateTime
      - createdBy
      - lastChangedDateTime
      - spotId
      - eventType
    ToggleSpotReserveDto:
      type: object
      properties:
        tags:
          type: object
        objectId:
          type: string
          format: uuid
        entityName:
          $ref: '#/components/schemas/SpotReserveEntityEnum'
        validUntil:
          type: string
          format: date-time
        observation:
          type: string
          maxLength: 1024
          description: Optional observation for the spot reserve action
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http