Типовые сценарии интеграции
Четыре типовых сценария, для каждого — отдельный маршрут по документации.
Всем четырём нужна общая база: ключ интеграции → первый запрос.
1. Витрина: сайт или маркетплейс показывает товары BILLZ
Заголовок раздела «1. Витрина: сайт или маркетплейс показывает товары BILLZ»Каталог, остатки и цены едут из BILLZ наружу. Продажи при этом могут проходить где угодно.
- Синхронизация каталога — первичная выгрузка и инкремент
- Остатки и цены — что обновлять чаще каталога
- Два режима синхронизации — дельта раз в час, полная раз в сутки
Ключевой метод — GET /v2/products
2. Продажи: внешняя система проводит продажу в BILLZ
Заголовок раздела «2. Продажи: внешняя система проводит продажу в BILLZ»Интернет-магазин, собственная касса, приложение курьера — что-то снаружи оформляет покупку, и она должна появиться в BILLZ.
- Первая продажа — минимальный путь на четырёх методах
- Интернет-заказ из внешней системы — полный сценарий: клиент, скидка, оплата, фискальный чек
- Продажа из внешней системы — сертификаты, отложки, оплата несколькими способами
Ключевая развилка — «заказ» в BILLZ означает заказ поставщику, а покупка клиента называется продажей.
3. Склад: движения товара из учётной системы
Заголовок раздела «3. Склад: движения товара из учётной системы»Поставки, перемещения между магазинами, списания, инвентаризация.
- Складские процессы — общая схема «собрать → наполнить → провести»
- Списание товара — разобранный до конца пример процесса
Ключевое правило: создание документа не меняет остаток, его меняет проведение. И право на проведение — отдельное от права на создание.
4. Аналитика: выгрузка данных в BI или 1С
Заголовок раздела «4. Аналитика: выгрузка данных в BI или 1С»Выручка, чеки, транзакции, движение товара — наружу, на чтение.
- Выгрузка продаж и выручки — чеки против сводных отчётов
- Маршруты ключа — какие отчёты доступны ключу
Диагностика проблем
Заголовок раздела «Диагностика проблем»Раздел решение проблем устроен от симптома:
403, 404, 200 без эффекта, 408, 429.
Чего в публичном API нет
Заголовок раздела «Чего в публичном API нет»Этих возможностей нет, обходных методов для них не предусмотрено.
| Чего нет | Что делать |
|---|---|
| Готовой накладной или печатной формы по продаже | собирать из GET /v2/order/:id — подробнее |
| Поиска покупателя по СТИР / ИНН | хранить связь у себя — подробнее |
| Заголовка идемпотентности | защита от дублей на своей стороне — подробнее |
| Webhooks — подписки на бизнес-события (продажа прошла, остаток изменился) | опрашивать по расписанию — синхронизация каталога |
| Прямой раздачи фото товаров с CDN BILLZ | кэшировать медиа у себя, это запрещено правилами |