Перейти к содержимому

Типовые сценарии интеграции

Четыре типовых сценария, для каждого — отдельный маршрут по документации.

Всем четырём нужна общая база: ключ интеграции → первый запрос.

1. Витрина: сайт или маркетплейс показывает товары BILLZ

Заголовок раздела «1. Витрина: сайт или маркетплейс показывает товары BILLZ»

Каталог, остатки и цены едут из BILLZ наружу. Продажи при этом могут проходить где угодно.

  1. Синхронизация каталога — первичная выгрузка и инкремент
  2. Остатки и цены — что обновлять чаще каталога
  3. Два режима синхронизации — дельта раз в час, полная раз в сутки

Ключевой метод — GET /v2/products

2. Продажи: внешняя система проводит продажу в BILLZ

Заголовок раздела «2. Продажи: внешняя система проводит продажу в BILLZ»

Интернет-магазин, собственная касса, приложение курьера — что-то снаружи оформляет покупку, и она должна появиться в BILLZ.

  1. Первая продажа — минимальный путь на четырёх методах
  2. Интернет-заказ из внешней системы — полный сценарий: клиент, скидка, оплата, фискальный чек
  3. Продажа из внешней системы — сертификаты, отложки, оплата несколькими способами

Ключевая развилка — «заказ» в BILLZ означает заказ поставщику, а покупка клиента называется продажей.

3. Склад: движения товара из учётной системы

Заголовок раздела «3. Склад: движения товара из учётной системы»

Поставки, перемещения между магазинами, списания, инвентаризация.

  1. Складские процессы — общая схема «собрать → наполнить → провести»
  2. Списание товара — разобранный до конца пример процесса

Ключевое правило: создание документа не меняет остаток, его меняет проведение. И право на проведение — отдельное от права на создание.

Выручка, чеки, транзакции, движение товара — наружу, на чтение.

  1. Выгрузка продаж и выручки — чеки против сводных отчётов
  2. Маршруты ключа — какие отчёты доступны ключу

Раздел решение проблем устроен от симптома: 403, 404, 200 без эффекта, 408, 429.

Этих возможностей нет, обходных методов для них не предусмотрено.

Чего нет Что делать
Готовой накладной или печатной формы по продаже собирать из GET /v2/order/:id — подробнее
Поиска покупателя по СТИР / ИНН хранить связь у себя — подробнее
Заголовка идемпотентности защита от дублей на своей стороне — подробнее
Webhooks — подписки на бизнес-события (продажа прошла, остаток изменился) опрашивать по расписанию — синхронизация каталога
Прямой раздачи фото товаров с CDN BILLZ кэшировать медиа у себя, это запрещено правилами