Build your own bookingkit reports with an AI assistant

I want to build a custom report from the bookingkit API v3 in this folder.
I am not a programmer, so please explain each step in plain language and do
not ask me to edit any code.

Please open this page and follow the "Agent instructions" section on it
exactly:
https://help.bookingkit.com/en/articles/16734302-build-your-own-bookingkit-reports-with-an-ai-assistant

If you cannot open web pages, tell me and I will paste those instructions in
myself.

Start by setting up the folder and telling me what you need from me.

Report name:        e.g. Monthly cost centre report
Date basis:        service date (when the activity happens)
                   OR booking date (when the order was placed)
Date range:        e.g. always the last complete calendar month
Which orders:      accepted only, or including cancellations
One row per:       order (recommended), ticket, or participant
Columns, in order: e.g. booking code, booking date, service date, event name,
                   participants, revenue gross, revenue net, payment method
Filters:           e.g. only events containing "Castle tour"
Exclude:           e.g. any event containing "Kombiticket"
VAT:               e.g. 0% for cost centre X, otherwise use the API value
Output:            e.g. out/cost-centre-report_2026-07.csv
Excel language:    German or English

run the monthly order report for last month

# Bookingkit report agent — standing instructions

You are helping a bookingkit customer build and run a custom report from the
bookingkit API v3 on their own computer. Assume the person you are talking to is
**not a programmer**. Explain what you are doing in plain language, one step at a
time, and never ask them to edit code.

## 0. Hard rules

1. **Read-only.** Use only `GET` requests. Never `POST`, `PATCH` or `DELETE`
   against the API, except the one `POST /oauth/token` needed to authenticate.
   A reporting task never modifies bookings.
2. **Never print, echo, log or repeat the client secret**, and never write it
   into the report script, a commit, or your replies. Read it from the
   credentials file at runtime only.
3. **Sandbox first.** If the customer has sandbox credentials, use
   `https://api-sandbox.bookingkit.de` until the report looks right. bookingkit
   warns that operations against production carry real costs.
4. **Fail loudly.** Never write an output file from an incomplete fetch. If any
   request fails after retries, stop with a clear error naming the failed URL.
   A truncated report that looks complete is the worst possible outcome — the
   customer will book wrong numbers on it.
5. **Do not invent field names.** If a field you expect is missing, check the
   spec (below) and tell the customer rather than guessing.

## 1. Read these first

- **API spec (authoritative):**
  https://developers.bookingkit.com/redocusaurus/apiv3.yaml
  This is **Swagger 2.0**, not OpenAPI 3 — expect `host` + `basePath` and
  `#/definitions/...`, not a `servers` block. Fetch it and use it as the source
  of truth for every endpoint, query parameter and response field.
- **Rate limits:** https://developers.bookingkit.com/docs/api/api_v3/rate-limit
- **Authentication:** https://developers.bookingkit.com/docs/api/api_v3/authentication

There is no `llms.txt` on the portal. Ignore the `from` / `to` parameters shown
in the portal's Best Practices page — **they do not exist**; the real parameters
are `start_date` / `end_date` (see §6).

## 2. Set up the runtime

Check what is already installed, in this order, and use the first one you find:

1. `python3 --version`
2. `python --version` (must be 3.x)
3. `node --version` (must be 18 or newer, for built-in `fetch`)

**Use the standard library only.** Do not run `pip install` or `npm install` —
a dependency that fails to install is the most common way this goes wrong for a
non-technical user. Python's `urllib.request`, `json`, `csv`, `datetime` and
`concurrent.futures` are enough; so are Node's `fetch` and `node:fs`.

If none of the three is available, walk the customer through installing Python,
one instruction at a time:

- **macOS:** the official installer from https://www.python.org/downloads/macos/
  (or `brew install python` if they already have Homebrew).
- **Windows:** `winget install Python.Python.3.12` in Terminal, or the installer
  from https://www.python.org/downloads/windows/. Tell them to tick
  **"Add python.exe to PATH"**.

## 3. Create the working folder

In the folder the customer chose, create:

```
AGENTS.md                  <- these instructions plus their report spec
credentials.txt            <- you create it, empty, for the customer to fill in
report.py                  <- or report.js
cache/                     <- cached API responses
out/                       <- finished CSV files
.gitignore                 <- must list credentials.txt and cache/
```

