Сервис онлайн-касс АТОЛ Онлайн: API и интеграция с CMS
Раскрываем общие детали работы с сетевым сервисом онлайн-касс, нюансы интеграции с CMS и подводные камни, об которые вы споткнетесь в случае, если не станете использовать готовые решения и будете заниматься интеграцией самостоятельно.
Согласно 54-ФЗ, все торгово-сервисные площадки, принимающие оплату через интернет, должны перейти на онлайн-кассы, отправляющие в режиме реального времени электронные чеки в ФНС. С 1 июля 2017 года это требование касается не только интернет-магазинов, но и самых разнообразных онлайн-сервисов, собирающих оплату с физических лиц с помощью банковских карт, а с 1 июля 2018 изменения затронут и тех, кто пользуется услугами альтернативных платежных средств (онлайн кошельков) — Webmoney, Яндекс.Деньги и др.
Хотя переход на новые кассы уже должен был состояться, данные ФНС говорят о том, что львиная доля торгово-сервисных площадок в интернете все еще не легализовала онлайн-расчеты с потребителями. По официальной статистике, на учете стоит около 14 тыс. кассовых аппаратов с признаком «расчеты в сети Интернет», в то время как сегмент рынка, по разным данным, насчитывает не менее 50 тыс. предприятий (здесь речь идет только о тех компаниях, которые принимают платежи через интернет от физических лиц).
Таким образом, более половины компаний пока не озаботились фискализацией расчетов. Одни онлайн-площадки остаются в тени, рассчитывая, что в переходный период они не заинтересуют ФНС, другие же, чтобы не нарушать закон, просто отключили прием онлайн-платежей.
Мы много пишем о том, как все сделать законно. Сегодня поговорим о деталях взаимодействия наших касс в рамках сервиса АТОЛ Онлайн с внутренними системами интернет-магазинов.
Вкратце о сервисе
Покупка онлайн кассы — мероприятие не дешевое. Доступная альтернатива покупке — аренда («онлайн-касса как сервис»). Именно эту услугу и предоставляет АТОЛ Онлайн.
Идея сервиса похожа на SaaS, но в данном случае из-за ограничений 54-ФЗ речь идет не об аренде виртуальных мощностей, а о временном использовании вполне реальной (физической) кассы, размещенной в нашем ЦОДе.
По договору одна или несколько касс резервируются за клиентом и ставятся им на учет через личный кабинет налогоплательщика на сайте ФНС.
Хотя сегодня существуют альтернативные сервисы аренды, АТОЛ Онлайн в 2017 году стал первым в данном сегменте рынка. На текущий момент примерно каждая третья касса, зарегистрированная в ФНС для расчетов в сети Интернет, арендована у АТОЛ.
Количество касс, необходимое каждому конкретному магазину, зависит от объемов передаваемой в ФНС информации — то есть фактически от количества заказов, обрабатываемых в единицу времени. Управление очередью документов на кассы осуществляется на стороне сервиса — они равномерно распределяются по имеющимся аппаратным ресурсам. Рекомендации и калькулятор для подсчета приблизительного количества единиц техники есть на нашем сайте.
Сервис позволяет оценивать параметры очереди из документов на кассах (скорость обработки каждого документа), из чего можно делать выводы о том, верно ли было рассчитано количество касс. Рост очереди необработанных документов — явный признак того, что объемы арендуемых ресурсов должны быть увеличены.
Как и «классические» сервисы аренды программного обеспечения или инфраструктуры, сервис допускает гибкое масштабирование ресурсов, доступных конечному пользователю. Однако из-за требований по регистрации каждой кассы в ФНС на конкретную компанию, процедура масштабирования имеет некоторые особенности.
В случае отказа от излишних ресурсов процедура выполняется быстро. Однако архив ФН, использующегося в «лишней» кассе, придется закрыть, а саму кассу снять с учета в ФНС (неиспользуемая касса с большой вероятностью будет передана другому клиенту, а ФН, хоть и действует 13 месяцев, жестко закрепляется за компанией и физической кассой — таким образом с другой кассой для расширения парка арендованной техники за счет произвольной кассы использовать его нельзя).
При увеличении количества касс процедура немного растягивается во времени. Поскольку субъекту налогообложения требуется ставить на учет в ФНС каждую кассу самостоятельно (через личный кабинет на nalog.ru), скорость, с которой будут предоставлены дополнительные ресурсы, зависит в том числе и от самого магазина. В принципе, это возможно сделать в течение суток.
Масштабирование открывает возможность гибко варьировать количество касс, прогнозируя пиковые нагрузки. Хотя это только один из вариантов работы. Большая часть магазинов предпочитает другой подход — рассчитывать количество постоянно арендованных касс, учитывая в том числе и пиковые нагрузки. Вне пиков оборудование используется не на полную силу, но зато такая схема обеспечивает большую отказоустойчивость.
Зачем и кому необходимо API
Помимо самого использования онлайн касс, 54-ФЗ регламентирует новые параметры кассового чека — дополнительные реквизиты и обязательное отражение в документе всех товарных позиций с соответствующими ставками налога. Вне зависимости от того, приобретена касса в собственность компании или взята в аренду, информация о товарных позициях и их итоговой стоимости (со всеми скидками и надбавками, а заодно со ставкой налога) должна поступать в нее из внешней системы — из CMS магазина или сервисной площадки. Тонкости этого процесса зависят от деталей задачи, но в общем случае обеспечение интеграции CMS и онлайн-кассы, как в присутствии платежного агрегатора, так и без него — это технически нетривиальная задача.
С самого начала АТОЛ Онлайн предложил открытый универсальный API для взаимодействия со сторонними системами. С рядом популярных CMS и платежных агрегаторов у сервиса уже есть готовая интеграция «из коробки» (причем список партнеров постоянно пополняется). То есть для магазина, который только что решил привести свою деятельность в соответствие с действующим законодательством, это упрощает процедуру: если используется популярная CMS, с большой долей вероятности разбираться в деталях API не придется, можно будет использовать готовый модуль. А покупая с нуля готовое решение (CMS) или выбирая платежного агрегатора, можно подобрать инструмент с уже реализованной интеграцией с онлайн-кассой.
Интегрированные платежные агрегаторы и банки: Сбербанк, Яндекс Касса, RoboKassa, RBKmoney, РайффайзенБанк, Тинькофф, Газпромбанк и другие.
API как таковой будет интересен тем, кто использует самописные инструменты. В свое время целый ряд компаний (в основном — крупные) вместо приобретения сторонней CMS-системы выбрали путь написания собственной. Им-то и приходится работать с API напрямую. С нашей точки зрения этот сегмент пользователей самый сложный, поскольку самописные CMS немного по-разному обрабатывают процессы, могут выдавать не ту информацию и т.п. И с каждым клиентом здесь отдельный проект.
Детали API
Попробуем, не погружаясь в детали, рассказать, что собой представляет API АТОЛ Онлайн.
Общение с онлайн-кассой в рамках API состоит из трех частей:
До недавнего времени в API АТОЛ Онлайн было собственное ограничение в 100 товарных позиций в чеке, позволявшее с запасом уложиться в предписанные 30 КБ. Но поскольку эксплуатация сервиса показала, что для некоторых клиентов ограничение в 100 товаров играет существенную роль, оно было снято. Теперь магазинам необходимо самостоятельно контролировать переполнение чека — то есть требуется принимать и обрабатывать соответствующую ошибку от АТОЛ онлайн. В особенности это касается магазинов, где покупатель может набрать в корзину большое количество мелких штучных товаров (крепеж, электронные компоненты и т.п.), или площадок, где популярны коллективные закупки (учебники и канцелярия на целый школьный класс).
Технически чеки более 30 Кбайт в онлайн торговле обрабатываются также, как и в офлайн торговле, где кассир просто разбивает корзину на два чека. Однако эта логика должна находиться на стороне внешней системы — т.е. магазина, поскольку АТОЛ Онлайн может лишь выдать ошибку о том, что фискализация не выполнена (по закону нельзя два чека оплатить через одну транзакцию).
В дополнение к перечисленной выше информации через API магазин должен предоставить телефон или email пользователя, куда будет отправлен электронный чек.
По закону именно интернет-магазин должен обеспечить возможность доставки электронного чека покупателю, то есть его обязанность — выяснить адрес для доставки (хотя, конечно, ритейлер понесет ответственность, если пользователь указал заведомо некорректные данные). Непосредственно доставку он может делегировать ОФД или осуществить самостоятельно. В последнем случае обратно через API после фискализации передаются признаки фискального документа, по которым электронный чек можно найти в ФНС или у ОФД.
API доставляет уведомления о том, что документ передан на фискализацию — то есть он отстоял в очереди и отправился на кассу — или, наоборот, возвращен с ошибкой, например, по таймауту (в том случае, если очередь слишком большая и он в течение пяти минут так и не дошел до кассы). Время, которое документы в среднем проводят в очереди, является хорошим маркером того, достаточно ли касс арендовал магазин.
Надо отметить, что сервис АТОЛ Онлайн предоставляет более широкий функционал через личный кабинет. Там доступна различная статистика, а также сами фискализированные чеки. Позже подобный функционал появится и в API. Кроме того, предполагается сделать механизм сверки.
Что нужно интернет-магазину, помимо API
Работа с онлайн-кассами на практике упирается не столько в поиск оборудования и настройку взаимодействия по API, сколько в изменение некоторых бизнес-процессов внутри магазина.
В первую очередь необходимо подготовиться к передаче корзины на сторону для фискализации. До сих пор многие магазины работают с платежными системами, просто передавая сумму к оплате. Легально продолжать работать по такой схеме уже нельзя. Нужно указывать весь перечень товаров в корзине. И если покупатели в магазине интим-услуг будут рады замене названий реальных сервисов на абстрактные «услуга 1», «услуга 2» и так далее, то потребители в магазине бытовой техники вряд ли обрадуются, когда вместо реальных товаров в чеке появится ерунда.
Каждый товар в чеке должен иметь окончательную цену уже после применения всех скидок и надбавок. Раньше касса могла сама посчитать скидку, теперь же этого делать нельзя. Вдобавок, во многих CMS такая логика просто не заложена, поэтому здесь требуются серьезные доработки.
Помимо названий и цен, как было упомянуто выше, надо передавать ставку налога. С этим были сложности даже у крупных офлайн-магазинов. Это был настоящий вызов для их внутренней системы автоматизации, поскольку раньше такая информация нигде не требовалась и не учитывалась, и, соответственно, не контролировалась. Порой логист, который принимает товар, просто по привычке оставлял ставки налога по-умолчанию, потому что привык так работать. Но для корректной работы связки CMS с онлайн-кассой необходимо, чтобы везде была заложена «правильная» математика (соответствующая моделям 54-ФЗ). Без этого чеки просто не будут фискализироваться.
Хороший пример несоблюдения мат-моделей — округление. Спецификация подразумевает передачу копеек в виде двух знаков после запятой. Но многие из собственных систем передают четыре и даже пять знаков. АТОЛ Онлайн лишние знаки отбрасывает, в то время как в собственной системе магазина при подсчете итоговой суммы может производиться округление по математическим правилам. Так проявляется расхождение в несколько копеек, которое не пройдет по кассе. И такие ошибки очень тяжело отлавливать.
Еще одно обязательное изменение — упомянутое требование номера мобильного телефона или адреса электронной почты у пользователя. Без этих данных фискализации не будет. До сих пор в нашу систему поступает довольно много чеков без идентификационных данных (их доля достигает единиц процентов). После отправки подобного «анонимного» чека интернет-магазин получает сообщение об ошибке, но ничего поделать не может, поскольку транзакция уже прошла. В этом случае все «чисто» можно сделать только через отмену платежной операции (или же чек можно дослать позднее — с правильными реквизитами).
В итоге затраты на саму интеграцию CMS и онлайн-кассы могут оказаться намного меньше, нежели на перестройку всей информационной системы под требования федерального закона. И к этому надо быть готовым.
Конвертер программного интерфейса приложений (API) для «АТОЛ Онлайн»
Введение
Документ описывает сценарий использования программного интерфейса приложений (API ) сервиса «АТОЛ Онлайн» для информационной системы «Ferma».
1. Общая информация по API
Кодировка, используемая в запросах и ответах, – UTF-8. Запросы выполняются методами POST и GET, параметры запроса располагаются в структуре данных формата JSON, передаваемой в блоке данных запроса (при использовании POST), также параметры могут передаваться в строке запроса (при использовании GET).
Ответы выдаются сервером в формате JSON и, в случае успешности ответа согласно его заголовку (код ответа по протоколу HTTP равен 200).
2. Авторизация через getToken
Возможность множественных обращений к конвертеру «АТОЛ Онлайн» после одной авторизации без использования механизма Cookies реализуется с помощью механизма AuthToken: после авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, которая используется, как параметр авторизации при обращении к соответствующему личному кабинету (ЛК).
Параметры запроса:
Content-Type: application/json
charset=utf-8
Тело запроса представляет собой структуру JSON, содержащую:
В данном запросе присутствуют примеры значений: Login – «12345» и Password – «56789». Они задаются как значения в JSON-структуре внутри запроса.
Их можно получить в личном кабинете клиента в разделе «Ferma», после покупки кассы Ferma, либо у вашего менеджера.
Момент времени задается в формате «ДД-ММ-ГГГГ чч:мм:сс»:
ДД – день даты, 2 цифры,
ММ – месяц даты, 2 цифры,
ГГГГ – год даты, 4 цифры,
чч – часы, 2 цифры,
мм – минуты, 2 цифры,
сс – секунды, 2 цифры.
Пример ответа с ошибкой:
Доступ к кассам по полученному параметру “token” происходит в соответствии с правами доступа, заданными для пользователя, чьи имя и пароль были использованы в процессе генерации параметра “token”. Права пользователя могут быть заданы одновременно для ЛКК нескольких юридических лиц, при этом функции описываемого здесь программного интерфейса приложений (API ), связанные со сбором данных по ККТ будут возвращать данные только по тем единицам ККТ, доступ к которым разрешен согласно используемому значению параметра “token”.
Пример запроса с использованием кода авторизации:
3. Создание чеков
Запрос на создание чеков с использованием конвертера «АТОЛ Онлайн»:
Тело запроса представляет собой структуру JSON, содержащую необходимые параметры и имеющую следующий обобщенный вид:
Параметры структуры приведены в таблице 1.
Таблица 1. Параметры структуры запроса на формирование кассового чека с использованием конвертера «АТОЛ Онлайн»
Таблица 1.2 Параметры элементов структуры «agent_info»
Таблица 1.3 Параметры элементов структуры «items»
В ответ на POST запрос возвращается структура данных в формате JSON, содержащая уникальный идентификатор, присвоенный данному документу и статус.
Параметры элементов структуры ответа описаны в таблице 2.
Способы получения результатов обработки документа по уникальному идентификатору описаны в разделе 4. Пример ответа:
Пример ответа с ошибкой:
Таблица 2. Параметры структуры ответа на проксирование чеков
Программный интерфейс приложений (API) для работы с ИС «Чеки и ККТ»
Введение
1. Авторизация через AuthToken
Возможность множественных обращений к ИС «Чеки и ККТ» после одной авторизации без использования механизма Cookies реализуется с помощью механизма AuthToken: после авторизации с передачей имени и пароля система возвращает код авторизации – строку символов, которая используется, как параметр авторизации при обращении к соответствующему личному кабинету (ЛК). HTTP-запрос авторизации, передающий имя пользователя и пароль в формате JSON выглядит следующим образом:
В данном запросе присутствуют примеры значений: передаваемое имя пользователя – «12345» и пароль – «56789»; они задаются как значения в JSON-структуре внутри запроса с ключами «Login» и «Password» соответственно.
Другой формат запроса, обрабатываемый ИС «Чеки и ККТ»: HTTP-запрос авторизации в формате URLEncoded:
На данный запрос будет получен ответ по протоколу HTTP, который в случае успешной авторизации будет иметь код равный 200 и содержать структуру, подобную следующей (приведены примеры значений):
В случае проблем с авторизацией (код ответа по протоколу HTTP будет равен 403) данные будут отсутствовать, JSON-структура будет пустой (будет иметь вид «<>»). Полученный код авторизации используется в виде дополнительного параметра в запросах документов для сверки, где необходима авторизация.
Доступ к кассам по полученному ключу “AuthToken” происходит в соответствии с правами доступа, заданными для пользователя, чьи имя и пароль были использованы в процессе генерации ключа “AuthToken”. Права пользователя могут быть заданы одновременно для ЛКК нескольких юридических лиц, при этом функции описываемого здесь программного интерфейса приложений (API ), связанные со сбором данных по ККТ будут возвращать данные только по тем единицам ККТ, доступ к которым разрешен согласно используемому значению ключа “AuthToken”.
Пример запроса с использованием кода авторизации:
Здесь:
INN – идентификационный номер налогоплательщика (ИНН) юридического лица, о котором производится запрос. Строка состоит из 10 цифр от 0 до 9.
Code – действующий код авторизации, полученный в результате запроса авторизации.
2. Запросы к ИС на получение информации по чекам и ККТ
Запросы (функции) программного интерфейса приложений ИС «Чеки и ККТ» реализуют функции, необходимые в процессе работы различных ИС, использующих кассы и работающих с кассовыми документами. Большинство запросов имеет схожий формат и особенности структуры входных и выходных данных, если входные и выходные данные будут отличаться, это будет описываться дополнительно. Обобщенно формат запроса и ответа описан ниже.
С помощью запросов программного интерфейса приложений ИС «Чеки и ККТ» можно получать информацию о чеках и ККТ. Кодировка, в запросах и ответах – UTF-8. Ответы выдаются сервером в формате JSON, и, в случае успешности ответа, согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:
Здесь параметр «Status» – состояние обработки запроса, в данном случае имеет значение «Success» (запрос обработан успешно).
Ключу «Data» соответствует структура, где «Prop1», «Prop2», … «PropN» и «Val1», «Val2», … «ValN» — ключи передаваемых параметров с их значениями (см. описания параметров ниже; значениями параметров могут являться массивы и структуры).
Параметр «Elapsed» — время, затраченное системой на обработку запроса: от получения запроса системой до выдачи ответа.
Формат времени — строка вида «чч:мм:сс.ддддддд», в которой:
чч – часы,
мм – минуты,
сс – секунды,
ддддддд – доли секунды.
В случае неуспешного ответа (код ответа по протоколу HTTP не равен 200) данные имеют следующий обобщенный вид:
Здесь параметр «Status» в данном случае имеет значение «Failed» (обработка запроса не удалась).
Ключу «Errors» соответствует одномерный массив, в котором присутствуют строки с сообщениями об ошибках, возникших при обработке данных.
На месте строк «Ошибка 1», «Ошибка 2», … «Ошибка N» перечислены сообщения об ошибках, возникших при обработке переданных данных.
Параметр «Elapsed» – так же, как и в случае успешного ответа, время, затраченное системой на обработку запроса.
Формат представления времени тот же.
2.1. Запрос информации о KKT
Запрос на получение информации по ККТ имеет вид:
Здесь:
INN – идентификационный номер налогоплательщика (ИНН) юридического лица, о котором производится запрос. Строка состоит из 10 цифр от 0 до 9.
FNumber – номер фискального накопителя.
KKTNumber – заводской номер кассы.
KKTRegNumber – регистрационный номер кассы.
Code – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос возвращается структура данных JSON следующего примерного вида (приведены примеры значений, многоточие означает многократно повторяющуюся структуру такого же вида):
Список полей этой структуры c их описаниями представлен в таблице 1.
Таблица 1. Поля данных записи с информацией о ККТ
| Идентификатор | Формат поля | Назначение |
|---|---|---|
| Id | Строка | Уникальный номер ККТ (кассы) |
| KktRegId | Строка | Регистрационный номер ККТ (кассы) |
| KktName | Строка | Название кассы |
| SerialNumber | Строка | Заводской (серийный) номер ККТ (кассы) |
| ActivationDate | Дата и время в формате ISO | Дата успешной проверки регистрационного номера в ФНС |
| ContractStartDate | Дата и время в формате ISO | Дата начала действия контракта на получение услуг оператора “OFD.ru” |
| ContractEndDate | Дата и время в формате ISO | Дата окончания действия контракта на получение услуг оператора “OFD.ru” |
| CreateDate | Дата и время в формате ISO https://en.wikipedia.org/wiki/ISO_8601). Здесь используется только формат представления времени без задания смещения часовых поясов (Time Zone Offset) и интервалов.»>2) | Дата регистрации кассы в личном кабинете клиента |
| FnNumber | Строка | Номер фискального накопителя |
| SignDate | Дата и время в формате ISO | Дата подписания договора |
| PaymentDate | Дата и время в формате ISO | Дата оплаты услуг ОФД для кассы |
| CheckDate | Дата и время в формате ISO | Дата подписания КЭП (квалификационной электронной подписью) |
| LastDocOnKktDateTime | Дата и время в формате ISO | Дата и время последнего документа, сгенерированного кассой (по локальному времени кассы) |
| LastDocOnOfdDateTimeUtc | Дата и время в формате ISO | Дата и время получения последнего документа кассы в ОФД (по времени оператора “OFD.ru” в UTC) |
| FirstDocumentDate | Дата и время в формате ISO | Дата и время генерации кассой первого документа |
| FiscalAddress | Строка | Адрес установки кассы |
| FiscalPlace | Строка | Место расчетов |
| Path | Строка | Иерархия расположения кассы в личном кабинете клиента |
| KktModel | Строка | Модель кассы (ККТ) |
| FnEndDate | Дата и время в формате ISO | Дата и время окончания работы фискального накопителя |
Ошибка в ответе на запрос, обрабатываемая ИС:
InnNotFound – для текущей учетной записи не найдено юридическое лицо по заданному ИНН.
2.2. Запрос списка отчетов по смене для заданной кассы за период
Запрос на получение списка отчетов по смене (z-отчетов) по заданной кассе за период имеет вид:
Здесь:
INN – ИНН юридического лица. Строка состоит из 10 цифр от 0 до 9.
KKT – регистрационный номер кассы – строка символов.
Date1 и Date2 – начальная дата и конечная дата периода для формирования отчета, значения содержат дату и время в формате ISO. Разность Date2 и Date1 не должна превышать 30 дней, дата начала и дата конца периода формирования отчета не должны быть одинаковые.
Code – действующий код авторизации, полученный в результате запроса авторизации.
Частота отправки запроса не должна превышать более 1 запроса в секунду.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (приведены примеры значений, многоточие означает многократно повторяющуюся структуру такого же вида):
Описание параметров структуры ответа представлен в таблице 2.
Таблица 2. Поля данных записи с информацией о ККТ
| Идентификатор | Формат поля | Назначение |
|---|---|---|
| Id | Строка в формате UUID | Идентификатор смены |
| Open_CDateUtc | Дата и время в формате ISO | Дата и время отчета об открытии смены |
| Close_CDateUtc | Дата и время в формате ISO | Дата и время отчета о закрытии смены |
| UserInn | Строка, 10 или 12 цифр | ИНН владельца кассы |
| KktRegNumber | Строка | Регистрационный номер кассы |
| FnNumber | Строка | Номер фискального накопителя, установленного в кассу |
| ShiftNumber | Целое число | Номер смены по данным кассы |
| Operator | Строка | Фамилия, имя, отчество оператора |
| Open_DocNumber | Целое число | Фискальный номер документа отчета об открытии смены, присвоенный кассой (уникальный в рамках текущего фискального режима) |
| Open_DocDateTime | Дата и время в формате ISO | Дата и время формирования отчета об открытии смены по данным кассы |
| Open_DocRawId | Строка в формате UUID | Идентификатор документа отчета об открытии смены, полученного от кассы |
| Close_DocNumber | Целое число | Фискальный номер документа отчета о закрытии смены, присвоенный кассой (уникальный в рамках текущего фискального режима) |
| Close_DocDateTime | Дата и время в формате ISO | Дата и время формирования отчета о закрытии смены по данным кассы |
| Close_DocRawId | Строка в формате UUID | Идентификатор документа отчета о закрытии смены, полученного от кассы |
| ShiftDocsCount | Целое число | Общее количество документов за смену |
| IncomeSumm | Целое число | Сумма полученных денежных средств за смену в копейках |
| IncomeCashSumm | Целое число | Сумма полученных денежных средств за смену наличными в копейках |
| IncomeECashSumm | Целое число | Сумма полученных денежных средств за смену безналичными в копейках |
| IncomeCount | Целое число | Количество чеков, выданных за смену, соответствующих получению суммы IncomeSumm |
| AdvanceSumm | Целое число | Сумма полученных денежных средств авансом в копейках |
| CreditSumm | Целое число | Сумма полученных денежных средств кредита в копейках |
| ExchangeSumm | Целое число | Сумма полученных денежных средств обмена в копейках |
| RefundIncomeSumm | Целое число | Сумма выданных (возвращённых) денежных средств за смену в копейках |
| RefundIncomeCashSumm | Целое число | Сумма выданных (возвращенных) денежных средств за смену наличными в копейках |
| RefundIncomeCount | Целое число | Количество чеков, выданных за смену, соответствующих возврату суммы RefundIncomeSumm |
| ExpenseSumm | Целое число | Сумма расхода за смену |
| ExpenseCount | Целое число | Количество чеков расхода за смену |
| RefundExpenseSumm | Целое число | Сумма возвратов расхода за смену |
| RefundExpenseCount | Целое число | Количество чеков возврата прихода за смену |
| RefundAdvanceSumm | Целое число | Сумма возврата аванса |
| RefundCreditSumm | Целое число | Сумма возврата кредита |
| RefundExchangeSumm | Целое число | Сумма возврата обмена |
| TaxTotalSumm | Целое число | Общая сумма удерживаемых налогов, начисленная за смену в копейках |
| Tax10Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %, начисленная за смену в копейках |
| Tax18Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20 %, начисленная за смену в копейках |
| Tax110Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках |
| Tax118Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20/120, начисленная за смену, в копейках |
| TaxNaSumm | Целое число | Сумма по операциям, не облагаемая НДС, накопленная за смену, в копейках |
| Tax0Summ | Целое число | Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену, в копейках |
Ошибки в ответе на запрос, обрабатываемые ИС:
2.3. Запрос списка отчетов по смене для всех ККТ за период
Запрос на получение списка отчетов по смене (z-отчетов) для всех ККТ, зарегистрированной на определенного владельца, за период имеет вид:
Здесь:
INN – ИНН юридического лица, на которое зарегистрирована касса, по данным которой генерируется отчет. Строка состоит из 10 цифр от 0 до 9.
Date1 и Date2 – начальная и конечная даты периода, для которого требуется сгенерировать отчет по открытым и закрытым сменам для заданной кассы – строка символов, содержащая дату и время в формате ISO. Разность Date2 и Date1 не должна превышать 30 дней.
Code – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных вида, аналогичного структуре, выдаваемой ИС по запросу списка отчетов по смене для заданной кассы за заданный период.
Ошибки в ответе на запрос, обрабатываемые ИС:
Внимание! В ответе json возвращается информации по сменам для всех ККТ только по текущему ФН.
2.4. Список чеков за период по заданной кассе
Запрос на получение списка чеков за период по заданной кассе имеет вид:
Здесь:
INN – ИНН юридического лица, на которое зарегистрирована касса, по данным которой генерируется отчет. Строка состоит из 10 цифр от 0 до 9.
KKT – регистрационный номер кассы – строка символов.
Date1 и Date2 – начальная и конечная даты периода, для которого требуется сгенерировать отчет по открытым и закрытым сменам для заданной кассы – строка символов, содержащая дату и время в формате ISO. Разность Date2 и Date1 не должна превышать 7 дней.
Code – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (приведены примеры значений, многоточие означает многократно повторяющуюся структуру такого же вида):
Список полей этой структуры c их описаниями представлен в таблице 3. Ошибки в ответе на запрос, обрабатываемые ИС:
Таблица 3. Поля данных записи со списком документов (чеков)
| Идентификатор | Формат поля | Назначение |
|---|---|---|
| Id | Строка в формате UUID | Уникальный номер фискального документа в ИС, используется в запросе подробной информации по чеку, как RawId |
| CDateUtc | Дата и время в формате ISO | Дата и время приема документа в ИС |
| Tag | Целое число | Численный признак вида документа: 3 – чек, 31 – чек коррекции, 4 – бланк строгой отчетности, 41 – бланк строгой отчетности коррекции |
| IsBso | Логическая переменная | Имеет значение true, если документ является БСО, иначе (если документ является чеком) – false |
| IsCorrection | Логическая переменная | Имеет значение true, если чек или бланк строгой отчетности (БСО) является документом коррекции, иначе – false |
| OperationType | Строка | Тип операции: «Income» – приход, «Expense» – расход, «Refund income» – возврат прихода, «Refund expense» – возврат расхода. |
| UserInn | Строка, 10 или 12 цифр | ИНН владельца кассы |
| KktRegNumber | Строка | Регистрационный номер кассы |
| FnNumber | Строка | Номер фискального накопителя, установленного в кассу |
| DocNumber | Целое число | Фискальный номер документа |
| DocDateTime | Дата и время в формате ISO | Дата и время формирования документа по данным кассы |
| DocShiftNumber | Целое число | Номер смены (по данным кассы), в которую был сформирован документ |
| ReceiptNumber | Целое число | Номер документа в смене (по данным кассы) |
| DocRawId | Строка в формате UUID | Уникальный номер фискального документа в ИС, (используется в запросе подробной информации по чеку, как RawId, дублирует поле Id) |
| TotalSumm | Целое число | Общая сумма по чеку в копейках |
| CashSumm | Целое число | Сумма по чеку (БСО) наличными в копейках |
| ECashSumm | Целое число | Сумма по чеку (БСО) электронными в копейках |
| PrepaidSumm | Целое число | Сумма по чеку (БСО) предоплатами (авансами) |
| CreditSumm | Целое число | Сумма по чеку (БСО) постоплатами (кредитами) |
| ProvisionSumm | Целое число | Сумма по чеку (БСО) встречными предоставлениями |
| TaxTotalSumm | Целое число | Общая сумма удерживаемых налогов, начисленная за смену в копейках |
| Tax10Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10 %, начисленная за смену, в копейках |
| Tax18Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20 %, начисленная за смену, в копейках |
| Tax110Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке 10/110, начисленная за смену, в копейках |
| Tax118Summ | Целое число | Сумма удерживаемого налога на добавленную стоимость (НДС) по ставке в 20/120, начисленная за смену, в копейках |
| TaxNaSumm | Целое число | Сумма по операциям, не облагаемая НДС, накопленная за смену, в копейках |
| Tax0Summ | Целое число | Сумма по операциям, облагаемая НДС по ставке 0%, накопленная за смену, в копейках |
| Depth | Целое число | Количество товарных позиций в чеке |
2.5. Список чеков за смену по заданной кассе
Запрос на получение списка за смену по заданной кассе имеет вид:
Здесь:
– действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON, аналогичная структуре, приведенной в п. 2.4. Описание полей структуры см. в Таблице 3, описание ошибок, см. в п. 2.4.
2.6. Подробная информация по чеку
Запрос на получение подробной информации по конкретному чеку может быть получен двумя способами: по уникальному номеру фискального документа, либо по порядковому номеру смены и номеру документа в смене.
Здесь:
INN – ИНН юридического лица Строка состоит из 10 цифр от 0 до 9.
KKT – регистрационный номер кассы – строка символов.
RawId – уникальный номер фискального документа в ИС «Чеки и ККТ» (строка в формате UUID).
ShiftNumber – номер смены, в течение которой был сгенерирован документ.
DocShiftNumber – номер документа внутри смены.
Code – действующий код авторизации, полученный в результате запроса авторизации.
Успешным ответом на запрос (с кодом HTTP равным 200) является структура данных JSON следующего вида (приведены примеры значений):
Описания параметров структуры бланка строгой отчетности представлен в таблице 4.
Таблица 4. Описание параметров бланка строгой отчетности
Таблица 5. Описание параметров чека коррекции
Таблица 6. Возможные значения параметра «ProductCode» (Тег 1163)
| Идентификатор | Формат поля | Назначение | Тег |
|---|---|---|---|
| Code_EAN_8 | Строка | код товара в формате EAN-8 | 1301 |
| Code_EAN_13 | Строка | код товара в формате EAN-13 | 1302 |
| Code_ITF_14 | Строка | код товара в формате ITF-14 | 1303 |
| Code_GS_1 | Строка | код товара в формате GS1, нанесенный на товар, не подлежащий маркировке средствами идентификации | 1304 |
| Code_GS_1M | Строка | код товара в формате GS1, нанесенный на товар, подлежащий маркировке средствами идентификации | 1305 |
| Code_KMK | Строка | код товара в формате короткого кода маркировки, нанесенный на товар, подлежащий маркировке средствами идентификации | 1306 |
| Code_MI | Строка | контрольно-идентификационный знак мехового изделия | 1307 |
| Code_F_1 | Строка | код товара в формате Ф.1 | 1320 |
| Code_F_6 | Строка | код товара в формате Ф.6 | 1325 |
Ошибки в ответе на запрос, обрабатываемые ИС: