> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bahnexpress.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create and verify your first sandbox order.

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.

<Warning>
  Keep the sandbox base URL in every command. The production URL creates real transport orders.
</Warning>

<Steps>
  <Step title="Set your sandbox credentials">
    Set the client ID and client secret from the portal.

    ```bash theme={null}
    export BAHN_CLIENT_ID="your_sandbox_client_id"
    export BAHN_CLIENT_SECRET="your_sandbox_client_secret"
    ```
  </Step>

  <Step title="Get an access token">
    Request a token and save it. The token is valid for 15 minutes.

    ```bash theme={null}
    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")
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="Read the current order">
    Read the order with its Bahn order ID.

    ```bash theme={null}
    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`.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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.
  </Step>
</Steps>

You now have a working order and the credentials needed for the rest of the sandbox. Next, read [Integration lifecycle](./guides/integration-workflows) to design the complete flow.