Инструкция об особенностях интеграции с API СБИС
Введение
Наша команда занимается разработкой приложения Tardis (MCOB. Управление бухгалтерией). Приложение используется компаниями уполномоченных бухгалтерий для управления и комплексного взаимодействия c базами 1С, в которых ведется бухгалтерский учет по обслуживаемым организациям.
Приложение предоставляет пользователям единый интерфейс, в котором отображаются актуальные сведения о состоянии ведения учета по организациям во множестве баз 1С.
Кроме этого возникла потребность отображать в этом интерфейсе данные организаций, по которым отчетность и взаимодействие с контролирующими органами выполняется в таких сервисах как СБИС.Онлайн и Контур.Экстерн.
Своевременное информирование о статусах отчетности или получении Требований от контролирующих органов является очень важным для бухгалтеров. Особенно когда бухгалтер ведет несколько организаций в разных программах, или каждая организация имеет собственный аккаунт в какой-то системе.
О недокументированных особенностях получения данных из СБИС.Онлайн и пойдет речь в этой статье.
Вся документация для разработки взаимодействия изучалась на официальном сайте СБИС. В соответствии с ней выполнялась первоначальная авторизация для получения токена, выполнялись запросы с этим токеном, и после получения данных закрывался сеанс.
1. Получение регламентированных отчетов
Первой задачей было получить статусы регламентированных отчетов.
Сначала попробовали метод API отчетности СБИС.СписокИзменений https://sbis.ru/help/integration/api/reporting/commands/list_change
Но этот метод возвращал только документы ЭДО (счета, реализации, акты). Даже если установить параметр запроса ТолькоОтчетность=Да, как рекомендовала техподдержка СБИС, регламентированные отчеты получить не удавалось.
Поэтому попробовали использовать метод СБИС.СписокДокументов https://sbis.ru/help/integration/api/all_methods/list_doc , хотя техподдержка СБИС не всегда признает существование этого метода для отчетности
Для получения именно отчетов нашли способ - указывать в параметре Тип=ОтчетФНС или ОтчетПФР, хотя в документации данные типы документов не указаны https://sbis.ru/help/integration/catalog/guide#1
И техподдержка СБИС считает, что данные типы использовать нельзя
Тем не менее, таким способом нам удалось получать статусы по всем видам отчетов.
2. Получение Требований ФНС
В АПИ ЭДО СБИС мы не нашли метода, возвращающего список документов такого типа.
Изначально, мы пробовали получить Требования методом СБИС.СписокДокументов, но документы такого типа данным методом не возвращаются.
Однако, удалось получить новые Требования методом СБИС.СписокСлужебныхЭтапов. https://sbis.ru/help/integration/api/all_methods/stage_doc
и получить данные документа методом СБИС.ПрочитатьДокумент. https://sbis.ru/help/integration/api/all_methods/read_doc
Выяснилась неприятная особенность. Метод СБИС.СписокСлужебныхЭтапов с фильтром ТолькоОтчетность=Да получает только первичное появление статуса по Требованию.
Но если пользователь в кабинете СБИС откроет данный документ, то информация о появлении Требования перестает попадать в ответ запроса этим методом.
Поэтому для получения, уже прочитанных пользователями Требований, обратились за помощью в поддержку СБИС, которая сначала ответила, что Требования получить никак нельзя.
Но позже прислала письмо с разъяснениями, что нужно использовать метод СБИС.СписокИзменений с параметром Тип=ИстребованиеФНС.
Данный способ полностью решил нашу проблему.
Следует отметить, при тестах выполнения запросов в Postman легко не заметить, что запрос возвращает несколько объектов внутри массива “Документ”
Хотя при чтении ответа средствами 1С содержимое массива отображается корректно и полностью.
Запрос СБИС.СписокИзменений выдает постраничный ответ. И если параметр “ЕстьЕще” равен “Да”, то для получения следующей страницы в запросе необходимо передать идентификатор последнего документа из массива ”Документ” предыдущего запроса.
3. Получатели и Доверители
К сожалению, скрины к данному описанию нет возможности разместить из-за требований конфиденциальности.
Учетная запись СБИСоформляется на одну организацию по ИНН/КПП. При этом в учетной записи документооборот может происходить по нескольким организациям (если позволяет тариф).
Когда мы пытались получить Требования по организациям одного из аккаунтов СБИС , обнаружили, что по некоторым организациям Требования есть в личном кабинете, но отсутствуют в ответах API.
Метод СБИС.СписокИзменений изначально выполняли по каждой организации аккаунта, подставляя в запрос их ИНН/КПП. В ответе по некоторым организациям был всегда пустой список документов.
В чем заключалась проблема? Оказывается, в СБИС есть такие понятия, как:
- Доверитель - это организация, которая поручает другой организации получать и отправлять свои документы по ЭДО.
- Получатель - организация, которая получила такую доверенность от Доверителя.
В личном кабинете СБИС такие Требования в отборах по Доверителюне отображаются, но они находятся среди документов Получателя
Аналогично в ответах API мы получали Требования других организаций как входящие документы, адресованные главной организации аккаунта.
При этом в ответе нет явного реквизита, позволяющего определить фактическую организацию этого документа.
После изучения проблемы было определено, что у документа Требование в реквизитах есть список Событий.
У каждого События список Вложений. При участии Требования в цикле обмена у одного из вложений имя файла содержит ИНН фактической организации.
Таким непростым способом получилось идентифицировать Требования организаций Доверителей и корректно отобразить их в нашей программе.
4.Получение сверок с ФНС по задолженности
Данный функционал довольно успешно используется нашей программой Tardis в базах 1С, где выполняется ежемесячное формирование и отправка запросов на сверку в ФНС и последующее получение и анализ задолженности по организациям.
Выполнять запросы сверок с ФНС через API СБИС нет возможности.
Но в ЛК СБИС есть возможность настроить автоматическое формирование и отправку запросов сверок.
Т.е. для нас оставалось разработать поиск и парсинг уже полученных в ЛК СБИС сверок.
Изначально данные сверок с ФНС получали методомСБИС.СписокДокументов с параметром Тип=ЗапросФНС и последующим поиском в выборке документов, где
Направление = "Входящий" и Вложение.Подтип = "1160080" и чтением данных найденных сверок методом СБИС.ПрочитатьДокумент
Оказалось, что таким способом можно получить только документы “Справка о состоянии расчетов с ФНС” по аккаунтам, у которых включена услуга "Супер-сверка"
Чтобы получать данные сверок из документов “Выписка расчетов с ФНС” без покупки дополнительных лицензий клиентами, мы разработали поиск выписок и получение данных из их содержимого.
Для этого массива документов со Справками (Тип=ЗапросФНС) мы добавили поиск Выписок. Фильтр: Документ.Примечание = НСтр("ru='Выписка операций по расчетам с бюджетом'", "ru") и Документ.Состояние.Код = "7"
Коды состояний документов: https://sbis.ru/help/integration/api/reporting/guides#code_con
Из найденных и прочитанных документов мы получаем ссылки на сами файлы сверок.
Скачиваем их во временный каталог и парсим для получения данных о задолженности, которые потом отображаем в нашей программе по всем организациям аккаунта.
5. Проверка организации в аккаунте
При выполнении всех запросов к API СБИС в параметрах всегда передаются ИНН и КПП.
Иногда КПП организации меняется или организация переводится в другой аккаунт СБИС
Поэтому для проверки актуальности организации в аккаунте и соответствия ИНН и КПП организации в нашей программе мы используем запрос методом СБИС.СписокНашихОрганизаций.
https://sbis.ru/help/integration/api/all_methods/company
6. Ограничение по количеству запросов в минуту
API СБИС имеет лимит по количеству запросов к сервису равный 300 запросов в минуту.
Эту проблему решили просто. Сделали паузу 0,5 секунд перед выполнением каждого запроса. Таким образом запросов в минуту никогда не будет больше 120.
7. Формат результата разный
В процессе отладки взаимодействия с API СБИС обнаружили, что в случае ошибки, ответ не всегда приходит в виде описанного в документации объекта (Структуры).
Иногда объект Error является строкой!
Это тоже необходимо учитывать при обработке ответов API СБИС.
Заключение
API СБИС имеет довольно обширный функционал, которым удобно пользоваться при разработке интеграций. И несмотря на пробелы в документации и поддержке, из него можно получить практические всё, что необходимо.