Quickstart

Create and read one transport order for your own Bahn account. You need curl, jq, uuidgen, and a sandbox credential from Customer API in the Bahn portal. The request omits ordered_for because the transport belongs to your company. In your own system, link the returned Bahn order ID to the record that initiated the transport.

Keep the sandbox base URL in every command. The production URL creates real transport orders.

Set your sandbox credentials

Set the client ID and client secret from the portal. Generate one run ID for this tutorial. Keep it when retrying a request. Start again with a new run ID when creating another test order.

export BAHN_CLIENT_ID="your_sandbox_client_id"
export BAHN_CLIENT_SECRET="your_sandbox_client_secret"
export BAHN_QUICKSTART_RUN_ID=$(uuidgen)

Get an access token

Request a token and save it. The token is valid for 15 minutes.

TOKEN_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "https://sandbox.api.bahnexpress.fi/oauth2/token" \
  --user "$BAHN_CLIENT_ID:$BAHN_CLIENT_SECRET" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials")

export BAHN_ACCESS_TOKEN=$(printf "%s" "$TOKEN_RESPONSE" | jq -er ".access_token")

Create an order

Create one transport between two dealerships. Set available_from to a future time before you run the command.

ORDER_RESPONSE=$(curl --fail-with-body --silent --show-error \
  --request POST "https://sandbox.api.bahnexpress.fi/v2/orders" \
  --header "Authorization: Bearer $BAHN_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $BAHN_QUICKSTART_RUN_ID-order" \
  --data '{
    "customer_reference": "QUICKSTART-001",
    "pickup": {
      "address": {
        "formatted_address": "Teollisuuskatu 1, 00510 Helsinki, Finland",
        "country_code": "FI"
      },
      "type": "dealership",
      "available_from": "2099-08-03T08:00:00+03:00"
    },
    "delivery": {
      "address": {
        "formatted_address": "Hatanpään valtatie 24, 33100 Tampere, Finland",
        "country_code": "FI"
      },
      "type": "dealership"
    },
    "items": [{
      "role": "primary",
      "vin": "WBA00000000000001"
    }],
    "service_options": {
      "transport_preference": "flexible",
      "inspection": "standard"
    }
  }')

export BAHN_ORDER_ID=$(printf "%s" "$ORDER_RESPONSE" | jq -er ".id")
printf "Created %s\n" "$BAHN_ORDER_ID"

A successful response has the accepted status. Save the returned id for later requests.

Read the current order

Read the order with its Bahn order ID.

curl --fail-with-body --silent --show-error \
  "https://sandbox.api.bahnexpress.fi/v2/orders/$BAHN_ORDER_ID" \
  --header "Authorization: Bearer $BAHN_ACCESS_TOKEN" | jq '{id, status, allowed_actions}'

The response should contain your order ID, the accepted status, and the current allowed_actions.

Advance the test order

Confirm pickup readiness with the first sandbox scenario. This gives you a real state change to read and later test through webhooks.

curl --fail-with-body --silent --show-error \
  --request POST \
  "https://sandbox.api.bahnexpress.fi/v2/test/orders/$BAHN_ORDER_ID/advance" \
  --header "Authorization: Bearer $BAHN_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $BAHN_QUICKSTART_RUN_ID-readiness" \
  --data '{"scenario":"pickup_readiness_confirmed"}' \
  | jq '{scenario, pickup_readiness: .order.pickup_readiness}'

The response should show pickup_readiness_confirmed and the confirmed readiness value.

You have created, read, and advanced a sandbox order. Next, use Integration lifecycle to connect this flow to your own records and keep them current.

Get started

Create and manage orders

Follow the transport

Reliability and production

Platform ordering

Automation