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

# Integration lifecycle

> Design the order, webhook, and resource-read loop.

Build the integration around the order. Add tracking, files, inspection reports, and reports only when your product needs them.

## The core loop

```mermaid theme={null}
sequenceDiagram
    participant Product as Your product
    participant API as Bahn API
    Product->>API: POST /oauth2/token
    API-->>Product: Access token
    Product->>API: POST /v2/orders
    API-->>Product: Accepted order
    API-->>Product: Signed webhook
    Product->>API: GET data.resource_url
    API-->>Product: Current resource
```

A webhook tells you what changed. The resource tells you what is true now. This distinction matters when events arrive late, arrive more than once, or arrive in a different order.

## Store the right identifiers

After order creation, store these values together:

| Value                | Why you need it                                                                        |
| -------------------- | -------------------------------------------------------------------------------------- |
| `id`                 | Use the Bahn order ID in every resource path.                                          |
| `customer_reference` | Match the order to your own record. It can be `null` and is not required to be unique. |
| `revision`           | Protect order updates and cancellations from stale writes.                             |
| `allowed_actions`    | Decide which order actions your UI can offer.                                          |
| `ordered_for`        | Route and display orders created through a platform integration.                       |

Do not build a second version of the order lifecycle from webhook events. Store the data your product needs, then refresh it from the API after relevant events.

## Add only the capabilities your product uses

| Product requirement              | Recommended API flow                                                             |
| -------------------------------- | -------------------------------------------------------------------------------- |
| Show a price before confirmation | Check the price, then create the order.                                          |
| Place and manage orders          | Create the order, then read it when the UI opens or a webhook arrives.           |
| Show pickup and delivery timing  | Read the order and keep requested, agreed, estimated, and actual times separate. |
| Show a live map                  | Read tracking while the map is open and refresh with the ETag.                   |
| Build a document archive         | Read files after file, inspection, pickup, or delivery events.                   |
| Show a full inspection           | Read the inspection report when its status becomes available.                    |
| Export orders                    | Read report rows with cursor pagination.                                         |
| Order for another business       | Use a platform ordering credential and send `ordered_for`.                       |

## Make reads event-driven

Read an order when a user opens it. After that, use webhooks to decide when to refresh. For a customer-facing tracking page, poll the tracking resource every 30 to 60 seconds while the map is visible.

The event payload contains `data.resource_url`. Tracking, file, and inspection events point to their own resources. Order events point to the order. Use `data.related_resource_urls` when one change affects more than one resource.

## Keep writes deliberate

Create one idempotency key for one logical write. Reuse it only when you retry the same request body after a timeout or server error.

Before an update or cancellation, read the latest order. Check `allowed_actions`, then send the current `revision` in `If-Match`. If Bahn returns `revision_conflict`, read the order again and make a new decision.

Continue with [Orders and timing](./orders) for the order model, or [Webhooks](./webhooks) for the event-processing flow.