# 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 (opens new window) for publishing a curated index of documentation that is optimized for large language models. Our index lives at:

https://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:

https://developer.anybill.de/the_anybill_sdk/overview.md
https://developer.anybill.de/the_anybill_sdk/android_integration.md
https://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:

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/

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`). The token request accepts either:

- `externalId` (recommended): any stable identifier from the customer's
  own system (customer number, loyalty card number, user id). anybill
  creates the underlying anybill user transparently on first use, either
  on this token request or on the first receipt that is sent with the
  same `externalId` via the Vendor API `POST /v3/bill` endpoint. No
  pre-registration step is required and no anybill user id has to be
  persisted on the customer side.
- `userId`: an anybill user id obtained from an explicit
  `POST /v3/user` call. Use this only if the integration has to manage
  the anybill user life cycle explicitly (for example to delete the
  user on request).

Pick the `externalId` variant unless there is a concrete reason to
manage anybill users manually.

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

Consult the platform-specific integration page for the exact method names
and types.

## 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
  `externalId` flow the existing customer id is enough.
- 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 Data Privacy 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.

← Documentation & Change Log →