Einride BookingService API

openapi: 3.2.0
info:
  title: 'Einride Extend: Shipment Booking Service API'
  description: Based on REST principles, with optional support for gRPC, the Einride Extend Shipment API enables modern API-based integration to Einride Saga for transport booking.
  version: v1beta1
security:
- Authorization: []
tags:
- name: BookingService
paths:
  /v1beta1/{parent}/tours:
    get:
      summary: List existing truck tours
      description: This is an AIP standard List method.
      operationId: BookingService_ListTours
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListToursResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: parent
        description: 'The resource name of the parent, which owns this collection of tours.

          Format: spaces/{space}'
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+
      - name: pageSize
        description: 'Requested page size. Server may return fewer tours than requested.

          If unspecified, server will pick an appropriate default.'
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageToken
        description: 'A token identifying a page of results the server should return.

          Typically, this is the value of ListToursResponse.page_token returned from the previous call to `ListTours` method.'
        in: query
        required: false
        schema:
          type: string
      - name: orderBy
        description: 'How the results should be sorted. Presently, the only permitted values are:


          - `"create_time desc"` (default if no order_by is specified)

          - `"create_time asc"`

          Example:

          ```

          order_by = "create_time desc"

          ``'
        in: query
        required: false
        schema:
          type: string
      - name: showDeleted
        description: Controls whether deleted tours should be returned. Defaults to false.
        in: query
        required: false
        schema:
          type: boolean
      - name: skip
        description: Allows to skip results.
        in: query
        required: false
        schema:
          type: integer
          format: int32
      tags:
      - BookingService
  /v1beta1/{parent}/tours:search:
    get:
      summary: Search tours
      description: 'Search for Tours in a space.

        - You can search for Tours by external_reference_id'
      operationId: BookingService_SearchTours
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1SearchToursResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: parent
        description: 'The resource name of the parent, which owns this collection of tours.

          Format: spaces/{space}'
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+
      - name: pageSize
        description: 'Requested page size. Server may return fewer tours than requested.

          If unspecified, server will pick an appropriate default.'
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: pageToken
        description: 'A token identifying a page of results the server should return.

          Typically, this is the value of

          [SearchToursResponse.page_token][einride.saga.book.v1.SearchToursResponse.page_token]

          returned from the previous call to `SearchTours` method.'
        in: query
        required: false
        schema:
          type: string
      - name: skip
        description: Allows for skipping result
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: query
        description: 'Filters

          Multiple filters will be combined with the logical operator AND.


          Returned tours contain the query string in ANY of the fields:

          tour_id, external_reference_id'
        in: query
        required: false
        schema:
          type: string
      - name: showDeleted
        description: Includes deleted tours in result
        in: query
        required: false
        schema:
          type: boolean
      - name: orderBy
        description: 'How the results should be sorted. Presently, the only permitted values are:


          - `"create_time asc"` (default if no order_by is specified)

          - `"create_time desc"`

          Example:

          ```

          order_by = "create_time desc"

          ```'
        in: query
        required: false
        schema:
          type: string
      tags:
      - BookingService
  /v1beta1/{space}/tours:
    post:
      summary: Create a truck tour booking in a space
      description: This is an AIP standard Create method.
      operationId: BookingService_CreateTour
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Tour'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: space
        description: The parent space in which to create the tour.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+
      tags:
      - BookingService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1Tour'
              required:
              - tour
        description: The tour to create.
        required: true
  /v1beta1/{tour.name}:
    patch:
      summary: Update a tour
      description: 'See: https://google.aip.dev/134 (Standard methods: Update).

        If the tour has been confirmed, only a selection of fields can be updated: Stops.RequestedStartTime, Stops.RequestedEndTime, Annotations, PreliminaryShipments.Annotations.'
      operationId: BookingService_UpdateTour
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Tour'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: tour.name
        description: The resource name of the tour.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/tours/[^/]+
      tags:
      - BookingService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                space:
                  type: string
                  description: Resource name of the space that owns the tour.
                  readOnly: true
                sender:
                  type: string
                  description: Resource name of the sender of the tour.
                createTime:
                  type: string
                  format: date-time
                  description: The creation timestamp of the tour.
                  readOnly: true
                updateTime:
                  type: string
                  format: date-time
                  description: 'The last update timestamp of the tour.

                    Updated when create/update/delete operation is performed.'
                  readOnly: true
                deleteTime:
                  type: string
                  format: date-time
                  description: The deletion timestamp of the tour. This is set if the tour is deleted.
                  readOnly: true
                state:
                  $ref: '#/components/schemas/v1beta1TourState'
                  description: 'The state of the tour. Set to PENDING upon creation.

                    A tour is then either accepted or rejected.'
                  readOnly: true
                type:
                  $ref: '#/components/schemas/TourTourType'
                  description: The type of tour, either PROVISIONAL or CONFIRMED. Defaults to PROVISIONAL.
                serviceType:
                  $ref: '#/components/schemas/TourServiceType'
                  description: The type of service to create a tour for.
                externalReferenceId:
                  type: string
                  description: External reference ID is a unique identifier that can be set by the client.
                automationRule:
                  $ref: '#/components/schemas/TourAutomationRule'
                  description: The rule that is applied when a confirmed tour is accepted. Defaults to CREATE_SHIPMENTS.
                preliminaryShipments:
                  type: array
                  items:
                    type: object
                    $ref: '#/components/schemas/TourPreliminaryShipment'
                  description: 'The preliminary shipments included in this tour.

                    A preliminary shipment includes input about the specific shipments for a tour, including units and references.'
                stops:
                  type: array
                  items:
                    type: object
                    $ref: '#/components/schemas/TourStop'
                  description: The ordered list of stops included in this tour.
                createdShipments:
                  type: array
                  items:
                    type: object
                    $ref: '#/components/schemas/v1beta1Shipment'
                  description: The shipments that are associated with the tour. These are created when a tour is CONFIRMED and ACCEPTED.
                  readOnly: true
                annotations:
                  type: object
                  additionalProperties:
                    type: string
                  description: Supplementary annotation metadata for the tour, e.g. customer internal references.
              title: The resource which replaces the current resource.
              required:
              - sender
              - serviceType
              - preliminaryShipments
              - stops
              - tour
        description: The resource which replaces the current resource.
        required: true
  /v1beta1/{tour}:
    get:
      summary: Get an existing truck tour booking
      description: This is an AIP standard Get method.
      operationId: BookingService_GetTour
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Tour'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: tour
        description: The resource name of the tour to retrieve.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/tours/[^/]+
      tags:
      - BookingService
  /v1beta1/{tour}:cancel:
    get:
      summary: Cancel a tour
      operationId: BookingService_CancelTour
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Tour'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: tour
        description: The resource name of the tour to cancel.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/tours/[^/]+
      tags:
      - BookingService
  /v1beta1/{tour}:confirm:
    get:
      summary: Confirm a Provisional tour
      description: 'Reconfirming a tour that is already confirmed will return an InvalidArgument Error.

        When a tour has been accepted by Saga and confirmed by the user, Shipments will be created.'
      operationId: BookingService_ConfirmTour
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Tour'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: tour
        description: The resource name of the tour to confirm.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/tours/[^/]+
      tags:
      - BookingService
components:
  schemas:
    ShipmentDeliveryState:
      type: string
      enum:
      - AWAITING
      - IN_TRANSIT
      - DELIVERED
      description: "- AWAITING: Shipment delivery hasn't started\n - IN_TRANSIT: Shipment is in transit\n - DELIVERED: Shipment is delivered"
      title: Shipment delivery state
    UnitVolumeUnit:
      type: string
      enum:
      - CBM
      - CBFT
      description: "- CBM: Cubic meters\n - CBFT: Cubic feet"
      title: Volume units
    UnitVolume:
      type: object
      properties:
        value:
          type: number
          format: double
          title: Volume value
        unit:
          $ref: '#/components/schemas/UnitVolumeUnit'
          title: Volume unit
      title: Volume specified in different units
      required:
      - value
      - unit
    bookv1beta1Unit:
      type: object
      properties:
        type:
          type: string
          title: Type of unit
        externalReferenceId:
          type: string
          title: External reference ID of the unit
        description:
          type: string
          title: Description of the unit
        trackingId:
          type: string
          title: Unique unit tracking ID
          readOnly: true
        weight:
          $ref: '#/components/schemas/UnitWeight'
          title: Unit weight
        length:
          $ref: '#/components/schemas/UnitLength'
          title: Unit length
        height:
          $ref: '#/components/schemas/UnitLength'
          title: Unit height
        width:
          $ref: '#/components/schemas/UnitLength'
          title: Unit width
        volume:
          $ref: '#/components/schemas/UnitVolume'
          title: Unit volume
      description: A unit is a holder of goods such as a EUR-pallet.
      required:
      - type
      - weight
    TourStopType:
      type: string
      enum:
      - PICKUP
      - DELIVER
      description: "Type describes the reason for the stop. E.g. a stop to deliver or pickup.\n\n - PICKUP: Stop to pick up goods.\n - DELIVER: Stop to deliver goods."
    ShipmentService:
      type: string
      enum:
      - PALLET
      - FTL
      - DRAYAGE
      description: "- PALLET: Pallet\n - FTL: Full truck load\n - DRAYAGE: Drayage is the transport of goods over a short distance also known as the \"The first mile.\""
      title: Shipment service type
    v1beta1Tour:
      type: object
      properties:
        name:
          type: string
          description: The resource name of the tour.
        space:
          type: string
          description: Resource name of the space that owns the tour.
          readOnly: true
        sender:
          type: string
          description: Resource name of the sender of the tour.
        createTime:
          type: string
          format: date-time
          description: The creation timestamp of the tour.
          readOnly: true
        updateTime:
          type: string
          format: date-time
          description: 'The last update timestamp of the tour.

            Updated when create/update/delete operation is performed.'
          readOnly: true
        deleteTime:
          type: string
          format: date-time
          description: The deletion timestamp of the tour. This is set if the tour is deleted.
          readOnly: true
        state:
          $ref: '#/components/schemas/v1beta1TourState'
          description: 'The state of the tour. Set to PENDING upon creation.

            A tour is then either accepted or rejected.'
          readOnly: true
        type:
          $ref: '#/components/schemas/TourTourType'
          description: The type of tour, either PROVISIONAL or CONFIRMED. Defaults to PROVISIONAL.
        serviceType:
          $ref: '#/components/schemas/TourServiceType'
          description: The type of service to create a tour for.
        externalReferenceId:
          type: string
          description: External reference ID is a unique identifier that can be set by the client.
        automationRule:
          $ref: '#/components/schemas/TourAutomationRule'
          description: The rule that is applied when a confirmed tour is accepted. Defaults to CREATE_SHIPMENTS.
        preliminaryShipments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/TourPreliminaryShipment'
          description: 'The preliminary shipments included in this tour.

            A preliminary shipment includes input about the specific shipments for a tour, including units and references.'
        stops:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/TourStop'
          description: The ordered list of stops included in this tour.
        createdShipments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/v1beta1Shipment'
          description: The shipments that are associated with the tour. These are created when a tour is CONFIRMED and ACCEPTED.
          readOnly: true
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Supplementary annotation metadata for the tour, e.g. customer internal references.
      description: 'A Tour is a preplanned definition of what groups of goods are to be picked up and delivered, where, at what times, and in what order.

        When a tour is accepted and confirmed by Saga, Shipments based on the data provided in the Tour will be created.'
      required:
      - sender
      - serviceType
      - preliminaryShipments
      - stops
    UnitLengthUnit:
      type: string
      enum:
      - CM
      - IN
      description: "- CM: Centimeters\n - IN: Inches"
      title: Length units
    v1beta1TourState:
      type: string
      enum:
      - PENDING
      - ACCEPTED
      - REJECTED
      - CANCELLED
      description: "The state of the tour.\n\n - PENDING: The tour is received. Awaiting accept/reject.\n - ACCEPTED: The tour is accepted.\n - REJECTED: The tour is rejected.\n - CANCELLED: The tour is cancelled."
    UnitLength:
      type: object
      properties:
        value:
          type: number
          format: double
          title: Length value
        unit:
          $ref: '#/components/schemas/UnitLengthUnit'
          title: Length unit
      title: Length specified in different units
      required:
      - value
      - unit
    v1beta1ShipmentState:
      type: string
      enum:
      - ACTIVE
      - RELEASED
      - CANCELLED
      description: "- ACTIVE: Shipment is active (initial state).\n - RELEASED: Shipment is ready for pickup.\n - CANCELLED: Shipment is cancelled"
      title: Shipment state
    TourStop:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/v1beta1Address'
          description: The address of this stop.
        stopType:
          $ref: '#/components/schemas/TourStopType'
          description: The type of stop.
        instructions:
          type: string
          description: Instructions for this stop.
        contactPerson:
          type: string
          description: The contact person for this stop.
        requestedStartTime:
          type: string
          format: date-time
          description: The earliest time to arrive this stop.
        requestedEndTime:
          type: string
          format: date-time
          description: The latest time to depart this stop.
        shipmentExternalReferenceIds:
          type: array
          items:
            type: string
          description: 'The shipment external reference ids associated with this stop. E.g. for a pickup stop this will hold the shipments to pickup.

            The external_reference_ids are defined in preliminary_shipments.'
      description: A stop is an address where an event is going to happen. The event is either to pickup or deliver goods.
      required:
      - address
      - stopType
      - requestedStartTime
      - requestedEndTime
      - shipmentExternalReferenceIds
    UnitWeight:
      type: object
      properties:
        value:
          type: number
          format: double
          title: Weight value
        unit:
          $ref: '#/components/schemas/UnitWeightUnit'
          title: Weight unit
      title: Weight specified in different units
      required:
      - value
      - unit
    TourServiceType:
      type: string
      enum:
      - FULL_TRUCK_LOAD
      - DISTRIBUTION
      - SHUTTLE
      - MILK_RUN
      - DRAYAGE
      description: "The service type of the tour.\n\n - FULL_TRUCK_LOAD: Service type FTL.\n - DISTRIBUTION: Service type distribution.\n - SHUTTLE: Service type shuttle.\n - MILK_RUN: Service type milk run.\n - DRAYAGE: Service type drayage."
    TourAutomationRule:
      type: string
      enum:
      - CREATE_SHIPMENTS
      - CREATE_AND_RELEASE_SHIPMENTS
      description: "The rule that is applied when a confirmed tour is accepted.\n\n - CREATE_SHIPMENTS: When the confirmed tour is accepted, shipments will be created automatically from its stops and units.\n - CREATE_AND_RELEASE_SHIPMENTS: When the confirmed tour is accepted, shipments will be created automatically from its stops and units\nand then released."
    v1beta1Vehicle:
      type: object
      properties:
        referenceId:
          type: string
          title: Reference id
        driverReferenceId:
          type: string
          title: Driver reference id
        carrierReferenceId:
          type: string
          title: Carrier reference id
      title: Holds vehicle information
      required:
      - referenceId
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/protobufAny'
    UnitWeightUnit:
      type: string
      enum:
      - KG
      - LBS
      description: "- KG: Kilograms\n - LBS: Pounds"
      title: Weight units
    v1beta1Shipment:
      type: object
      properties:
        name:
          type: string
          description: The resource name of the shipment.
        space:
          type: string
          description: Resource name of the space that owns the shipment.
          readOnly: true
        sender:
          type: string
          description: Resource name of the sender of the shipment.
        createTime:
          type: string
          format: date-time
          description: The creation timestamp of the shipment.
          readOnly: true
        updateTime:
          type: string
          format: date-time
          description: 'The last update timestamp of the shipment.

            Updated when create/update/delete operation is performed.'
          readOnly: true
        deleteTime:
          type: string
          format: date-time
          description: The deletion timestamp of the shipment. Set if the shipment is deleted.
          readOnly: true
        trackingId:
          type: string
          description: A generated tracking ID for this shipment.
          readOnly: true
        pickupAddress:
          $ref: '#/components/schemas/v1beta1Address'
          description: 'The address where the shipment is picked up.

            Supply when creating shipment if different from the sender default pickup address.'
        pickupInstructions:
          type: string
          description: Instructions for the pickup.
        requestedPickupStartTime:
          type: string
          format: date-time
          title: The shipment should be picked up after this time
        requestedPickupEndTime:
          type: string
          format: date-time
          title: The shipment should be picked up before this time
        deliveryAddress:
          $ref: '#/components/schemas/v1beta1Address'
          description: The address where the shipment is delivered to.
        deliveryInstructions:
          type: string
          description: Instructions for the delivery.
        requestedDeliveryStartTime:
          type: string
          format: date-time
          title: The shipment should be delivered after this time
        requestedDeliveryEndTime:
          type: string
          format: date-time
          title: The shipment should be delivered before this time
        units:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/bookv1beta1Unit'
          title: Shipment units
        externalReferenceId:
          type: string
          description: An external reference for this shipment. If supplied then it must be unique within the space.
        tour:
          type: string
          description: Resource name of the truck tour booking this shipment relates to.
        state:
          $ref: '#/components/schemas/v1beta1ShipmentState'
          description: 'Shipment state

            Can be set to ACTIVE (default) or RELEASED when creating a shipment.

            Disabled as existing API allows setting.'
        deliveryState:
          $ref: '#/components/schemas/ShipmentDeliveryState'
          title: Shipment delivery state
          readOnly: true
        vehicle:
          $ref: '#/components/schemas/v1beta1Vehicle'
          title: Vehicle information for the shipment
        annotations:
          type: object
          additionalProperties:
            type: string
          title: Annotations for the shipment
        service:
          $ref: '#/components/schemas/ShipmentService'
          title: Shipment service, defaults to PALLET
      description: A shipment represents a demand to deliver goods from an origin to a destination.
      required:
      - sender
      - deliveryAddress
      - units
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    typeLatLng:
      type: object
      properties:
        latitude:
          type: number
          format: double
          description: The latitude in degrees. It must be in the range [-90.0, +90.0].
        longitude:
          type: number
          format: double
          description: The longitude in degrees. It must be in the range [-180.0, +180.0].
      description: 'An object that represents a latitude/longitude pair. This is expressed as a

        pair of doubles to represent degrees latitude and degrees longitude. Unless

        specified otherwise, this must conform to the

        <a href="http://www.unoosa.org/pdf/icg/2012/template/WGS_84.pdf">WGS84

        standard</a>. Values must be within normalized ranges.'
    v1beta1ListToursResponse:
      type: object
      properties:
        tours:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/v1beta1Tour'
          description: The list of tours. If there are none in the current page then this will be empty.
        nextPageToken:
          type: string
          description: 'A token to retrieve next page of results.  Pass this value in the ListToursRequest.page_token field in the

            subsequent call to `ListTours` method to retrieve the next page of results.'
        totalSize:
          type: integer
          format: int32
          description: The total size of tours found in a space.
      description: Response message for TourService.ListTours.
    TourPreliminaryShipment:
      type: object
      properties:
        externalReferenceId:
          type: string
          description: A customer provided external reference id.
        units:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/bookv1beta1Unit'
          description: The units that should be shipped.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Annotations for the shipment.
      description: Customer provided information about a shipment associated with a tour that will be added to the created shipments.
      required:
      - externalReferenceId
      - units
    TourTourType:
      type: string
      enum:
      - PROVISIONAL
      - CONFIRMED
      description: "The tour type.\n\n - PROVISIONAL: The tour is provisional and can be updated.\n - CONFIRMED: The tour is confirmed and can not be updated."
    v1beta1Address:
      type: object
      properties:
        recipient:
          type: string
          title: Recipient
        co:
          type: string
          title: Care of (C/O)
        line1:
          type: string
          title: Address line 1
        line2:
          type: string
          title: Address line 2
        postalCode:
          type: string
          title: Postal code
        city:
          type: string
          title: City
        regionCode:
          type: string
          title: 'Region code (Unicode CLDR region code)

            https://cldr.unicode.org/'
        stateCode:
          type: string
          title: State code
        displayName:
          type: string
          title: The displayed name of the address
        contactInfo:
          type: string
          title: Contact information
        latLng:
          $ref: '#/components/schemas/typeLatLng'
          title: The geographic location of the address
        externalReferenceId:
          type: string
          description: An external reference for this address.
      description: An Address is where goods are picked up or delivered.
      required:
      - recipient
      - line1
      - postalCode
      - city
      - regionCode
    v1beta1SearchToursResponse:
      type: object
      properties:
        tours:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/v1beta1Tour'
          description: The list of tours.
        nextPageToken:
          type: string
          description: 'A token to retrieve next page of results. Pass this value in the

            SearchToursRequest.page_token field in the subsequent call to `SearchTours` method

            to retrieve the next page of results.'
        totalSize:
          type: integer
          format: int32
          description: The total size of tours found using the search filters.
      description: Response message for TourService.SearchTours.
  securitySchemes:
    Authorization:
      type: apiKey
      name: authorization
      in: header