Работа с API «Такском-Касса»

В этой статье:

- изучим структуру HTTP-запросов, программно сформируем тело, заголовки и параметры;

- познакомимся с API Такском-Касса, пройдём процедуру авторизации и получим данные чека с использованием кода 1С;

- научимся расшифровывать JSON-схемы запросов, описанные в API Такском;

- наглядно увидим разницу между POST и GET запросом;

- узнаем, как расшифровывать теги чеков и как их читать.

Рассмотренный пример выполнен в модуле формы обработки загрузки данных из Такском-Касса.

Знакомство с API Такском-Касса и авторизация через HTTP-запрос

API сервиса Такском-Касса предназначен для взаимодействия с личным кабинетом пользователя ККТ и решает задачи обмена данными. Найти можно по ссылке. Рассмотрим несколько примеров работы с API, составив запросы для авторизации и получения данных чека.

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

Открыв описание запроса, необходимого для авторизации, мы увидим следующее:

Рисунок 1 - Описание структуры запроса авторизации

Для чтения и понимания принципа составления запросов к Такском необходимо разобраться, из чего состоит запрос:

1. Стартовая строка – содержит адрес запроса. Он состоит из адреса сервера и пути к методу. В рассматриваемом случае стартовая строка содержит сервер «api-lk-ofd.taxcom.ru», с которым устанавливается соединение. Путь к методу авторизации выглядит так: «/API/v2/Login». В программном коде адрес сервера указывается при создании HTTP-cоединения, а путь к методу при создании HTTP-запроса.

2. Заголовки - определяют дополнительные параметры HTTP-сообщения. Они представляют собой пару из параметра и его значения, которые разделяются двоеточием. На одну строку — один параметр. В рассматриваемом примере всего два заголовка «Integrator-ID» и «Content-Type». В программном коде для указания заголовков создаётся соответствие, в котором прописывается название заголовка и его значение. Значение ID интегратора запрашивается у Такском через техническую поддержку.

3. Тело сообщения— это сами данные, которые передаются в запросе. Структура тела запроса находится в Приложении 1 документации. Файл из приложения содержит JSON-схему запроса и при открытии в текстовом редакторе имеет следующий вид:

Рисунок 2 - JSON-схема запроса авторизации

Для наглядного представления схемы и понимания того, как необходимо формировать запрос, обработаем содержимое файла в одном из сервисов для конвертации JSON0-схемы в текстовое представление. В данном случае использован сервис по ссылке. Также хорошими помощниками в составлении и тестировании запросов могут послужить Bruno и Postman.

В результате можно будет прочесть строковое представление тела, которое необходимо сформировать программным кодом и отправить посредством встроенных методов платформы:

Рисунок 3 - Результат конвертации JSON-схемы

В результате HTTP-запрос, который осуществляет процедуру авторизации и получения временного токена выглядит следующим образом:

Рисунок 4 - Схема соответствия описания запроса и его сборки в 1С

В итоге процесс формирования запроса состоит из следующих этапов:

1. Создание нового соединения, которое хранит адрес сервера, к которому адресован запрос;

2. Согласно документации создаётся соответствие, которое включает необходимые заголовки для исполнения запроса;

3. Создаётся сам запрос, в параметры которого передаётся адрес к методу и соответствие заголовков;

4. С помощью метода «УстановитьТелоИзСтроки» согласно схеме прописываются параметры, которые должны содержать поля «login» и «password», которые используются для входа в личный кабинет Такском, а также «agreementNumber» - номер договора, который можно найти в личном кабинете Такском (в примере данные пользователя и идентификатор интегратора нерабочие).

Когда запрос готов, он отправляется, а ответ считывается в формате JSON.

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

GET-запрос и чтение тегов чека

Для взаимодействия с API Такском необходимо использовать GET-запросы. В рамках рассматриваемого примера самое главное отличие «POST» от «GET» запроса в необходимости указания параметров в GET-запросе.

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

Рисунок 5 - Структура запроса получения данных документа

Рисунок 6 - Программная сборка, отправка и чтение результата

При описании GET-запроса в программном коде при создании нового запроса необходимо дополнительно, помимо адреса к методу и заголовков, указать параметры, согласно документации.

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

Рисунок 7 - Полученные данные чека

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

Посмотреть обозначение каждого тега можно в карточке документа в личном кабинете Такском. Ниже видно, что каждое поле чека сопоставлено с соответствующим ему значением тега:

Рисунок 8 - Карточка чека из ЛК Такском

Рисунок 9 - Расшифровка тегов чека

С обязательным перечнем реквизитов кассовых чеков, а также с их расшифровками можно ознакомиться на сайте ИТС по ссылке.

Мы рассмотрели два вида – GET и POST-запросы к Такском-Касса для получения данных о чеках. С полным перечнем методов можно ознакомиться в руководстве пользователя. Все остальные запросы пишутся по образу и подобию рассмотренных в статье примеров.