kosov/fns-check
Данная библиотека предоставляет возможности, аналогичные функционалу официального мобильного приложения ФНС по проверке онлайн-чеков, а именно:
- Регистрация нового пользователя;
- Авторизация пользователя;
- Восстановление пароля пользователя;
- Проверка существования чека;
- Получение детальной информации по чеку.
Установка даннной библиотеки возможна только через Composer.
Так как библиотека использует HTTP клиент по стандарту PSR-7, то вместе с библиотекой необходимо установить любой из доступных HTTP клиентов или адаптеров. Список поддерживаемых HTTP клиентов – http://docs.php-http.org/en/latest/clients.html. Подробнее об использовании можно почитать здесь.
Выполните следующую команду (если вы хотите использовать php-http/curl-client в качестве HTTP клиента)
в директории своего проекта или добавьте
в секцию require файла composer.json вашего проекта.
Ниже рассмотрен пример получения детальной информации по чеку. Все остальные примеры возможностей данной библиотеки рассмотрены здесь.
Если вы работаете с данными QR-кода чека, то для формирования массива данных запроса можете использовать FnsCheckHelper::fromQRCode :
Возможные проблемы и их решения
При получении детальной информации по чеку вы можете получить ошибку illegal public api usage . Чтобы этого не происходило, необходимо выполнять запросы в следующем порядке:
Универсальный API для получения информации по чекам
В данной статье хотелось бы рассказать про API для получения чеков, которое нам не предоставила всеми любимая ФНС.
Когда только появились QR-коды на чеках я подумал «Вау, как круто! Ты сканируешь код и видишь если не всю инфу по чеку, то ссылку на него». И какого же было мое разочарование, когда просканировав такой код я увидел что-то вроде
Но расстраиваться я не стал и подумал, что ФНС позаботилась о нас и предоставила API для получения такой информации. Погуглив некоторое время я понял, что ФНС нам предоставила только мобильное приложение для проверки чека и просмотра той информации, что поступила к ним от магазина.
Но! Между магазином и налоговой имеется ещё одно звено — ОФД — те, кто обрабатывают информацию по чекам, полученную от магазинов, и отправляют в налоговую. Вот они то и предоставляют API для получения нужной нам информации. Не все. И не всегда бесплатно.
Судя по информации из википедии по состоянию на 1 марта 2018 зарегистрировано 17 ОФД. Допустим 10 из них предоставляют открытое и бесплатное API. Учитывая то, что мы не знаем с каким ОФД работает конкретный магазин, нужно будет пройтись по API 10 операторов фискальных данных. Далеко не лучший вариант.
Спустя какое-то время, я случайно наткнулся на приложение (не от ФНС), которое по QR-коду с чека получает информацию по чеку. Не будут же они «пробегать» по всем ОФД и собирать оттуда информацию — подумал я. Снова отправился в гугл и наткнулся на такой ответ.
Казалось, после этого ответа можно заканчивать импровизированное расследование, но у меня оставались ещё вопросы:
- Что будет, если использовать другие заголовки?
- Что делать, если пользователь не зарегистрирован? Скачивать мобильное приложение и регистрироваться? (Сайт ФНС не предоставляет возможности зарегистрироваться в этом контексте)
- А если забыл пароль?
Все параметры обязательные.
Если результат успешен, то пользователь создается, СМС с паролем отправляется на указанный номер, а в ответ возвращается 204 No content.
Если пользователь уже существует, то возвращается 409 Conflict и сообщение «user exists».
Если номер телефона некорректный, то возвращается 500 Internal Server Error и сообщение «failed with code 20101».
Если адрес электронной почты некорректный, то возвращается 400 Bad Request и сообщение «[«Object didn’t pass validation for format email: <адрес электронной почты, который вы указали>»]».
Если адрес электронной почты уже используется, а телефон нет, то ошибок не возникает и регистрация проходит успешно.
В заголовке передается Pre-emptive Basic Authorization, где в качестве username передается номер телефона, в виде «+79991234567», а в качестве пароля — код, полученный в смс при регистрации или восстановлении пароля.
Если все хорошо, то вернется 200 OK и сообщение в виде json
Если указать некорректный номер телефона или пароль, то вернется 403 Forbidden и сообщение «the user was not found or the specified password was not correct».
Если не указать номер телефона и/или пароль, то не вернется ничего.
Если номер телефона найден, то возвращается 204 No Content и на телефон приходит СМС с новым паролем.
Если номер телефона не найден или номер некорректный, то возвращается 404 Not Found и сообщение «the user was not found».
- Номер ФН (Фискальный Номер) — 16-значный номер. Например 8710000100518392
- Номер ФД (Фискальный документ) — до 10 знаков. Например 54812
- Номер ФПД (Фискальный Признак Документа, также известный как ФП) — до 10 знаков. Например 3522207165
- Вид кассового чека. В чеке помечается как n=1 (приход) и n=2 (возврат прихода)
- Дата — дата с чека. Формат может отличаться. Я пробовал переворачивать дату (т.е. 17-05-2018), ставить вместо Т пробел, удалять секунды
- Сумма — сумма с чека в копейках
- Номер ФН (Фискальный Номер) — 16-значный номер. Например 8710000100518392
- Номер ФД (Фискальный документ) — до 10 знаков. Например 54812
- Номер ФПД (Фискальный Признак Документа, также известный как ФП) — до 10 знаков. Например 3522207165
Если не указать номер телефона и/или пароль, то ничего не вернется.
Если чек не найден, то возвращается 406 Not Acceptable. Также чек может быть не найден, если он был получен достаточно давно. ФНС не хранит информацию по чекам за все время. На момент написания этой статьи ФНС хранила детальную информацию порядка 2-3 месяцев.
Если перед вызовом данного метода не происходила проверка существования чека, то вернется 202 Accepted (без сообщений и любого содержимого). При повторном вызове информация по чеку вернется.
Если в параметре «sendToEmail» попытаться подставить значение «yes», то вернется 500 Internal Server Error и сообщение «connect ECONNREFUSED 127.0.0.1:465». При попытке подставить другие значения («true», 1 и т.д.) вернется 400 Bad Request и сообщение «[«No enum match for: <значение, которое пытались передать>»]».
Если всё хорошо, то вернется 200 ОК и содержимое в формате json примерно такого вида:
- все суммы указаны в копейках
- данные кассира в разных магазинах имеют разные форматы (в одном случае может вернуться «Фамилия Имя», в другом «Фамилия И. должность»
- порядок элементов может меняться
- разные магазины используют разные наборы параметров и, если какой-то параметр возвращается в чеке от одного магазина, то не факт, что этот параметр будет в чеке от другого магазина
- формат адреса магазина может различаться
Особого смысла в логине я не вижу, но он используется в их мобильном приложении. Возможно, в дальнейшем он для чего-нибудь пригодится.
Кому интересен пример реализации подключения к этому API, вот ссылка на гитхаб проект библиотеки, написанной на C#.
По всем вопросам или замечаниям прошу в комментарии.
UPD После небольшой проверки выяснилось, что ФНС не хранит детальную информацию по всем чекам. По крайней мере у меня 22.05.2018 не удалось получить полный чек от декабря 2017, января и февраля 2018, при том, что у ОФД эта информация имеется и мобильное приложение ФНС сообщает, что чек корректен. За март 2018 чек получить уже удалось.
UPD Как заметили пользователи IvanG и neoman36, n=1 это «Вид кассового чека». 1 — значит «приход», 2 — «Возврат прихода». Это же число надо вставлять при проверке существования чека.
UPD Как заметил пользователь Echo77, начиная с декабря 2018 года API стал возвращать код ответа 451 «Illegal public API usage», поэтому теперь прежде чем запрашивать чек, необходимо делать запрос на проверку существования чека.
UPD По замечанию пользователя Actie, в ответ на этот вопрос на тостере, в конце 2018 года ФНС выпустила официальный API «Проверка чека». «Доступ к API дают если написать заявление, заверить электронной подписью, рассказать зачем и как будешь использовать.» (с)
Получить токен физическому лицу, насколько понимаю, невозможно. Только юр. лицо или ИП. Также при написании заявления необходимо явно указать с каких IP адресов будешь запрашивать информацию по чекам.
Этот же пользователь (организация(?)) — Actie реализовали gem для Ruby. Но опять же замечу, что использовать его без токена не получится. Ссылка на репозиторий.
В этом же репозитории указано, что при большом количестве проверок API, описанный в данной статье, работает не стабильно. Лично я не проверял.
UPD Как заметил один из пользователей — после большого количества запросов появляется ошибка блокировки аккаунта. На 25.03.2020 лимит составляет около 25 запросов в сутки. Раньше такого лимита вроде бы не было.
Собираем данные с чеков гипермаркетов на Python
Update: к сожалению, информация в данном посте устарела. Рекомендуем изучить наш новый пост.
Недавно, покупая в очередной раз продукты в гипермаркете, вспомнил, что согласно ФЗ-54 любой оператор торговли, который пробивает кассовый чек, обязан отправлять данные чека в налоговую.
Что это значит для нас, аналитиков данных? Что мы можем лучше узнать себя, свои потребности и получить интересные данные о собственных покупках.
Попробуем в рамках серии постов собрать небольшой прототип приложения, которое позволит строить динамику своих покупок. Итак, начнем с того, что в каждом чеке есть QR-code, если его распознать, то мы получим следующую строку:
t=20190320T2303&s=5803.00&fn=9251440300007971&i=141637&fp=4087570038&n=1
В данной строке содержатся:
t — timestamp, время, когда вы осуществили покупку
s — сумма чека
fn — кодовый номер fss, потребуется далее в запросе к API
i — номер чека, он нам потребуется далее в запросе к API
fp — параметр fiscalsign, потребуется далее в запросе к API
В рамках решения первого шага нашей задачи мы будем парсить данные чека и собирать их в pandas dataframe, используя модули Python.
Мы воспользуемся API, который отдает данные по чеку с сайта налоговой.
В начале получим аутентификационные данные:
В результате выполнения POST-запроса мы получим пароль в виде SMS на указанный мобильный телефон. Далее, мы будем использовать его в переменной pwd
Теперь распарсим нашу строку со значениями из QR-кода:
Будем использовать полученные переменные для извлечения данных.
В посте на Хабре довольно подробно изучены статусы ошибок при формировании запроса к API, не буду повторять эту информацию.
В начале необходимо проверить, что по данному чеку есть данные, формируем GET-запрос.
В запросе необходимо указать headers, хотя бы пустые. В моем случае GET-запрос возвращает ошибку 406, из чего я понимаю, что такой чек находится (почему GET-запрос возвращает 406 для меня загадка, буду рад подсказкам в комментариях). Если не указать сумму или дату, то GET-запрос вернет ошибку 400 — bad request.
Переходим к самому интересному, получаем данные чека:
Должны получить код 200 (успешное выполнение GET-запроса), а в переменной products — все, что относится к нашему чеку.
Чтобы работать с этими данными воспользуемся pandas и преобразуем все в dataframe.
Теперь мы имеем рабочий pandas.dataframe с чеками, визуально это выглядит так:
Можно построить гистограмму покупок или посмотреть на все в виде «ящика с усами»:
В завершение элементарно получим описательные статистики в текстовом виде командой .describe():
Данные удобно записать в .csv-файл, чтобы в следующий раз дополнить статистику: