API для учётной системы

Что это и зачем

Аналитика считает прибыль по себестоимости и показывает остатки. Оба числа живут в вашей учётной системе и меняются каждый день. Этот API нужен, чтобы они попадали в SnappyCheck сами.

Что умеет ключ: писать себестоимость и остаток по баркоду для ОДНОГО магазина и (если разрешено отдельной галочкой) читать записанные значения обратно. Всё.

Чего не умеет: ключей маркетплейсов, заказов, финансов, данных других магазинов он не видит и увидеть не может — это отдельный, намеренно узкий класс доступа.

Ключ и адрес

Базовый адрес: https://portal.snappycheck.ru/api/v1 — только https; на http:// сервер отвечает редиректом 308, а не данными. Сам по себе базовый адрес ничего не отдаёт (404) — обращайтесь к конкретным точкам: /ping, /status, /items.

Аутентификация: заголовок Authorization: Bearer sc_live_… в каждом запросе. Больше ничего не требуется — ни подписи, ни сессии.

Где взять ключ

1. Владелец магазина заходит в портал → раздел «Интеграция» (portal.snappycheck.ru/integration). Раздел доступен администратору магазина или владельцу аккаунта.
2. Придумывает имя ключа («1С основной») и нажимает «Создать ключ».
3. Ключ показывается один раз, целиком. Потерян — восстановить нельзя, нужно выпустить новый и отозвать старый.

Одновременно у магазина может жить не больше двух активных ключей — этого хватает, чтобы заменить ключ без простоя: выпустили новый, перевели выгрузку, отозвали старый.

Две настройки ключа

• «Разрешить читать значения» — галочка при создании. Без неё GET /api/v1/items отвечает 403: даже украденный ключ не выгрузит вашу себестоимость. Запись работает всегда.
• «С каких IP принимать» — поле в строке ключа в портале: IP-адреса (через запятую), с которых ключ принимается; с любого другого адреса — 403 ip_not_allowed. Пусто — принимается отовсюду. Сравнение точное, по отдельным адресам; подсети (/24) не поддерживаются. Удобнее всего заполнить после первого удачного обмена: под полем появится адрес, с которого он пришёл, и кнопка «разрешить только его».

Проверка связи

GET/api/v1/ping — самый первый запрос, который стоит сделать. Ничего не меняет, проверяет ключ и показывает, к какому магазину он привязан.

curl -s https://portal.snappycheck.ru/api/v1/ping \
  -H "Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "store": "ООО Ромашка",
  "can_write": true,
  "can_read_values": false
}

store — название магазина: убедитесь, что это тот магазин, который вы ожидали. can_read_values — разрешено ли этому ключу читать значения (см. Читать значения).

Отправить данные

POST/api/v1/items — основной метод. Принимает пачку строк («партию») и записывает их магазину, к которому привязан ключ.

curl -s -X POST https://portal.snappycheck.ru/api/v1/items \
  -H "Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2026-08-05T09:00-delta" \
  -d '{
    "mode": "delta",
    "dry_run": false,
    "items": [
      {"barcode": "4600000000001", "cost_price": 512.40, "stock": 17},
      {"barcode": "4600000000002", "cost_price": 899},
      {"barcode": "4600000000003", "stock": 0}
    ]
  }'

{
  "batch_id": "0f4a9d2e-6c1b-4f7a-9a3d-1f2b3c4d5e6f",
  "status": "applied",
  "duplicate": false,
  "received": 3,
  "applied": 2,
  "skipped_locked": 0,
  "unknown_barcodes": ["4600000000003"],
  "unknown_count": 1,
  "warnings": []
}

Поля запроса

Поле, которого нет в строке, не трогается. Хотите обновить только остатки — присылайте строки вообще без cost_price.

Поля ответа

Правила записи

Часть правил неочевидна, и от них зависит, не потеряете ли вы данные. Прочитайте эту таблицу до того, как настроите выгрузку.

Режимы delta и full

delta — «вот что изменилось»

Режим по умолчанию. Трогаются только присланные баркоды, остальные строки магазина не задеваются вообще. Это правильный режим для регулярной выгрузки каждые несколько часов.

full — «вот вся картина склада»

