Loadsmart Bids API

openapi: 3.2.0
info:
  title: Loadsmart Bids API
  x-logo:
    altText: Loadsmart API
    url: https://developer.loadsmart.com/logo.svg
  description: "Loadsmart API provides endpoints to quote, book and track shipments autonomously.\n\n# Authentication\n\nLoadsmart API supports JWT tokens for authentication, signed using\npublic/private key pairs (RSA 4096).\n\n## What is JWT?\n\nJSON Web Token (JWT) is an [open standard](https://tools.ietf.org/html/rfc7519) used to\ncreate access tokens that contain some number of claims and is cryptographically signed by\nthe issuer, so its integrity can be verified without an auth server.\n\n## Token algorithm\n\nWe support JWT tokens signed using RS256 algorithm:\n\n```\n{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\"\n}\n```\n\n## Required Claims\n\nFor the token payload, we require at least the following claims:\n\n- `sub`: Identifies the subject of the API call. This could be\n  either `sys` (without any user or client context) or `usr:UUID`,\n  where `UUID` is the uuid of the user that will provide the\n  context for the API call.\n- `iss`: Identifies who issued the token. This will be provided by\n  Loadsmart when setting up the integration.\n- `iat`: Standard \"issued at\" claim; should be an unix timestamp.\n- `exp`: Standard \"expires at\" claim; should be an unix timestamp.\n  We recomend to keep the token as short-lived as possible - ideally\n  it should not be valid for more than 1 minute. In the future,\n  Loadsmart could reject tokens with high expiration times.\n\n## Using the token\n\nThe token must be present in the `Authorization` header on all\nrequests, following the format:\n\n```\nAuthorization: JWT <token>\n```\n\nEach part of the token is encoded in base64 and joined with a dot separating each encoded part -\nif you use a library to generate it (which is recommended), you don't need to worry about it.\n\n**Important: Authorization header value must have the prefix `JWT`**.\n\nSee an example:\n\n```\nAuthorization: JWT eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.TCYt5XsITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUcX16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtjPAYuNzVBAh4vGHSrQyHUdBBPM\n```\n\n## Available contexts\n\nEach token has an implicit context associated with it (usually depending on the value of `sub`\nclaim). This context identifies to the API if the entity doing an action is an user or a system.\n\nLoadsmart API has different token contexts depending on the endpoint being called. Each endpoint\nwill specify the supported contexts (and required scopes) in `AUTHORIZATIONS` section.\n\n<!-- ReDoc-Inject: <security-definitions> -->\n\n## API Access\n\nTo start using Loadsmart API, please get in touch through your\npoint of contact. They will direct you through the proper flow.\n\n### Creating a public/private key pair\n\nFor JWT tokens, you should provide your *public key*. To generate a\npublic and private key pair, you can use OpenSSL:\n\n```bash\n$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096\n$ openssl rsa -in private_key.pem -pubout -out public_key.pem\n```\n\n*Never* reuse keys between multiple systems.\n\nFor more information, checkout the [official JWT website](https://jwt.io/).\n"
  version: 1.0.0
servers:
- url: https://api.loadsmart.com
  description: Production server
- url: https://api.sandbox.loadsmart.com
  description: Sandbox environment
tags:
- name: Bids
  description: 'This API allows third parties to create, list, retrieve and accept bids.

    '
