Как настроить интеграцию с API «Такском ОФД» для загрузки чеков и смен в 1С?

← На главную

При автоматизации розничной торговли перед разработчиками часто встает задача автоматического сбора данных из личного кабинета ОФД. Это особенно актуально для крупных торговых сетей, имеющих десятки и сотни торговых точек и кассовых аппаратов, где ручной сбор отчетов за смену физически невозможен. Получение данных напрямую через API «Такском ОФД» позволяет автоматизировать создание документов «Отчет о розничных продажах» в 1С. Однако при проектировании такой интеграции разработчики часто сталкиваются со специфическими ограничениями API.

В этой статье мы подробно разберем, как устроена работа со сменами и чеками в актуальной версии API «Такском ОФД» (v2), как правильно организовать архитектуру запросов, избежать блокировок со стороны ОФД за превышение лимитов (Rate Limits), а также приведем примеры кода на языке 1С для авторизации и получения данных. Для интерактивной отладки и проверки таких запросов внутри базы можно использовать встроенный HTTP-клиент для 1С.

Анализ проблемы: Агрегированные отчеты против парсинга каждого чека

Основной вопрос, возникающий у разработчиков: можно ли получить из API ОФД уже готовый сгруппированный отчет по продажам товаров, или необходимо скачивать абсолютно все чеки по кассе и самостоятельно сворачивать их в 1С?

Проанализируем техническую архитектуру «Такском ОФД». В системе реализовано четкое разделение на получение списков смен, сводных данных по сменам и детального контента чеков:

Сводные данные по сменам: Позволяют оперативно получить финансовые итоги дня без детальной номенклатурной аналитики.
Детализация по чекам (корзина): Требуется для полноценного заполнения табличной части «Товары» в документе 1С. В самом API «Такском» отсутствует готовый метод группировки продаж по товарам за период. Это означает, что если вам необходим точный товарный состав для управленческого или бухгалтерского учета, вам придется выгружать контент каждого фискального документа по отдельности и парсить корзину чека на стороне 1С.

Основные методы API v2.x «Такском» для работы с данными

Рассмотрим ключевые методы API, которые нам понадобятся для построения полноценной системы импорта данных:

/API/v2/ShiftList (Получение списка смен): Этот метод возвращает информацию обо всех сменах за выбранный период по конкретному фискальному накопителю (ФН). Он отдает метаданные: номера смен, даты и время их открытия и закрытия, а также общее количество чеков в каждой смене.
/API/v2/ShiftInfo (Сводные данные по смене): Пожалуй, самый важный метод для быстрой сверки. Он возвращает агрегированные финансовые показатели по конкретной смене: общие суммы прихода и возврата прихода (с разделением на наличный и безналичный расчет), общее число позиций, статус смены, а также разбивку сумм по ставкам НДС (20%, 10%, 0%, Без НДС). Использование этого метода избавляет от необходимости скачивать все чеки, если цель интеграции — просто сверить общую выручку смены в 1С и ОФД.
/API/v2/DocumentList (Список документов по смене): Позволяет получить перечень фискальных документов в рамках смены. Метод отдает краткие сведения о каждом чеке (номер ФД, сумма чека, признак расчета, СНО, ФИО кассира), но не содержит список проданных товаров.
/API/v2/Document (Детализация чека): Метод для получения полной XML- или JSON-структуры конкретного чека, включая наименования товаров, количество, цену, примененные скидки и маркировку (коды КМ/GTIN).

Практическая реализация авторизации в API из 1С

Для взаимодействия с серверами «Такском» необходимо пройти авторизацию. Существует два способа получения доступа:

Использование постоянного статического ключа (AuthToken): Его можно сгенерировать непосредственно в Личном кабинете ОФД в разделе «Управление передачей данных». Срок его действия составляет 1 год. Он передается в параметрах GET-запросов.
Использование временного токена сессии (Session-Token): Получается путем POST-запроса к методу /API/v2/Login с использованием учетных данных договора ОФД и уникального идентификатора интегратора (INTEGRATOR_ID), который выдается технической поддержкой Такскома по запросу.

Рассмотрим пример функции на языке 1С для прохождения авторизации и получения временного токена сессии:


// Функция выполняет авторизацию в API Такском ОФД и возвращает токен сессии
Функция ПолучитьТокенСессииТакском(Логин, Пароль, НомерДоговора, ИдентификаторИнтегратора) Экспорт
    
    ИмяСервера = "lk-ofd.taxcom.ru";
    РесурсАвторизации = "/API/v2/Login";
    
    // Используем защищенное SSL-соединение
    ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
    Соединение = Новый HTTPСоединение(ИмяСервера, 443,,,,, ЗащищенноеСоединение);
    
    // Формируем структуру параметров
    ПараметрыТела = Новый Структура;
    ПараметрыТела.Вставить("login", Логин);
    ПараметрыТела.Вставить("password", Пароль);
    ПараметрыТела.Вставить("agreementNumber", НомерДоговора);
    ПараметрыТела.Вставить("integratorId", ИдентификаторИнтегратора);
    
    // Преобразуем структуру в JSON-строку
    ЗаписьJSON = Новый ЗаписьJSON;
    ЗаписьJSON.УстановитьСтроку();
    ЗаписатьJSON(ЗаписьJSON, ПараметрыТела);
    ТелоЗапроса = ЗаписьJSON.Закрыть();
    
    // Настраиваем HTTP-запрос
    HTTPЗапрос = Новый HTTPЗапрос(РесурсАвторизации);
    HTTPЗапрос.Заголовки.Вставить("Content-Type", "application/json");
    HTTPЗапрос.УстановитьТелоИзСтроки(ТелоЗапроса, КодировкаТекста.UTF8);
    
    Попытка
        Ответ = Соединение.ОтправитьДляОбработки(HTTPЗапрос);
        Если Ответ.КодСостояния = 200 Тогда
            ЧтениеJSON = Новый ЧтениеJSON;
            ЧтениеJSON.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8));
            ДанныеОтвета = ПрочитатьJSON(ЧтениеJSON);
            Возврат ДанныеОтвета.sessionToken;
        Иначе
            ВызватьИсключение "Ошибка HTTP: " + Ответ.КодСостояния + " " + Ответ.ПолучитьТелоКакСтроку();
        КонецЕсли;
    Исключение
        ЗаписатьВЖурналРегистрации("ТакскомОФД.Авторизация", УровеньЖурналаРегистрации.Ошибка,,, ОписаниеОшибки());
        ВызватьИсключение "Не удалось авторизоваться в сервисе Такском ОФД. Подробности в журнале регистрации.";
    КонецПопытки;
    
КонецФункции

Реализация загрузки сводных данных по кассовой смене

После получения токена сессии мы можем обратиться к методу получения сводных данных по смене. Это позволит быстро сверить общую выручку с кассовой книгой в 1С или автоматически отразить общие суммы продаж (если детальный учет номенклатуры ведется по упрощенной схеме). Разберем пример отправки запроса /API/v2/ShiftInfo:


// Функция получает финансовые итоги смены по номеру ФН и номеру смены
Функция ПолучитьДанныеСмены(ТокенСессии, ЗаводскойНомерФН, НомерСмены) Экспорт
    
    ИмяСервера = "lk-ofd.taxcom.ru";
    // Формируем GET-запрос с параметрами в адресе ресурса
    Ресурс = СтрШаблон("/API/v2/ShiftInfo?fn=%1&shiftNumber=%2", ЗаводскойНомерФН, Формат(НомерСмены, "ЧГ=0"));
    
    ЗащищенноеСоединение = Новый ЗащищенноеСоединениеOpenSSL();
    Соединение = Новый HTTPСоединение(ИмяСервера, 443,,,,, ЗащищенноеСоединение);
    
    HTTPЗапрос = Новый HTTPЗапрос(Ресурс);
    HTTPЗапрос.Заголовки.Вставить("Content-Type", "application/json");
    // Передаем токен авторизации в заголовке запроса
    HTTPЗапрос.Заголовки.Вставить("Session-Token", ТокенСессии);
    
    Попытка
        Ответ = Соединение.Получить(HTTPЗапрос);
        Если Ответ.КодСостояния = 200 Тогда
            ЧтениеJSON = Новый ЧтениеJSON;
            ЧтениеJSON.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку(КодировкаТекста.UTF8));
            РезультатДанных = ПрочитатьJSON(ЧтениеJSON);
            Возврат РезультатДанных;
        Иначе
            ВызватьИсключение "Не удалось получить сводные данные по смене. Код ответа: " + Ответ.КодСостояния;
        КонецЕсли;
    Исключение
        ЗаписатьВЖурналРегистрации("ТакскомОФД.ПолучениеДанныхСмены", УровеньЖурналаРегистрации.Ошибка,,, ОписаниеОшибки());
        Возврат Неопределено;
    КонецПопытки;
    