Всё то же самое, плюс одно важное следствие: всем товарам под интеграцией, которых нет в партии, остаток становится нулевым. Логика простая: вы прислали полную картину склада, значит, чего в ней нет — того на складе нет.

Что не обнуляется:

• себестоимость — никогда, режим касается только остатков;
• строки, которых интеграция ещё ни разу не касалась (продавец завёл их руками в портале) — «полная картина» вашего склада про них ничего не утверждает.

curl -s -X POST https://portal.snappycheck.ru/api/v1/items \
  -H "Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-2026-08-05" \
  -d '{"mode": "full", "items": [
        {"barcode": "4600000000001", "stock": 17},
        {"barcode": "4600000000002", "stock": 4}
      ]}'

Предпросмотр (dry_run)

"dry_run": true прогоняет партию целиком — разбор, правила записи, замки, все проверки, — и возвращает те же счётчики, что вернул бы боевой вызов, но не записывает ничего. Ответ приходит со "status": "dry_run".

Пользуйтесь им при настройке выгрузки и после изменений в ней: он честно покажет, сколько строк отбросится и сколько остатков обнулится, до того как это случится на самом деле.

Предпросмотр не занимает ключ идемпотентности: тот же Idempotency-Key потом сработает по-настоящему.

Повторы и идемпотентность

Сеть рвётся, задача падает по таймауту, cron запускается дважды. Чтобы повтор не записал партию второй раз, присылайте заголовок Idempotency-Key — любую строку до 64 символов, уникальную для этой партии (например, «2026-08-05T09:00-delta»).

Если партия с таким ключом уже принималась у этого магазина, ответ придёт 200 с "duplicate": true и счётчиками ПЕРВОЙ партии — ничего не записывается повторно.

Без этого заголовка каждый запрос считается новой партией.

Читать значения

GET/api/v1/items?barcodes=a,b,c — вернуть то, что сейчас хранится. Работает только у ключа, которому при создании разрешили чтение (галочка в портале), иначе 403 read_not_allowed.

curl -s -G https://portal.snappycheck.ru/api/v1/items \
  -H "Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  --data-urlencode "barcodes=4600000000001,4600000000002"

{
  "4600000000001": {"cost_price": 512.4, "stock": 17.0, "locked": false},
  "4600000000002": {"cost_price": 899.0, "stock": null, "locked": true}
}

Баркоды, которых нет в базе магазина, просто отсутствуют в ответе — это не ошибка. locked: true означает замок себестоимости: цену этого товара ваши партии не перезапишут.

За один запрос принимается до 1000 баркодов; лишние молча отбрасываются — режьте список на своей стороне. Пустой barcodes — пустой ответ {}.

Состояние обмена

GET/api/v1/status — короткая сводка по магазину. Удобно для мониторинга на вашей стороне: например, поднять тревогу, если last_batch_at старше суток.

{
  "last_batch_at": "2026-08-05T09:00:11.482913+00:00",
  "last_batch_status": "applied",
  "items_under_integration": 1840,
  "locked_items": 3
}

Лимиты и частота

Как часто присылать. Раз в 10 секунд — это потолок защиты, а не рекомендация. Реальной аналитике достаточно обмена раз в час; полную выгрузку (full) обычно делают раз в сутки.

Коды ошибок

Тело любой ошибки этого API выглядит так:

{
  "error": "неверный ключ",
  "code": "invalid_key"
}

error — человеку в лог. code — программе. Разбирайте именно code: текст error мы можем переформулировать в любой момент, а code стабилен. У некоторых ошибок в теле есть дополнительные поля — они указаны в таблице.

Стоп-кран: задержанная партия

Если mode=full обнулила бы остаток больше чем у половины товаров под интеграцией (и таких товаров не меньше 20), партия не применяется. Ответ — обычный 200, но со "status": "held": партия принята и сохранена целиком, данные магазина не тронуты.

Решает человек: владелец магазина видит партию в портале, в разделе «Интеграция», и нажимает «Применить» (записать ровно то, что показано) или «Отклонить» (данные остаются как есть).

Пока решения нет, каждая следующая full (в том числе с dry_run) получает 422 held_batch_pending. Режим delta продолжает работать без ограничений.

Резкий скачок и откат

