# Typical integration scenarios

> Four typical integrations with BILLZ and a short route through the documentation for each.

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

All four need the common basics: [integration key](/en/start/integration-key/) → [first request](/en/start/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](/en/guides/sync-catalog/) — initial export and incremental updates
2. [Stock and prices](/en/guides/sync-stocks/) — what to update more often than the catalog
3. [Two storefront sync modes](/en/guides/sync-catalog/#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](/en/start/first-sale/) — the minimal path using four methods
2. [Online order from an external system](/en/guides/ecommerce-order/) — the full scenario: customer, discount, payment, fiscal receipt
3. [Sale from an external system](/en/guides/create-sale/) — gift cards, held sales, payment with several methods

The key fork: [an “order” in BILLZ means an order **to a supplier**](/en/guides/ecommerce-order/#terminology-fork), 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](/en/concepts/processes/) — the general scheme “assemble → fill → post”
2. [Product write-off](/en/guides/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](/en/guides/sales-export/) — receipts versus summary reports
2. [Key routes](/en/reference/permissions/) — which reports are available to the key

## Diagnosing problems

The [troubleshooting](/en/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](/en/guides/ecommerce-order/#in-what-form-is-the-invoice-returned) |
| Customer search by STIR / TIN                                                 | store the mapping on your side — [details](/en/guides/ecommerce-order/#search)                                     |
| An idempotency header                                                         | duplicate protection on your side — [details](/en/guides/ecommerce-order/#which-identifier-to-store)               |
| Webhooks — subscriptions to business events (a sale completed, stock changed) | poll on a schedule — [catalog synchronization](/en/guides/sync-catalog/)                                           |
| Direct serving of product photos from the BILLZ CDN                           | cache media on your side; this is [prohibited by the rules](/en/guides/sync-catalog/#what-not-to-do)               |

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