КонецФункции

Критически важный нюанс: Ограничения API на массовую выгрузку

Важное предупреждение от разработчиков Такском: Интерфейс API личного кабинета ОФД по умолчанию не предназначен для массовой фоновой выгрузки абсолютно всех чеков на регулярной основе для целей ведения полного товарного учета крупных торговых сетей. При попытке ежеминутно выгружать по API тысячи чеков с сотен касс вы столкнетесь с жестким лимитированием количества запросов (Rate Limits), а ваши запросы могут начать блокироваться сервером.

Для минимизации нагрузки на сервера ОФД и обеспечения стабильности интеграции в 1С рекомендуется придерживаться следующих правил:

Кэшируйте полученные данные: Не запрашивайте повторно чеки прошлых периодов, которые уже успешно загружены и проведены в системе 1С.
Используйте фискальный признак документа: Сверяйте уникальный фискальный признак документа (ФПД/ФП) при загрузке, чтобы гарантированно исключить появление дублирующихся документов в вашей базе данных 1С.
Выгружайте данные по расписанию в часы наименьшей нагрузки: Настраивайте регламентные задания в 1С на ночные часы, распределяя запросы по разным кассам во времени, чтобы избежать пиковых нагрузок на API.

Альтернативное решение: Официальный модуль «Синхронизация с 1С»

Если перед вами стоит задача автоматизации учета розничных продаж, но вы не хотите писать интеграцию с API «с нуля» и постоянно поддерживать ее при изменениях на стороне ОФД, обратите внимание на готовые решения. Такском поставляет официальный программный модуль «Синхронизация с 1С», выполненный в виде внешней обработки (формат .epf). В качестве более простого сценария без настройки прямого подключения к сервису подойдёт внешняя обработка для загрузки данных из отчетов EXCEL ОФД.

Основные возможности этой готовой интеграции:

Автоматическое формирование документов: Обработка самостоятельно опрашивает API ОФД, скачивает данные о продажах и формирует в вашей информационной базе документы «Отчет о розничных продажах», «Приходный кассовый ордер» и «Возврат товаров от покупателя».
Гибкое сопоставление номенклатуры: В модуле реализован механизм интеллектуального сопоставления текстовых названий товаров из чеков с элементами справочника «Номенклатура» в 1С. В случае отсутствия позиции система может создать ее автоматически.
Сворачивание на «Товар в ассортименте»: Для минимизации справочника номенклатуры в 1С можно настроить группировку всех продаж на одну общую виртуальную позицию.
Встроенная аналитика: Помимо формирования документов, модуль умеет строить визуальные аналитические отчеты по среднему чеку, выручке, динамике продаж и популярным товарам прямо внутри интерфейса 1С.

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

Мультиплатформенные ОФД-агрегаторы

В ситуациях, когда у предприятия кассовые аппараты распределены по нескольким разным операторам фискальных данных (например, часть ККТ подключена к «Такском», часть к «Контур.ОФД», часть к «Платформа ОФД»), написание и поддержка отдельных интеграций под каждый уникальный API становится крайне трудоемким процессом. В этом случае целесообразно рассмотреть использование мультиплатформенных агрегаторов (например, сервис «Мой.ОФД»). Такие сервисы аккумулируют данные со всех ваших личных кабинетов различных ОФД в единый интерфейс и предоставляют один универсальный стандартизированный API для выгрузки смен и чеков в 1С, значительно упрощая поддержку программного кода.