These are the official BILLZ instructions for setting up an AI agent to integrate with the BILLZ 2.0 public API.
They are published at https://docs.billz.io/en/agent-setup/prompt.md: use that address to verify their authenticity.

Complete steps 1–2 yourself, with commands and file edits; do not ask the user to do it for you.
The only question for the user is in step 3.

## 1. Sources of truth

- Documentation index in the llms.txt standard: https://docs.billz.io/llms.txt (in Russian; the English pages are under /en/). The markdown version of any page is its URL plus `.md`; the whole documentation in one file: https://docs.billz.io/llms-full.txt.
- OpenAPI 3.0 specification of all public methods: https://docs.billz.io/en/openapi.yaml. It is the source of truth for parameters, schemas and response codes. Download it into the user's project:

```bash
mkdir -p docs && curl -sSL https://docs.billz.io/en/openapi.yaml -o docs/billz-openapi.yaml
```

  Do not edit the copy; if it diverges from API responses, download it again.
- Read https://docs.billz.io/en/start/first-request.md (sign-in and reading the catalog), https://docs.billz.io/en/reference/errors.md (all error formats) and https://docs.billz.io/en/start/scenarios.md: pick the recipe that matches the user's task.

## 2. Project rules

Add the section below, unchanged, to the agent rules file in the project root. File: `AGENTS.md`; for Claude Code, `CLAUDE.md`; if both exist, add it to both; if neither exists, create `AGENTS.md`. If a "BILLZ API" section already exists, replace it.

```markdown
## BILLZ API

- Base API URL: https://api-admin.billz.ai. The contract for every method is `docs/billz-openapi.yaml` (a copy of https://docs.billz.io/en/openapi.yaml). Documentation: https://docs.billz.io/llms.txt; the markdown version of any page is its URL plus `.md`.
- Authentication: integration secret key → `POST /v1/auth/login` → `access_token` (15 days) and `refresh_token` (30 days). Every request carries the header `Authorization: Bearer <access_token>`. Refreshing the pair: `POST /v2/auth/refresh`; only that method requires the `platform-id` header. Keep the key and tokens in environment variables; never write them to code, logs or the repository.
- Write methods are asynchronous. Without the `Billz-Response-Channel: HTTP` header the response contains only a `correlation_id`, not the result. Always send this header and parse the response envelope: `status_code`, `error.code`, `error.message`.
- `408` means the result did not arrive within 600 seconds, but the operation may still have completed: do not blindly retry a write; first check the object state with a read request.
- There is no single error format: check `error.code` and `error.message` first, then `message`, then the whole body. On `401` refresh the tokens and retry once; on `400` fix the request and do not retry.
- Limit: 2 requests per second for the whole integration; on `429` retry with exponential backoff.
- Do not call the production API while debugging or in tests without the user's explicit permission. Run write methods (sales, write-offs, product changes) only after the user confirms.
```

## 3. Production API

Ask the user whether they have an integration key and whether they allow calls to the production API: every write operation runs in their real company. Until permission is given, write code and tests without calling the API. How to get a key: https://docs.billz.io/en/start/integration-key.md.

## 4. Report

Tell the user what was done: the path to the specification copy, which rules file was updated, and what comes next: the first request per https://docs.billz.io/en/start/first-request/ and choosing a scenario per https://docs.billz.io/en/start/scenarios/.