Инструкция об особенностях интеграции с API Saby

Введение

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

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

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

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

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

Вся документация для разработки взаимодействия изучалась на официальном сайте Saby. В соответствии с ней выполнялась первоначальная авторизация для получения токена, выполнялись запросы с этим токеном, и после получения данных закрывался сеанс.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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