Особенности интеграции с API СБИС

Особенности интеграции с API СБИС

Введение

Наша команда занимается разработкой приложения Tardis (MCOB. Управление бухгалтерией). Приложение используется компаниями уполномоченных бухгалтерий для управления и комплексного взаимодействия c базами 1С, в которых ведется бухгалтерский учет по обслуживаемым организациям.

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

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

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

О недокументированных особенностях получения данных из СБИС.Онлайн и пойдет речь в этой статье.

Вся документация для разработки взаимодействия изучалась на официальном сайте СБИС https://sbis.ru/help/integration/api. В соответствии с ней выполнялась первоначальная авторизация для получения токена, выполнялись запросы с этим токеном, и после получения данных закрывался сеанс.

1. Получение регламентированных отчетов

Первой задачей было получить статусы регламентированных отчетов.

Сначала попробовали метод API отчетности СБИС.СписокИзменений https://sbis.ru/help/integration/api/reporting/commands/list_change

Но этот метод возвращал только документы ЭДО (счета, реализации, акты). Даже если установить параметр запроса ТолькоОтчетность=Да, как рекомендовала техподдержка СБИС, регламентированные отчеты получить не удавалось.

Поэтому попробовали использовать метод СБИС.СписокДокументов https://sbis.ru/help/integration/api/all_methods/list_doc , хотя техподдержка СБИС не всегда признает существование этого метода для отчетности

article-image

Для получения именно отчетов нашли способ - указывать в параметре Тип=ОтчетФНС или ОтчетПФР, хотя в документации данные типы документов не указаны https://sbis.ru/help/integration/catalog/guide#1

И техподдержка СБИС считает, что данные типы использовать нельзя

article-image

Тем не менее, таким способом нам удалось получать статусы по всем видам отчетов.

2. Получение Требований ФНС

В АПИ ЭДО СБИС мы не нашли метода, возвращающего список документов такого типа.

Изначально, мы пробовали получить Требования методом СБИС.СписокДокументов, но документы такого типа данным методом не возвращаются.

article-image

Однако, удалось получить новые Требования методом СБИС.СписокСлужебныхЭтапов. https://sbis.ru/help/integration/api/all_methods/stage_doc

и получить данные документа методом СБИС.ПрочитатьДокумент. https://sbis.ru/help/integration/api/all_methods/read_doc

article-image

Выяснилась неприятная особенность. Метод СБИС.СписокСлужебныхЭтапов с фильтром ТолькоОтчетность=Да получает только первичное появление статуса по Требованию.

Но если пользователь в кабинете СБИС откроет данный документ, то информация о появлении Требования перестает попадать в ответ запроса этим методом.

Поэтому для получения, уже прочитанных пользователями Требований, обратились за помощью в поддержку СБИС, которая сначала ответила, что Требования получить никак нельзя.

article-image

Но позже прислала письмо с разъяснениями, что нужно использовать метод СБИС.СписокИзменений с параметром Тип=ИстребованиеФНС.

Данный способ полностью решил нашу проблему.

Следует отметить, при тестах выполнения запросов в Postman легко не заметить, что запрос возвращает несколько объектов внутри массива “Документ”

article-image

Хотя при чтении ответа средствами 1С содержимое массива отображается корректно и полностью.

article-image

Запрос СБИС.СписокИзменений выдает постраничный ответ. И если параметр “ЕстьЕще” равен “Да”, то для получения следующей страницы в запросе необходимо передать идентификатор последнего документа из массива ”Документ” предыдущего запроса.

article-image

3. Получатели и Доверители

К сожалению, скрины к данному описанию нет возможности разместить из-за требований конфиденциальности.

Учетная запись СБИСоформляется на одну организацию по ИНН/КПП. При этом в учетной записи документооборот может происходить по нескольким организациям (если позволяет тариф).

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

Метод СБИС.СписокИзменений изначально выполняли по каждой организации аккаунта, подставляя в запрос их ИНН/КПП. В ответе по некоторым организациям был всегда пустой список документов.

В чем заключалась проблема? Оказывается, в СБИС есть такие понятия, как:

  1. Доверитель - это организация, которая поручает другой организации получать и отправлять свои документы по ЭДО.
  2. Получатель - организация, которая получила такую доверенность от Доверителя.

В личном кабинете СБИС такие Требования в отборах по Доверителюне отображаются, но они находятся среди документов Получателя

Аналогично в ответах API мы получали Требования других организаций как входящие документы, адресованные главной организации аккаунта.

При этом в ответе нет явного реквизита, позволяющего определить фактическую организацию этого документа.

После изучения проблемы было определено, что у документа Требование в реквизитах есть список Событий.

У каждого События список Вложений. При участии Требования в цикле обмена у одного из вложений имя файла содержит ИНН фактической организации.

Таким непростым способом получилось идентифицировать Требования организаций Доверителей и корректно отобразить их в нашей программе.

4.Получение сверок с ФНС по задолженности

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

Выполнять запросы сверок с ФНС через API СБИС нет возможности.

Но в ЛК СБИС есть возможность настроить автоматическое формирование и отправку запросов сверок.

Т.е. для нас оставалось разработать поиск и парсинг уже полученных в ЛК СБИС сверок.

Изначально данные сверок с ФНС получали методомСБИС.СписокДокументов с параметром Тип=ЗапросФНС и последующим поиском в выборке документов, где

Направление = "Входящий" и Вложение.Подтип = "1160080" и чтением данных найденных сверок методом СБИС.ПрочитатьДокумент

article-image

Оказалось, что таким способом можно получить только документы “Справка о состоянии расчетов с ФНС” по аккаунтам, у которых включена услуга "Супер-сверка"

article-image

Чтобы получать данные сверок из документов “Выписка расчетов с ФНС” без покупки дополнительных лицензий клиентами, мы разработали поиск выписок и получение данных из их содержимого.

Для этого массива документов со Справками (Тип=ЗапросФНС) мы добавили поиск Выписок. Фильтр: Документ.Примечание = НСтр("ru='Выписка операций по расчетам с бюджетом'", "ru") и Документ.Состояние.Код = "7"

Коды состояний документов: https://sbis.ru/help/integration/api/reporting/guides#code_con

article-image

Из найденных и прочитанных документов мы получаем ссылки на сами файлы сверок.

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

5. Проверка организации в аккаунте

При выполнении всех запросов к API СБИС в параметрах всегда передаются ИНН и КПП.

Иногда КПП организации меняется или организация переводится в другой аккаунт СБИС

Поэтому для проверки актуальности организации в аккаунте и соответствия ИНН и КПП организации в нашей программе мы используем запрос методом СБИС.СписокНашихОрганизаций.

https://sbis.ru/help/integration/api/all_methods/company

6. Ограничение по количеству запросов в минуту

API СБИС имеет лимит по количеству запросов к сервису равный 300 запросов в минуту.

Эту проблему решили просто. Сделали паузу 0,5 секунд перед выполнением каждого запроса. Таким образом запросов в минуту никогда не будет больше 120.

7. Формат результата разный

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

article-image

Иногда объект Error является строкой!

article-image

Это тоже необходимо учитывать при обработке ответов API СБИС.

Заключение

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

Сервисы 1С для работы с маркетплейсами