> ## 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.

> ## Agent Instructions
> For Bahn Customer API V2 integration work, start with /skill.md and /guides/agent-integration.md on this documentation site. Use /llms.txt to find the guides for the requested workflow.
> The main integration orders your company's transports from existing software. Follow the requested screen, service, or job. Omit ordered_for for own-account orders. Use the platform-ordering guide when ordering for represented businesses. Add a customer-facing interface only when requested.
> Use /openapi.yaml for paths, schemas, scopes, and operation preconditions. Use the guides for transport rules and recovery behavior. Load only the relevant pages.
> Use the sandbox for development and tests. Keep credentials on the server. Production orders start real transport work; follow the customer's authorized workflow and account context.
> For required writes, preserve write keys and request data across retries, and use current actions and quoted revisions for order changes. When consuming webhooks, verify and durably store them before acknowledgement.
> Deliver the implemented workflow with test evidence, setup steps, and remaining gaps. Distinguish simulated checks from requests actually verified against Bahn.

# Go live

> Verify the integration and switch to production deliberately.

A production order starts real transport work. Verify the workflow your system will run using sandbox credentials first. Apply the checks below to the capabilities you use.

## Verify the complete workflow

| Area | What to verify |
| - | - |
| Authentication | Cache tokens, renew before expiry, and recover from a `401` once. |
| Creation | Store the Bahn order ID, customer reference, revision, and accepted price. |
| Retries | Repeat a timed-out write with the same idempotency key and request data. |
| Changes, when used | Check `allowed_actions`, send a quoted revision, and handle a revision conflict. |
| Webhooks, when used | Verify raw-body signatures, store durably before acknowledgement, and deduplicate retries. |
| Current state | Read the latest resource when your workflow needs it. For webhooks, handle events that arrive out of order. |
| Timing | Keep requested, agreed, estimated, actual, and committed times distinct. |
| Optional features | Test every feature your system uses, including files, inspection states, and tracking gaps. |

Use [Sandbox testing](/guides/sandbox) to move orders through the transport flow. Test update and cancellation requests on separate test orders. For platform ordering, also test separation between represented businesses. A successful sandbox eligibility check does not prove production eligibility.

## Configure production

1. Open **Customer API** in the Bahn portal and create a credential with **Production** selected.
2. Store its client ID and secret in your production secret manager.
3. Set both the API and token host to `https://api.bahnexpress.fi`.
4. If you consume webhooks, create a production webhook endpoint and store its signing secret separately from the sandbox secret.
5. Request a production token and verify a read request before enabling order creation.

Keep environment configuration together so the token host, API host, credential, and webhook secret agree. A sandbox token cannot access production.

For platform ordering, ask Bahn support to configure the ordering channel and confirm each represented business before its first production order.

## Operate the integration

Store request IDs with write results. Monitor failed requests, exhausted retries, webhook verification failures, and webhook processing delays. The customer portal shows delivery attempts and lets you replay retained events to their original endpoint.

Cache file IDs rather than temporary download URLs. Refresh the file list when a URL expires. Poll tracking only while the map is visible.

Use the current `allowed_actions` to decide whether a production order can change or be cancelled. Confirm the customer's intent before cancellation.

Contact [Bahn support](mailto:support@bahnexpress.com) with the environment, order ID, request ID, and observed behavior when you need help. Keep credentials and signing secrets out of support messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.