paths:
  /api/v2/load-offers/bids:
    get:
      summary: List Bids
      tags:
      - Bids
      security:
      - User-JWT:
        - load_offers_read
      parameters:
      - in: query
        name: status
        schema:
          type: string
          enum:
          - pending
          - awarded
          - accepted
          - timed_out
          - refused
        description: The status of the bid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: Number of objects found
                    type: number
                    format: integer
                  next:
                    description: URL for next page of results
                    type: string
                    format: url
                  previous:
                    description: URL for previous page of results
                    type: string
                    format: url
                  results:
                    type: array
                    items:
                      type: object
                      description: The bid properties
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Bid unique identifier (UUID)
                        offer_id:
                          type: string
                          format: uuid
                          description: Offer unique identifier (UUID)
                        price:
                          type: string
                          format: uuid
                          description: Bid price (USD).
                        created_at:
                          type: datetime
                          format: date-time
                          description: Bid creation datetime
                        expires_at:
                          type: datetime
                          format: date-time
                          description: The bid expiration datetime
                        expired_at:
                          type: datetime
                          format: date-time
                          description: The bid datetime that bid was expirated
                        status:
                          type: string
                          enum:
                          - pending
                          - awarded
                          - accepted
                          - timed_out
                          - refused
                          description: Bit status.
              example:
                count: 2
                next: null
                previous: null
                results:
                - id: 3b068fe4-99da-40e5-813a-d0a6de9fd558
                  offer_id: 1471e2b8-bb79-4210-a2d8-5171c4776a54
                  created_at: 2021-05-26 17:12:43.701000+00:00
                  expires_at: null
                  expired_at: null
                  price: 770.1
                  status: pending
                - id: 02df5646-be83-4383-ac76-b2d5557cf927
                  offer_id: 36241edf-545a-496a-a698-ca8fb6c21156
                  created_at: 2021-05-26 17:12:43.688000+00:00
                  expires_at: null
                  expired_at: null
                  price: 61.14
                  status: pending
        '400':
          description: Invalid parameters
        '401':
          description: Not authorized
    post:
      summary: Create Bid
      tags:
      - Bids
      security:
      - User-JWT:
        - load_offers_write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Create bid
              properties:
                offer_id:
                  type: string
                  format: uuid
                  description: Offer unique identifier (UUID).
                price:
                  type: string
                  description: Bid Price (USD)
            example:
              offer_id: 47aada86-6ef1-4516-a272-2881397daea9
              price: '809.96'
      responses:
        '201':
          description: Success
          content:
            application/json:
              example:
                id: 7593cbc8-53d0-4e54-87fd-a21f4b6dbb44
                offer_id: 47aada86-6ef1-4516-a272-2881397daea9
                created_at: 2021-05-26 13:43:55.727258+00:00
                expires_at: 2021-05-26 13:58:55.727258+00:00
                expired_at: null
                price: '809.96'
                status: pending
              schema:
                type: object
                description: The bid properties
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Bid unique identifier (UUID)
                  offer_id:
                    type: string
                    format: uuid
                    description: Offer unique identifier (UUID)
                  price:
                    type: string
                    format: uuid
                    description: Bid price (USD).
                  created_at:
                    type: datetime
                    format: date-time
                    description: Bid creation datetime
                  expires_at:
                    type: datetime
                    format: date-time
                    description: The bid expiration datetime
                  expired_at:
                    type: datetime
                    format: date-time
                    description: The bid datetime that bid was expirated
                  status:
                    type: string
                    enum:
                    - pending
                    - awarded
                    - accepted
                    - timed_out
                    - refused
                    description: Bit status.
        '400':
          description: Invalid parameters
        '401':
          description: Not authorized
        '403':
          description: Forbidden
        '404':
          description: Offer doesn't exists or expired
        '410':
          description: Offer is no longer available
        '422':
          description: Could not create the bid with the given data due to one of - ["The carrier is not eligible for this offer", "This offer is unbiddable", "Invalid Price"]
  /api/v2/load-offers/bids/{bid_id}:
    get:
      summary: Retrieve Bid
      tags:
      - Bids
      security:
      - User-JWT:
        - load_offers_read
      parameters:
      - in: path
        name: bid_id
        schema:
          description: Bid unique identifier (UUID)
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The bid properties
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Bid unique identifier (UUID)
                  offer_id:
                    type: string
                    format: uuid
                    description: Offer unique identifier (UUID)
                  price:
                    type: string
                    format: uuid
                    description: Bid price (USD).
                  created_at:
                    type: datetime
                    format: date-time
                    description: Bid creation datetime
                  expires_at:
                    type: datetime
                    format: date-time
                    description: The bid expiration datetime
                  expired_at:
                    type: datetime
                    format: date-time
                    description: The bid datetime that bid was expirated
                  status:
                    type: string
                    enum:
                    - pending
                    - awarded
                    - accepted
                    - timed_out
                    - refused
                    description: Bit status.
              example:
                id: 7593cbc8-53d0-4e54-87fd-a21f4b6dbb44
                offer_id: 47aada86-6ef1-4516-a272-2881397daea9
                created_at: 2021-05-26 13:43:55.727258+00:00
                expires_at: 2021-05-26 13:58:55.727258+00:00
                expired_at: null
                price: '809.96'
                status: pending
        '401':
          description: Not authorized
        '403':
          description: Bid is not linked to external outlet
        '404':
          description: Offer doesn't exists
  /api/v2/load-offers/bids/{bid_id}/accept:
    post:
      summary: Accept Bid
      tags:
      - Bids
      security:
      - User-JWT:
        - load_offers_write
      parameters:
      - in: path
        name: bid_id
        schema:
          description: Bid unique identifier (UUID)
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Load unique identifier (UUID)
              example:
                id: 7593cbc8-53d0-4e54-87fd-a21f4b6dbb44
        '400':
          description: Invalid parameters
        '401':
          description: Not authorized
        '403':
          description: Forbidden
        '404':
          description: Offer doesn't exists
        '409':
          description: Cant accept bid with invalid status
components:
  securitySchemes:
    Application-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with the application context (preferred\nfor the endpoints that support it):\n\n```\n{\n  \"sub\": \"sys\",\n  \"iss\": \"token-issuer\",\n  \"exp\": 1626239022,\n  \"iat\": 1517239022\n}\n```\n"
    User-JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Authorize the request with an user context. A payload example\nwould be:\n\n```\n{\n  \"sub\": \"usr:87127882-d1db-4e50-8f7c-c792a80d7c49\",\n  \"iss\": \"token-issuer\",\n  \"iat\": 1517239022,\n  \"exp\": 1626239022\n}\n```\n"