Если больше чем у 20 % сравнимых строк себестоимость изменилась более чем втрое, партия применяется, но помечается как подозрительная: в warnings появляется предупреждение с числами, а в портале — плашка со ссылкой на откат. Сравнимыми считаются строки, у которых уже была прежняя цена (первая в жизни загрузка аномалией не выглядит).

Откат. Любую применённую партию владелец может откатить в портале в течение 30 дней: себестоимость и остатки вернутся такими, какими были до неё. Откат не трогает позиции с замком и те, что кто-то поправил вручную после обмена, — их количество показывается отдельно. Если те же товары уже перезаписала более поздняя партия, откат целиком запрещается: смешивать состояния из разных моментов нельзя.

Отзыв ключа

Ключ перестаёт работать в трёх случаях. После отзыва любой запрос по нему — 401 invalid_key; восстановить отозванный ключ нельзя, только выпустить новый.

Оба автоматических отзыва предупреждаются за 7 дней — плашкой в портале, с точным числом оставшихся дней.

Частые ошибки

Собрано из реальных обращений. Если ваша ситуация здесь — исправление займёт минуту.

Приходит код 308 (Permanent Redirect), тела нет

Запрос ушёл на http://. Сервер работает только по https и на обычный http отвечает «переезжайте на https» (308). Браузер такой редирект проходит сам, а HTTP-клиент 1С — нет, поэтому вы видите 308. Исправление: адрес https://portal.snappycheck.ru, порт 443, защищённое соединение.

Соединение = Новый HTTPСоединение("portal.snappycheck.ru", 443, , , , , Новый ЗащищенноеСоединениеOpenSSL());
Запрос = Новый HTTPЗапрос("/api/v1/ping");
Запрос.Заголовки.Вставить("Authorization", "Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
Ответ = Соединение.Получить(Запрос);
Сообщить(Ответ.КодСостояния);            // ждём 200
Сообщить(Ответ.ПолучитьТелоКакСтроку()); // {"store": "…", "can_write": true, …}

В ответе {"detail": "Not Found"} (404)

Такого адреса нет. Чаще всего открывают «корень» /api/v1 или /api/v1/ — сам по себе он ничего не отдаёт. Рабочие адреса только три: GET /api/v1/ping, GET /api/v1/status, POST/GET /api/v1/items. Проверьте путь по буквам: /api/v1/item, /api/v1/ping/ с лишним слешем или /api/ping без v1 — тоже 404.

Открываю адрес в браузере — «неверный ключ» (401)

Так и должно быть: браузер из адресной строки не передаёт заголовок с ключом, а без него любой запрос — 401. Браузер для проверки не годится. Проверяйте из командной строки — одной строкой:

curl -s https://portal.snappycheck.ru/api/v1/ping   -H "Authorization: Bearer sc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Ответ вида {"store": "Название магазина", "can_write": true, …} — связь есть, ключ верный. Тот же 401 из 1С означает: заголовок не дошёл (опечатка в слове Authorization, нет слова Bearer и пробела после него, лишние пробелы или перенос строки в ключе) либо ключ отозван в портале.

403 ip_not_allowed — «адрес не разрешён для этого ключа»

У ключа в портале заполнено поле «С каких IP принимать», и запрос пришёл с другого адреса (например, сервер 1С переехал или выгрузку запустили с рабочего места). Владелец магазина либо добавляет новый адрес в это поле, либо очищает его — тогда ключ снова принимается отовсюду.

403 read_not_allowed при чтении

Ключ выпущен без галочки «разрешить читать значения» — писать он может, читать нет. Для сверки нужен ключ с этой галочкой (выпускается заново, старый можно отозвать).

Как понять, что запрос вообще дошёл до SnappyCheck

В портале, в разделе «Интеграция», у ключа есть колонка «Использован» — время последнего запроса с этим ключом — и под полем адресов подпись «последний обмен пришёл с адреса …». Если там «ни разу», до нас не долетело ни одного запроса: смотрите два первых пункта (http вместо https, неверный адрес).

Поддержка

Вопрос по интеграции, нужен пример под вашу конфигурацию 1С или кажется, что сервис ответил неправильно — напишите нам и приложите batch_id из ответа: по нему видно всё, что произошло с партией.

Почта: SnappyCheck@yandex.com