Quickstart

This guide takes you from a client credential to a working sandbox order. You need curl, jq, and a sandbox credential from the Bahn customer portal.

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.

export BAHN_CLIENT_ID="your_sandbox_client_id"
export BAHN_CLIENT_SECRET="your_sandbox_client_secret"

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 from a dealership to an end customer. 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: quickstart-order-001" \
  --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: quickstart-readiness-001" \
  --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 now have a working order and the credentials needed for the rest of the sandbox. Next, read Integration lifecycle to design the complete flow.

Get started

Core integration

Customer features

Platform integrations

Test and automate