СБИС API: OAuth2, retry и что не написано в официальной документации

Как восстановить доступ к Saby после ошибки сессии, отличить сбой транспорта от ошибки JSON-RPC и повторять операции без создания дублей. Разбираем сервисную авторизацию и границы автоматического retry.

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

Статья разбирает проектирование надёжного клиента Saby: авторизацию, обработку JSON-RPC и неопределённый результат записи после таймаута. Описанные сбои — сценарии для проверки интеграции, а не подтверждённая статистика отказов оператора.

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

Сервисная авторизация и восстановление сессии

Для рассмотренного способа интеграции приложение передаёт app_client_id, app_secret и secret_key на https://online.saby.ru/oauth/service/. В ответе используется поле token, а при вызове команд — заголовок X-SBISAccessToken. Не переносите сюда автоматически схему Bearer + refresh_token другого API.

СБИС: восстановление после 401. API-запрос → Успех; API-запрос → 401; 401 → Один повтор запроса
СБИС: восстановление после 401. Нажмите на схему, чтобы увеличить.

Одна сессия для группы workers

Храните текущий токен централизованно и сериализуйте повторную авторизацию блокировкой. Ожидающие workers должны перечитать токен после снятия блокировки, а не каждый создавать свою сессию. В документации сервисной авторизации указан лимит пяти активных сессий приложения; создание новой сверх лимита завершает старую.

Когда можно повторить запрос

После подтверждённой ошибки сессии получите новый токен и допускайте один повтор безопасной операции чтения. Для записи сначала выясните, не была ли она выполнена. Повторный отказ отправьте на разбор с кодом ошибки, идентификатором операции и временем; секреты в журнал не включайте.

Первоисточник: Saby: сервисная авторизация приложения, проверено 16 октября 2026 года. Интерактивная авторизация — другой сценарий; её параметры проверяйте отдельно.

Retry: когда повторный запрос — это не лекарство

Любой HTTP-клиент в 2026 году должен уметь retry. Symfony HttpClient даёт это из коробки: задаёшь количество попыток, backoff-стратегию, и он сам повторяет при 5xx и таймаутах. Но СБИС API требует кастомной логики retry, потому что не всё, что кажится временной ошибкой, ею является.

200 OK с ошибкой внутри тела

СБИС: проверяется и статус, и тело ответа. HTTP-статус + JSON-тело → Проверка error / error_message; Проверка error / error_message → Бизнес-ошибка; Проверка error / error_message → Техническая ошибка
СБИС: проверяется и статус, и тело ответа. Нажмите на схему, чтобы увеличить.

СБИС иногда возвращает HTTP 200, но в JSON-теле содержит поле error или error_message. Это происходит при валидации бизнес-логики: неверный ИНН контрагента, отсутствие обязательного поля, превышение лимита на размер документа. Стандартный retry на HTTP-статус такое не поймает — он увидит 200 и решит, что всё хорошо.

Мы добавили слой парсинга ответа, который проверяет не только статус, но и структуру тела. Если присутствует поле ошибки — выбрасываем кастомное SbisApiException с флагом isRetriable. Бизнес-ошибки (неверный ИНН) помечаются как non-retriable: повторный запрос не исправит данные. Технические ошибки (таймаут, 5xx) — как retriable.

Rate limiting: лимиты, о которых не предупреждают

В документации СБИС API нет явного раздела про rate limiting. Но на практике при интенсивной отправке документов мы начали получать 429 Too Many Requests. Лимит не задокументирован численно, и он, похоже, зависит от типа аккаунта и времени суток.

Наше решение — адаптивный rate limiter на стороне клиента. Мы используем Symfony RateLimiter с фиксированным окном: не более N запросов в минуту, где N подбирается эмпирически. При получении 429 включаем exponential backoff и временно снижаем лимит. Это замедляет отправку, но не ломает очередь.

Дубли документов при retry

После таймаута создания документа результат может быть неизвестен: сервер мог сохранить документ до разрыва соединения. Нельзя считать все методы API одинаково безопасными для повтора. Сохраните идентификатор исходного объекта, проверьте внешний результат и используйте документированный механизм конкретной команды.

Зарезервируйте операцию в локальном хранилище до сетевого вызова, используйте уникальный ключ из системы-источника, организации и UUID документа. После таймаута переведите операцию в состояние «результат неизвестен» и выполните сверку. Номер и дата документа недостаточны для надёжной идентификации.

Структура документа: JSON, который не совпадает с УПД

Когда бухгалтер говорит «отправь УПД», он подразумевает документ, который он видит в 1С. Когда разработчик читает документацию СБИС API, он видит JSON-схему. Между ними — пропасть.

Поля с разной семантикой

В 1С поле «Покупатель» — это контрагент из справочника. В JSON СБИС это вложенная структура с ИНН, КПП, наименованием, адресом и ролью. В 1С сумма НДС может быть рассчитана автоматически. В СБИС она должна быть явно указана в каждой позиции. В 1С маркировка — это отдельный механизм. В СБИС — поле внутри товара с определённым форматом.

Мы ввели промежуточный DTO UpdDto, который описывает документ в терминах бизнеса: продавец, покупатель, товары, сумма, НДС. Отдельный маппер преобразует DTO в JSON СБИС. Это позволяет:

  • Тестировать бизнес-логику отдельно от формата API;
  • Менять структуру JSON при обновлении API, не трогая ядро;
  • Поддерживать несколько версий формата параллельно.

Обязательные поля, которых нет в 1С

