Einride ShipmentService API

openapi: 3.2.0
info:
  title: 'Einride Extend: Authentication AuthenticationService Shipment Service API'
  description: "Based on REST principles, with optional support for gRPC, the Einride Extend API enables modern API-based integration to Einride Saga.\n\nAPI design\n----------\n\nThe Einride Extend APIs are designed using the [AIP](https://aip.dev) design framework, which means that they are resource-oriented and work like standard [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\n\n### Resource-oriented design\n\n*See also: [AIP-121: Resource-oriented design](https://google.aip.dev/121)*\n\nThe fundamental building blocks of this API are individually-named resources (nouns) and the relationships and hierarchy that exist between them.\n\nA number of standard methods (verbs) provide the semantics for common [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations. Custom methods are available where custom operations are required, such as for cancelling shipments.\n\n### Resource names\n\n*See also: [AIP-122: Resource names](https://google.aip.dev/122)*\n\nThis API exposes resources which users are able to create, retrieve, and manipulate. Resources are named: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources.\n\nAs such, the unique identifier for a resource in this API is called a *resource name*.\n\nProtocols\n---------\n\nThe Einride Extend APIs support both HTTP and gRPC protocols.\n\n### HTTP\n\nThe Einride Extend APIs are available as RESTful HTTP endpoints.\n\nSee this document for the OpenAPI specifications, or use the API documentation at [extend.saga.einride.tech](https://extend.saga.einride.tech), where you can also try out the REST APIs and make example requests.\n\n### gRPC\n\n[gRPC](https://grpc.io) is a high performance, open source universal RPC framework that works across programming languages and platforms.\n\nTo for more information about using Einride Extend APIs via gRPC, please contact your Einride representative.\n\nAuthentication\n---------\n\nThe Einride Extend use standard [Bearer token authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). When using the HTTP APIs, make sure to always provide the following header in all requests:\n\n\n    Authorization: Bearer <token>\n\n\nWhere `<token>` is the authentication token for your integration. \n\n\nObtain a short-lived authentication token by using the ExchangeSecret API documented below. \n\n\nPlease contact your Einride representative to obtain a client ID and client secret for your integration. \n\nAPI address\n---------\n\nThe Einride Extend API is available via the following root address:\n\nhttps://api.saga.einride.tech\n"
  version: v1beta1
servers:
- url: https://api.saga.einride.tech/
tags:
- name: ShipmentService
paths:
  /v1beta1/{parent}/shipments:
    get:
      summary: List shipments in a space.
      description: This is an AIP standard [List](https://google.aip.dev/132) method.
      operationId: ShipmentService_ListShipments
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1ListShipmentsResponse'
        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 shipments.

          Format: spaces/{space}'
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+
      - name: pageSize
        description: 'Requested page size. Server may return fewer shipments 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 ListShipmentsResponse.page_token

          returned from the previous call to `ListShipments` 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 shipments 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:
      - ShipmentService
  /v1beta1/{shipment.name}:
    patch:
      summary: Update a shipment in a space.
      description: This is an AIP standard [Update](https://google.aip.dev/134) method.
      operationId: ShipmentService_UpdateShipment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Shipment'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: shipment.name
        description: The resource name of the shipment.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/shipments/[^/]+
      tags:
      - ShipmentService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                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
              title: The resource which replaces the current resource.
              required:
              - sender
              - deliveryAddress
              - units
              - shipment
        description: The resource which replaces the current resource.
        required: true
  /v1beta1/{shipment}:
    get:
      summary: Get a shipment.
      description: This is an AIP standard [Get](https://google.aip.dev/131) method.
      operationId: ShipmentService_GetShipment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Shipment'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: shipment
        description: The resource name of the shipment to retrieve.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/shipments/[^/]+
      tags:
      - ShipmentService
  /v1beta1/{shipment}:cancel:
    post:
      summary: Cancel a shipment.
      description: 'The state of the shipment after cancelling it is CANCELLED.


        This is an AIP [state](https://google.aip.dev/216) transition method.'
      operationId: ShipmentService_CancelShipment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Shipment'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: shipment
        description: The resource name of the shipment to cancel.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/shipments/[^/]+
      tags:
      - ShipmentService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentServiceCancelShipmentBody'
        required: true
  /v1beta1/{shipment}:release:
    post:
      summary: Release a shipment.
      description: 'The state of the shipment after releasing it is RELEASED.


        This is an AIP [state](https://google.aip.dev/216) transition method.'
      operationId: ShipmentService_ReleaseShipment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Shipment'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: shipment
        description: The resource name of the shipment to release.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+/shipments/[^/]+
      tags:
      - ShipmentService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentServiceReleaseShipmentBody'
        required: true
  /v1beta1/{space}/shipments:
    post:
      summary: Create a shipment in a space.
      description: This is an AIP standard [Create](https://google.aip.dev/133) method.
      operationId: ShipmentService_CreateShipment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1beta1Shipment'
        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 shipment.
        in: path
        required: true
        schema:
          type: string
          pattern: spaces/[^/]+
      tags:
      - ShipmentService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1beta1Shipment'
              required:
              - shipment
        description: The shipment to create.
        required: true
components:
  schemas:
    UnitLengthUnit:
      type: string
      enum:
      - CM
      - IN
      description: "- CM: Centimeters\n - IN: Inches"
      title: Length units
    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
    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
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/protobufAny'
    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
    v1beta1ListShipmentsResponse:
      type: object
      properties:
        shipments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/v1beta1Shipment'
          description: The list of shipments.
        nextPageToken:
          type: string
          description: 'A token to retrieve next page of results.  Pass this value in the ListShipmentsRequest.page_token field in the

            subsequent call to `ListShipments` method to retrieve the next page of results.'
        totalSize:
          type: integer
          format: int32
          description: The total size of shipments found in a space.
      description: Response message for ShipmentService.ListShipments.
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    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
    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
    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
    UnitWeightUnit:
      type: string
      enum:
      - KG
      - LBS
      description: "- KG: Kilograms\n - LBS: Pounds"
      title: Weight units
    ShipmentServiceCancelShipmentBody:
      type: object
      description: Request message for BookService.CancelShipment.
    ShipmentServiceReleaseShipmentBody:
      type: object
      description: Request message for BookService.ReleaseShipment.
    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
    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
    UnitVolumeUnit:
      type: string
      enum:
      - CBM
      - CBFT
      description: "- CBM: Cubic meters\n - CBFT: Cubic feet"
      title: Volume units
    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.'
    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
    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