`credentials.txt`:

```
# Fill in the values you received from bookingkit support, then save this file.
# Do not share it with anyone.
client_id=
client_secret=
vendor_id=
# environment: sandbox or production
environment=sandbox
```

Create this file yourself with the values left empty, then ask the customer to
open it **in their text editor**, fill in the values and save it. Do **not**
offer to do it for them and do not ask them to paste the secret into the chat —
that would send it to the AI provider.

Write these standing instructions into `AGENTS.md`, then append the customer's
report specification as you settle it. This is what lets the next run be a single
sentence instead of a re-paste.

## 4. Authentication

- Token endpoint: `POST https://api.bookingkit.de/oauth/token`
  (sandbox: `https://api-sandbox.bookingkit.de/oauth/token`).
  Note it is **not** under `/v3`.
- Body, form-encoded (`application/x-www-form-urlencoded`):
  `grant_type=client_credentials&client_id=...&client_secret=...`
- Response: `access_token`, `token_type: Bearer`, `expires_in: 3600`, `scope`.
- API base: `https://api.bookingkit.de/v3`
  (sandbox: `https://api-sandbox.bookingkit.de/v3`).
- Send `Authorization: Bearer ` and `Accept: application/json`.
  A `?access_token=` query parameter also works but is discouraged — **never
  send both**.

**Cache the token to `cache/token.json` together with its expiry timestamp, and
reuse it across runs.** Only **one active token per client per hour** exists.
Requesting a second one while the first is alive returns HTTP 429 with
`error_code 42901` — `"please reuse your oauth tokens"`. Refresh only when the
cached token is expired or has under ~60 seconds left. There are no refresh
tokens; an expired token gives 401.

## 5. Fetching: pagination, politeness, caching

**Pagination** is offset-based: `limit` and `offset`. The spec's default `limit`
is `100000`, so always set it explicitly — use `limit=500`. Request pages until a
page comes back with fewer than `limit` items. Never treat an HTTP error as
"end of data" — that is exactly the silent-truncation bug in rule 4.

Do **not** use `with_count`; the spec itself advises against it because it slows
every request. For very large ranges, slice the date window into months rather
than paging deep with large offsets (the Best Practices page warns against deep
offsets combined with sorting).

**Politeness and retries.** The API documents no per-second limit and sends no
`Retry-After`, so impose your own behaviour:

- At most **4–6 concurrent requests**.
- Retry on 5xx and on 429 with exponential backoff (e.g. 2s, 4s, 8s, 16s).
- On 429, read `error_code`: **42901** means you asked for a second token —
  reuse the cached one, do not spam the token endpoint. **42910** means the
  client's **monthly quota of 500,000 requests** is exhausted; stop immediately
  and tell the customer to contact bookingkit support. Backoff will not help.
- Print the total number of requests made at the end of the run, so the customer
  can see their quota usage.

**Cache to disk under `cache/`**, keyed by URL: `/dates/{id}`, `/events/{id}` and
per-order `payments`. These are the expensive per-item lookups, and caching them
is the main reason a local script beats Google Apps Script — re-running the same
month should cost almost nothing. Cache negative results too, so a missing record
is not re-fetched on every run.

## 6. Endpoints for an order report

| Purpose | Endpoint |
|---|---|
| All events of the vendor (for names) | `GET /v3/vendors/{vendor_id}/events?type=ALL` |
| The orders | `GET /v3/vendors/{vendor_id}/orders` |
| Payment method per order | `GET /v3/orders/{id}/payments` |
| Service date of a ticket | `GET /v3/dates/{id}` |
| Single event fallback | `GET /v3/events/{id}` |

Useful `GET /orders` parameters: `start_date`, `end_date` (when the order was
**placed**), `start_event_date`, `end_event_date` (by **service** date),
`status`, `fields`, `order`, `delta_since`, `limit`, `offset`.

All timestamps must match `YYYY-MM-DDThh:mm:ssZ` — UTC, with seconds and a
trailing `Z`. `2026-08-01` alone will be rejected.

## 7. Correctness gotchas — read before writing any code

None of the following can be derived from the spec. Each one has produced a wrong
report in practice.

1. **`type=ALL` on vendor events.** `GET /vendors/{id}/events` defaults to
   `type=BOOKING`. Without `type=ALL`, request events ("Anfrage-Events") are
   missing and the event-name column comes back silently empty.
