Store API v1

API для магазинов

Подключите собственную учётную программу: синхронизируйте остатки, передавайте продажи с других площадок и обрабатывайте заказы BrickFox.

BrickFox не подключается к BrickLink, BricksApp или другой площадке сам. Внешние системы связывает программа владельца магазина.

Доступ включается для магазина отдельно.

Ключ создаёт владелец магазина в кабинете. Секрет показывается один раз.

Первый запрос

Базовый адрес: https://brickfox.ru/api/store/v1.

Передавайте ключ только в заголовке Bearer. Не кладите его в URL, браузерный JavaScript или логи.

export BRICKFOX_API_TOKEN="секрет_из_кабинета"

curl --fail-with-body \
  -H "Authorization: Bearer $BRICKFOX_API_TOKEN" \
  https://brickfox.ru/api/store/v1/capabilities

Ответ capabilities содержит действующие scopes, режим склада, доступные функции и лимиты. Машинная схема — OpenAPI 3.1.

Ключи и права

Один ключ принадлежит одному магазину. Выдавайте программе только права, которые нужны её сценарию.

Задача	Scopes
Остатки и внешние продажи	`inventory:read`, `inventory:write`
Заказы	`orders:read`, `orders:write`
Имя и населённый пункт; телефон и полный адрес после принятия заказа	`orders:personal-data`
Снимок и журнал	`events:read`
Webhook	`webhooks:manage` и право на ресурс события
Переписка и файлы	`messages:read/write`, `attachments:read/write`

Отзыв ключа действует для нового запроса, скачивания файла, задания и следующей доставки webhook. Адреса не входят в обычную проекцию заказа.

Согласованная синхронизация

Первую локальную копию стройте через snapshot. Живой список /inventories может измениться между страницами.

1Создать snapshotЗафиксировать склад и заказы на одной границе.
2Прочитать страницыСобрать staging и заменить зеркало целиком.
3Читать changesСохранять каждый новый безопасный cursor.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $BRICKFOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bootstrap-2026-09-08-01" \
  -d '{"resources":["inventories","orders"]}' \
  https://brickfox.ru/api/store/v1/snapshots

После последней страницы сохраните meta.changes_cursor. Событие inventory.deleted удаляет строку из зеркала; inventory.invalidated и HTTP 410 требуют нового snapshot.

Продажа на другой площадке

Назначьте продаже постоянный external_operation_id. При таймауте повторяйте неизменённое тело с тем же ID и ключом идемпотентности.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $BRICKFOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: http-attempt-7f0b04f2" \
  -d '{
    "external_operation_id":"market-order-19342-line-1",
    "reason":"external_sale",
    "lines":[{"inventory_id":"LOT_ID","delta":-2}]
  }' \
  https://brickfox.ru/api/store/v1/inventory-adjustments

Постоянный внешний ID защищает от двойного списания и после окончания срока HTTP-квитанции. Сервер не уменьшит остаток ниже резерва заказов BrickFox.

Обработка заказа BrickFox

Получить заказ, ETag и available_actions.
Передать условия оплаты и доставки.
После подтверждения покупателя выполнить accept.
Выполнить prepare, затем ship.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $BRICKFOX_API_TOKEN" \
  -H 'If-Match: "ORDER_ID:RESOURCE_VERSION"' \
  -H "Idempotency-Key: ship-order-19342" \
  https://brickfox.ru/api/store/v1/orders/ORDER_ID/actions/ship

HTTP 412 означает, что заказ изменился. Получите его заново и перепроверьте действие. Файлы без контактов доступны в форматах csv, brickfox-xml, bsx и wanted-xml.

Webhook ускоряет, журнал восстанавливает

Проверяйте BrickFox-Signature как HMAC-SHA256 от timestamp + "." + raw_body. Сначала сохраните событие в свою надёжную очередь, затем отвечайте 2xx.

дубликаты допустимы — дедупликация по BrickFox-Event-Id;
порядок HTTP-доставки не гарантируется;
webhook запускает чтение ресурса или /changes, а не сам меняет количество;
callback принимает только публичный HTTPS-адрес.

Ошибки и восстановление

Ответ	Что делает клиент
`401`	Останавливает отправку и просит владельца заменить ключ.
`409`	Разбирает предметный конфликт; не меняет команду вслепую.
`412`	Перечитывает ресурс и принимает решение по новой версии.
`410`	Создаёт новый snapshot и атомарно заменяет зеркало.
`429`	Соблюдает `Retry-After`, добавляет jitter и backoff.
`5xx`	Повторяет безопасную команду с теми же идентификаторами.

Ошибки приходят как application/problem+json. Для диагностики сохраняйте code и X-Request-ID, без токена и тела заказа.

Основные ресурсы

Склад

Лоты, партии, цены, публикация и внешние операции.

/inventories

Синхронизация

Snapshot, непрерывный changes feed и фоновые jobs.

/snapshots · /changes

Заказы

Условия, состав, действия, отправления и платежные отметки.

/orders

Переписка

Сообщения, быстрые ответы и приватные изображения.

/messages · /attachments

Магазин

Профиль, настройки, способы, скидки и комплекты.

/shop · /settings

Сервис

Webhook, каталог, отчёты, начисления и выгрузки.

/webhooks · /reports

Нужен доступ к API?

Опишите учётную программу, нужные scopes и примерный размер склада.

Связаться с BrickFox Открыть OpenAPI