СБИС требует ряд полей, которые в типовой 1С не всегда заполнены: адрес контрагента для роуминга, коды ТН ВЭД для импорта, признак ГИС МТ для маркированных товаров. Если отправить документ без них — СБИС вернёт ошибку валидации, но не скажет, какое именно поле пропущено. Сообщение будет общим: «Неверный формат документа».

Мы добавили предварительную валидацию на стороне коннектора: перед отправкой DTO проходит через Symfony Validator с кастомными constraints. Если чего-то не хватает — документ не уходит в СБИС, а помечается ошибкой с понятным описанием. Бухгалтер видит в интерфейсе: «У контрагента Иванов ООО не заполнен адрес для ЭДО» — и исправляет в 1С, а не ловит абстрактную ошибку от API.

Ошибки, которые не должны быть фатальными

В интеграции с внешним API важно различать ошибки, от которых можно оправиться, и ошибки, которые требуют вмешательства человека. Мы выделили четыре класса ошибок СБИС API и для каждого настроили своё поведение.

Класс ошибки Пример Поведение
Транзиентная Таймаут, 5xx, 429 Retry с backoff, затем dead-letter
Валидационная Неверный ИНН, отсутствие поля Сразу dead-letter, уведомление пользователю
Авторизационная 401, 403 Refresh токена, затем retry; при неудаче — алерт
Бизнес-логика Контрагент не найден, дубль документа Dead-letter, ручная обработка

Чего не хватает в документации: список для разработчика

По итогам работы с СБИС API мы составили список вещей, которые хотели бы видеть в документации явно, но которые приходится добывать опытным путём.

Точные лимиты rate limiting

Сколько запросов в минуту допустимо? Зависит ли лимит от типа аккаунта? Есть ли burst-режим? Сейчас это чёрный ящик.

Полная схема ошибок

Какие коды ошибок может вернуть каждый эндпоинт? Какие из них retriable? Документация описывает happy path, но не сценарии отказа.

Идемпотентность

Можно ли безопасно повторить запрос? Если нет — какой механизм дедупликации рекомендуется? Это критично для надёжной интеграции.

Изменения API

Где публикуется changelog? Какой срок поддержки старых версий? Без этого планировать обновление коннектора невозможно.

Вебхуки vs polling

Есть ли механизм push-уведомлений о смене статуса документа? Или единственный способ узнать, что документ подписан — это регулярный polling? Документация умалчивает.

Тестовая среда

Есть ли sandbox, в котором можно отправлять документы без риска создать реальные записи? Если да — как получить к ней доступ?

Как мы тестируем интеграцию со СБИС

Тестирование интеграции с внешним API — задача, которая решается в несколько слоёв. Мы не полагаемся на ручные прогоны, потому что они не масштабируются и не покрывают граничные случаи.

Unit-тесты клиента

HTTP-клиент СБИС обёрнут в интерфейс SbisClientInterface. В тестах мы подменяем его моком, который возвращает заранее заготовленные ответы. Это позволяет тестировать логику retry, обработку ошибок и парсинг тела без реальных запросов к API. Моки хранятся как JSON-файлы в репозитории — это наши «золотые записи» ответов СБИС.

Интеграционные тесты

Раз в суток CI запускает тесты против реального тестового аккаунта СБИС. Они отправляют один тестовый документ, проверяют статус, забирают его обратно. Это ловит изменения в API, которые моки не предскажут: новые обязательные поля, изменение структуры ответа, неожиданные 403.

Contract testing

Мы используем подход, при котором фиксируем структуру запроса и ответа. Если ответ СБИС перестаёт соответствовать ожидаемой схеме — тест падает ещё до того, как это сломает продакшен. Для JSON-схем используем JSON Schema Validator.

Выводы для разработчиков

Интеграция с СБИС API — это не сложная задача в принципе, но она требует аккуратности в деталях. OAuth2, retry, валидация, дедупликация — всё это стандартные паттерны, которые Symfony даёт из коробки или с минимальными доработками. Главное — фиксировать версию контракта и проверять аварийные сценарии и проектировать клиент так, чтобы он выживал в реальном мире, а не только в тестовых запросах.

Если вы начинаете интеграцию с СБИС — начните не с эндпоинтов, а с архитектуры клиента: как он будет авторизовываться, как будет обрабатывать ошибки, как будет предотвращать дубли. Эти решения сложнее изменить на лету, чем добавить ещё один вызов API. Наш опыт вынесен в open-source коннектор sbis-1c-connector — там можно посмотреть реализацию клиента, DTO, retry-логики и обработки ошибок, описанных в статье.

По теме: если вы проектируете связанный контур, посмотрите Как мы автоматизировали отправку УПД из 1С в СБИС через cron и 1С ↔ Ozon: open-source коннектор на Symfony vs типовые обработки.

Что проверить на пилоте

Условия применимости. Автоматическое повторение POST после таймаута может повторить уже выполненную бизнес-операцию. Условия retry зависят от команды, а не только от HTTP-кода.

Проверочный сценарий. Смоделируйте сохранение документа с потерей ответа. Операция должна перейти на сверку, а не немедленно создать новый документ с другим идентификатором.

Как оценить результат. Отслеживайте неизвестные результаты, дубли и время ручного разбора. Успех последней попытки не доказывает отсутствие побочного эффекта предыдущих.

ModernERP Integration Monitor

Узнавайте о сбоях обменов раньше, чем о них сообщат сотрудники

Ошибки, задержки и история обменов между 1С, CRM, WMS и API — в одном сервисе. Контролируйте критичные интеграции с Integration Monitor.

Посмотреть Integration Monitor ↗

Работает на наших серверах · До 15 интеграций · 90 дней истории