Typical integration scenarios

Four typical scenarios, each with its own route through the documentation.

All four need the common basics: integration key → first request.

1. Storefront: a website or marketplace shows BILLZ products

Catalog, stock and prices flow out of BILLZ. Sales can take place anywhere.

1. Catalog synchronization — initial export and incremental updates
2. Stock and prices — what to update more often than the catalog
3. Two storefront sync modes — delta once an hour, full once a day

Key method — GET /v2/products

2. Sales: an external system makes a sale in BILLZ

An online store, a custom cash register, a courier app — something outside BILLZ processes a purchase, and it must appear in BILLZ.

1. First sale — the minimal path using four methods
2. Online order from an external system — the full scenario: customer, discount, payment, fiscal receipt
3. Sale from an external system — gift cards, held sales, payment with several methods

The key fork: an “order” in BILLZ means an order to a supplier, while a customer’s purchase is called a sale.

3. Warehouse: product movements from an accounting system

Supplies, transfers between shops, write-offs, stocktaking.

1. Warehouse processes — the general scheme “assemble → fill → post”
2. Product write-off — a process example worked through to the end

Key rule: creating a document does not change the stock; posting it does. And the permission to post is separate from the permission to create.

4. Analytics: exporting data to BI or 1C

Revenue, receipts, transactions, product movement — outbound, read-only.

1. Exporting sales and revenue — receipts versus summary reports
2. Key routes — which reports are available to the key

Diagnosing problems

The troubleshooting section is organized by symptom: 403, 404, 200 with no effect, 408, 429.

What the public API does not have

These capabilities are absent, and no workaround methods are provided for them.

What is missing	What to do
A ready-made invoice or printable form for a sale	assemble it from GET /v2/order/:id — details
Customer search by STIR / TIN	store the mapping on your side — details
An idempotency header	duplicate protection on your side — details
Webhooks — subscriptions to business events (a sale completed, stock changed)	poll on a schedule — catalog synchronization
Direct serving of product photos from the BILLZ CDN	cache media on your side; this is prohibited by the rules

No webhooks are provided yet — neither for events nor for responses