AI-Assisted Integration

anybill actively supports developers who integrate the Frontend SDK with the help of AI coding agents such as Cursor, Claude Code, GitHub Copilot and Codex. The primary audience is developer teams at retail merchants and integration partners who want to move from first contact to a working integration with fewer round-trips, less manual reading, and less trial-and-error.

Why we provide this

We treat Developer Experience as part of the product. If developers rely on AI coding agents day-to-day, the documentation has to be accessible to those agents as well, not only to humans browsing HTML. We therefore ship the documentation in a machine-readable shape, make the integration patterns explicit, and expose them at stable URLs that any AI tool can reference. It is part of how we build anybill, not a side project.

What we provide

Machine-readable documentation (llms.txt)

llms.txt is an open standard for publishing a curated index of documentation that is optimized for large language models. Our index lives at:

• developer.anybill.de/llms.txt

It lists every relevant SDK and API page with a one-line description and a direct link to the Markdown version.

Usage example for Cursor: open Settings > Features > Docs > Add new doc and paste the URL above. Cursor will index the referenced pages and make them available in chat and inline suggestions.

Clean Markdown versions of every page

Every documentation page is also served as a plain Markdown file at the same path with an .md suffix. For example:

• developer.anybill.de/the_anybill_sdk/overview.md
• developer.anybill.de/the_anybill_sdk/android_integration.md
• developer.anybill.de/partner_platform_api/api_v3.md

These files contain the same content as the rendered HTML pages but without HTML boilerplate, which makes them ideal as context for AI coding agents.

AGENTS.md starter file

AGENTS.md is an open convention for project-level instructions aimed at AI coding agents. It is supported by Cursor, OpenAI Codex, Zed and other tools. We provide a ready-to-use starter file that captures the anybill authentication model, the SDK initialization contract, common pitfalls and out-of-scope actions.

Download it and place it at the root of your project:

• anybill-sdk-AGENTS.md

The full content of the file:

# anybill SDK Integration

This project integrates the anybill SDK for digital receipts. This file
provides context for AI coding agents working on the integration.

## What is anybill

anybill is a digital receipt solution for retail merchants. The Frontend SDK
enables consumer-facing apps to receive, display, and manage digital receipts
issued at point of sale.

## Official documentation

- Overview and machine-readable index: https://developer.anybill.de/llms.txt
- Frontend SDKs: https://developer.anybill.de/the_anybill_sdk/overview.md
- Android: https://developer.anybill.de/the_anybill_sdk/android_integration.md
- iOS: https://developer.anybill.de/the_anybill_sdk/ios_integration.md
- Flutter: https://developer.anybill.de/the_anybill_sdk/flutter_integration.md
- React Native: https://developer.anybill.de/the_anybill_sdk/react_native_integration.md
- Web: https://developer.anybill.de/the_anybill_sdk/web_integration.md
- Partner Platform API: https://developer.anybill.de/partner_platform_api/api_v3.md

When in doubt, fetch the relevant `.md` page and follow the official flow.

## Authentication model

The Frontend SDK is initialised with a short-lived access token that the
customer backend mints via the anybill Partner Platform API
(`POST /v3/user/token`). Internally anybill always stores both an
`anybillUserId` and an `externalId` for every user. The two integration
variants differ in *how* that user record is created, not in which id is
used afterwards:

- **Implicit user creation via `externalId` (recommended):** Pass any
  stable identifier from the customer's own system (customer number,
  loyalty card number, user id) as `externalId`. The anybill user is
  created on the first receipt that is sent with that `externalId` via
  the Vendor API `POST /v3/bill` endpoint. The `POST /v3/user/token`
  call itself does **not** create a user; it returns HTTP 404 until a
  matching user exists. No pre-registration step is required and no
  anybill user id has to be persisted on the customer side.
  *This flow has to be enabled per tenant on the anybill side. Contact
  `dev@anybill.de` if it is not active for your account yet.*
- **Explicit user creation via `POST /v3/user`:** Create the anybill
  user up front, store the returned `userId` alongside your own user
  record and use it for subsequent token requests. Use this if you need
  to control the user life cycle yourself (for example to pre-register
  users before their first receipt, or to run explicit user management
  operations).

Prefer the implicit `externalId` flow unless you have a concrete reason
to manage anybill users explicitly. Both flows result in the same user
record on anybill's side.

The SDK handles token refresh internally. When refresh fails, the SDK calls
a customer-provided callback; the customer app must then request a new
token from the customer backend and pass it back to the SDK.

**Never embed anybill API keys or partner credentials in the client app.**
Token minting always happens server-side.

## SDK initialization contract

The SDK requires:
- An environment (sandbox / production)
- A valid access token obtained via the flow above
- A token-refresh callback that returns a new token when called

Always consult the platform-specific integration page for the exact
method names, types and up-to-date examples. The snippets below are
starting points, not copy-paste-ready production code.

### Android (Kotlin) - token-based login

Reference: https://developer.anybill.de/the_anybill_sdk/android_integration.md

```kotlin
val result = YourApi.getTokenForUser() // accessToken, refreshToken, expiresIn
val user = TokenUser(result.accessToken, result.refreshToken, result.expiresIn)

when (val tokenLogin = AuthProvider.loginTokenUser(user)) {
    is ApiResult.EmptySuccess -> Unit // continue
    is ApiResult.GenericError -> Unit // handle error
    is ApiResult.NetworkError -> Unit // handle error
}
```

### iOS (Swift) - token-based login

Reference: https://developer.anybill.de/the_anybill_sdk/ios_integration.md

