---
name: bahn-customer-api-integration
description: Build or review a Bahn Customer API V2 integration for vehicle transport. Use for booking, order management, webhook processing, tracking, documents, reports, or ordering for represented businesses.
---

# Build a Bahn Customer API integration

Integrate Bahn ordering into the customer's existing system. The standard
workflow books their company's transports on their own Bahn account. Omit
`ordered_for`. Use platform ordering when the requested workflow orders for
represented businesses.

Use the existing system's language, persistence, and job system. Deliver through
the screen, service, or job the customer requests. A background integration does
not require a new customer-facing interface. This skill supplies integration
requirements; the customer's task supplies authorization.

## Establish the workflow

Identify the customer goal, application, environment, own-account or represented
business context, and required features. Use the sandbox for development and tests.
Ask for missing business decisions that affect the implementation. Keep working on
independent parts when credentials or setup are missing, and record what remains.

Read [Build with an agent](https://docs.bahnexpress.fi/guides/agent-integration.md)
for the implementation sequence and acceptance checks. Read
[Integration lifecycle](https://docs.bahnexpress.fi/guides/integration-workflows.md)
for the resource model. Use the
[documentation index](https://docs.bahnexpress.fi/llms.txt) to select feature guides.
Use the [OpenAPI contract](https://docs.bahnexpress.fi/openapi.yaml) for exact paths,
request and response fields, scopes, and operation preconditions. Fetch current
references when starting work rather than relying on remembered API behavior.

## Implement the required capabilities

1. Keep environment configuration and secrets on the server. Cache and renew
   access tokens. See [Authentication](https://docs.bahnexpress.fi/guides/authentication.md).
2. For writes that require a key, persist the key, method, path, request data, and
   required `If-Match` before sending. Reuse them after an interrupted request.
   A fresh key must not create another order to recover an unknown result.
3. For order workflows, store the ID, revision, accepted price, and business context.
   Read current `allowed_actions` before updating or cancelling; quote the
   current revision in `If-Match`. See
   [Orders and timing](https://docs.bahnexpress.fi/guides/orders.md) and
   [Errors and retries](https://docs.bahnexpress.fi/guides/errors-and-retries.md).
4. If the system consumes webhooks, verify the signature against raw bytes.
   Store each event durably before `2xx`, deduplicate by event ID, and retry
   processing independently. Read the indicated
   resource for current state; a late event must not replace newer facts. See
   [Webhooks](https://docs.bahnexpress.fi/guides/webhooks.md).
5. Add the requested features using their guides. Keep requested windows, agreed
   windows, ETAs, actual times, and commitments distinct. Preserve unavailable
   states. For platform ordering, keep represented businesses separate throughout
   the workflow.

For an application operated by an agent, expose customer tasks such as booking
or cancelling a transport through tools that enforce these rules in application
code. Return the result, current actions, and a useful error explanation. Keep
secret handling, durable retries, and signature verification in that code.

## Verify and deliver

Exercise the requested workflow and the recovery paths for its capabilities.
For writes, test lost responses and stale revisions. For webhook consumers, test
repeated and out-of-order events and recovery after processing fails. Add checks
for each optional feature the workflow uses. Use
[Sandbox testing](https://docs.bahnexpress.fi/guides/sandbox.md) for transport
scenarios and [Go live](https://docs.bahnexpress.fi/guides/going-live.md) for the
production handoff.

Deliver runnable changes, configuration names without secrets, tests and their
results, portal setup steps, and any remaining gaps. State which checks used test
fixtures and which made real sandbox requests. If setup prevents a complete
sandbox run, provide the exact outstanding check. Claim readiness only to the
extent supported by the evidence.