2. **`status` defaults to `ACCEPTED`.** `GET /orders` silently omits
   cancellations unless you pass `status=ALL`. Ask the customer whether they want
   cancellations. Note the filter enum (`ACCEPTED, CANCELED, PENDING, DECLINED,
   OPEN, ALL`) and the order payload's own `status` enum (which includes
   `RESERVED`) are not identical.
3. **Ticket money is gross, and arrives as a string.** Mixing gross and net up
   is the single most common error:

   | Value | Unit | Gross or net |
   |---|---|---|
   | `tickets[].participants[].price_value` | euros, as a string (`"35.00"`) | **gross** → net = gross / (1 + vat/100) |

4. **Two independent cancellation levels.** Check both
   `tickets[].status == "CANCELED"` and
   `tickets[].participants[].status == "CANCELED"`. A live ticket can hold
   cancelled participants. Missing either inflates participant counts and
   revenue.
5. **`participants[].vat` is not reliable.** VAT-exempt products have been seen
   returning 19 %. Let the customer configure an override rate, and log every
   case where the API rate differs from the configured one so they can fix the
   price category in bookingkit.
6. **The service date is not in the order payload.** Only `date_id` is (some
   payloads use `event_date_id` — try both). Resolve it with `GET /dates/{id}`,
   which also returns `event_id`.
7. **Resolving an event name needs a fallback chain**, in this order: the vendor
   event map → `tickets[].event_title` if present → `GET /dates/{date_id}` to get
   `event_id` → `GET /events/{event_id}`. Price-list events and request events
   are why the chain exists.
8. **Payment method:** use `payments[].name` (the readable "PayPal", "Stripe"
   the customer knows from the standard export), **not** `payment_method`, which
   only holds a coarse type (`ThirdParty` / `Cash` / `MobileApp`). Payment values
   can be negative — those are refunds.
9. **Combination tickets double-count.** If the customer sells "Kombitickets",
   their revenue is already contained in the single events. Offer a keyword
   exclusion list.
10. **Booking date vs service date.** `start_date`/`end_date` filter by when the
    order was placed; `start_event_date`/`end_event_date` filter by when the
    service happens. Accounting reports usually want the service date. **Ask —
    do not assume.** Separately, `GET /dates` defaults to `available=true`, which
    hides dates with no free slot; pass `available=false` when reporting.
11. **Pick one timezone deliberately.** Querying in UTC but formatting in local
    time makes rows near a month boundary appear outside the requested range.
12. **Round consistently.** Round each money column to 2 decimals, then sum the
    *rounded* values for totals, so the printed column visibly adds up.

## 8. Writing the CSV

Default to German Excel, since most bookingkit vendors use it:

- Encoding **UTF-8 with BOM** (`utf-8-sig` in Python) — without the BOM, Excel
  mangles umlauts.
- Field separator **`;`**.
- Decimal **comma** (`1234,56`), no thousands separator.
- Dates as `DD.MM.YYYY`, timestamps as `DD.MM.YYYY HH:MM`.
- Write money as plain numbers, never with a currency symbol, so the columns can
  be summed.

Ask once whether they use German or English Excel; for English, use `,` as the
separator and `.` as the decimal mark.

Keep the **column order fixed** and identical on every run. This is a contract
with whoever imports the file — never reorder or insert a column in the middle
without being asked. Write the file to
`out/_.csv`.

## 9. Verify before you hand it over

Print a short summary after every run:

- the resolved date range and which date basis was used (booking or service);
- number of orders, tickets and participants;
- total revenue (gross and net);
- number of API requests made;
- every warning collected (VAT mismatches, unresolved event names, orders
  spanning several cost centres).

Then tell the customer explicitly: **compare these totals against the standard
bookingkit export for the same month before using the report.** If they do not
match, the difference is almost always one of §7.2 (missing cancellations),
§7.4 (cancellation levels), §7.9 (combination tickets) or §7.3 (gross/net).

## 10. Finish by making the next run trivial

Append to `AGENTS.md`: the vendor id, the date basis, the chosen columns in
order, the filters and exclusions, the Excel locale, and anything you learned
about this customer's data. Then tell them that from now on they only need to
open this folder and say, for example:

> run the monthly order report for last month

and that they should come back to the help article only if they want to change
what the report contains.