Задача статьи. Здесь проектируем восстановление после сбоя, ограниченный retry и сверку неопределённого результата записи. Первичная настройка приложения и сервисной авторизации.
Статья разбирает проектирование надёжного клиента Saby: авторизацию, обработку JSON-RPC и неопределённый результат записи после таймаута. Описанные сбои — сценарии для проверки интеграции, а не подтверждённая статистика отказов оператора.
Сервисная авторизация и восстановление сессии
Для рассмотренного способа интеграции приложение передаёт app_client_id, app_secret и secret_key на https://online.saby.ru/oauth/service/. В ответе используется поле token, а при вызове команд — заголовок X-SBISAccessToken. Не переносите сюда автоматически схему Bearer + refresh_token другого API.
Одна сессия для группы workers
Храните текущий токен централизованно и сериализуйте повторную авторизацию блокировкой. Ожидающие workers должны перечитать токен после снятия блокировки, а не каждый создавать свою сессию. В документации сервисной авторизации указан лимит пяти активных сессий приложения; создание новой сверх лимита завершает старую.
Когда можно повторить запрос
После подтверждённой ошибки сессии получите новый токен и допускайте один повтор безопасной операции чтения. Для записи сначала выясните, не была ли она выполнена. Повторный отказ отправьте на разбор с кодом ошибки, идентификатором операции и временем; секреты в журнал не включайте.
Первоисточник: Saby: сервисная авторизация приложения, проверено 16 октября 2026 года. Интерактивная авторизация — другой сценарий; её параметры проверяйте отдельно.
Retry: когда повторный запрос — это не лекарство
Любой HTTP-клиент в 2026 году должен уметь retry. Symfony HttpClient даёт это из коробки: задаёшь количество попыток, backoff-стратегию, и он сам повторяет при 5xx и таймаутах. Но СБИС API требует кастомной логики retry, потому что не всё, что кажится временной ошибкой, ею является.
200 OK с ошибкой внутри тела
СБИС иногда возвращает 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 мы составили список вещей, которые хотели бы видеть в документации явно, но которые приходится добывать опытным путём.
Сколько запросов в минуту допустимо? Зависит ли лимит от типа аккаунта? Есть ли burst-режим? Сейчас это чёрный ящик.
Какие коды ошибок может вернуть каждый эндпоинт? Какие из них retriable? Документация описывает happy path, но не сценарии отказа.
Можно ли безопасно повторить запрос? Если нет — какой механизм дедупликации рекомендуется? Это критично для надёжной интеграции.
Где публикуется changelog? Какой срок поддержки старых версий? Без этого планировать обновление коннектора невозможно.
Есть ли механизм 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-кода.
Проверочный сценарий. Смоделируйте сохранение документа с потерей ответа. Операция должна перейти на сверку, а не немедленно создать новый документ с другим идентификатором.
Как оценить результат. Отслеживайте неизвестные результаты, дубли и время ручного разбора. Успех последней попытки не доказывает отсутствие побочного эффекта предыдущих.