```swift
let result = await YourApi.getTokenForUser()
let tokenUser = TokenUser(
    accessToken: result.accessToken,
    expiresIn: result.expiresIn,
    refreshToken: result.refreshToken
)

authProvider.loginTokenUser(tokenUser: tokenUser) { result in
    switch result {
    case .success: break // continue
    case .failure(let error): break // handle error.type
    }
}
```

### Flutter (Dart) - token-based login

Reference: https://developer.anybill.de/the_anybill_sdk/flutter_integration.md

```dart
final tokens = await YourApi.getTokenForUser();

final loginCall = await AuthProvider.instance.loginUserWithToken(
  accessToken: tokens.accessToken,
  refreshToken: tokens.refreshToken,
  expiresIn: tokens.expiresIn,
);
```

### React Native (TypeScript) - token-based login

Reference: https://developer.anybill.de/the_anybill_sdk/react_native_integration.md

```ts
const { loginWithToken } = useAuth();

const result = await YourApi.getTokenForUser();
const tokenUser: TokenUser = {
  accessToken: result.accessToken,
  refreshToken: result.refreshToken,
  expiresIn: result.expiresIn,
};

const loginResult = await loginWithToken(tokenUser);
```

### Web (TypeScript) - token-based login

Reference: https://developer.anybill.de/the_anybill_sdk/web_integration.md

```ts
import { ApiConfig, AuthProvider } from "@anybill/base";

ApiConfig.initialize(clientId, environment);

await AuthProvider.instance.loginTokenUser(accessToken, refreshToken);
```

## Common pitfalls

- Do not hardcode tokens. Tokens are short-lived by design.
- Do not call the anybill App API directly from the client. Use the SDK.
- Do not create anybill users from the client. Token requests (and, if
  needed, explicit user creation) are a backend responsibility via the
  Partner Platform API.
- Do not introduce a separate "anybill user id" field in your data model
  unless you actually use the explicit `POST /v3/user` flow. With the
  implicit `externalId` flow the existing customer id is enough.
- Expect the first `POST /v3/user/token` call for a new `externalId` to
  return HTTP 404 until at least one receipt with that `externalId` has
  been sent via the Vendor API. Handle this by retrying once a receipt
  is known to exist, not by creating the user from the client.
- Treat token-refresh failures as a signal to re-authenticate the user,
  not as a transient error to retry blindly.

## When generating code

- Prefer the idiomatic patterns of the host app (e.g. Hilt/Koin on Android,
  Swift concurrency on iOS, Provider/Riverpod on Flutter).
- Wrap SDK calls in a thin adapter layer so the rest of the app does not
  depend on anybill types directly. This keeps the integration swappable
  and testable.
- Surface SDK errors through the app's existing error-handling pipeline;
  do not introduce a parallel error path.

## Out of scope for AI agents

- Do not generate production API keys or tokens.
- Do not modify the customer backend's token-minting endpoint without
  explicit human review.
- Do not change authentication flows based on assumptions. If the flow
  is unclear, fetch the relevant doc page and ask the developer.

How to use it with your AI tool

Cursor

1. Open Settings > Features > Docs > Add new doc and add https://developer.anybill.de/llms.txt.
2. Download anybill-sdk-AGENTS.md and save it as AGENTS.md at the root of your project.
3. Prompt Cursor, for example:

Integrate the anybill Android SDK into this app using the linked user
account flow. Follow the anybill docs and the rules in AGENTS.md.

Claude Code

1. Save anybill-sdk-AGENTS.md as CLAUDE.md at the root of your project, or create a symlink from CLAUDE.md to AGENTS.md.
2. Reference the documentation via /add-dir for local copies or pass the URL https://developer.anybill.de/llms.txt directly in your prompt.
3. Prompt Claude Code, for example:

Read https://developer.anybill.de/llms.txt and CLAUDE.md, then integrate
the anybill iOS SDK into this project. Use the externalId-based token
flow so we do not have to persist an additional anybill user id.

GitHub Copilot and other tools

• GitHub Copilot: place the content of AGENTS.md at .github/copilot-instructions.md.
• Other tools: use the equivalent project-instructions file your tool supports (for example .codeium/instructions.md or tool-specific rules files) and link to https://developer.anybill.de/llms.txt as the documentation source.

Example prompts

Android integration:

Integrate the anybill Android SDK into this existing Kotlin app. The user
is already authenticated via our backend. Use the externalId-based token
flow from the Partner Platform API (POST /v3/user/token with externalId),
reusing our customerId as the externalId so we do not have to persist an
anybill user id. Read the anybill docs at
https://developer.anybill.de/llms.txt for the exact flow.

iOS integration:

Integrate the anybill iOS SDK into this existing Swift app. The user is
already authenticated via our backend. Use the externalId-based token
flow from the Partner Platform API (POST /v3/user/token with externalId),
reusing our customerId as the externalId so we do not have to persist an
anybill user id. Read the anybill docs at
https://developer.anybill.de/llms.txt for the exact flow.

Token refresh callback:

Implement the token refresh callback for the anybill SDK on Android. When
the refresh fails, fetch a new token from our backend endpoint
`/anybill/token` and set it via the SDK's setToken method.

Cross-platform decision:

I need to add digital receipts to both our Android and iOS apps. Compare
the anybill native SDKs vs. the Flutter SDK for our use case, based on the
official anybill documentation.

Security considerations

Keep this short and apply it strictly:

• Do not let AI agents embed real API keys, partner credentials or production tokens in client code or commit history.
• Integration tokens for the Frontend SDK are issued by your backend via the Partner Platform API. Minting stays server-side.
• Review any AI-generated change that touches authentication, token handling or network calls before merging.

See the Security and Compliance page for the broader platform-level guarantees.

Feedback

We actively evolve this setup. If a prompt, a documentation page or the AGENTS.md template did not work as expected, let us know via the usual developer support channel at dev@anybill.de.