Описание API (коннектор АТОЛ Онлайн)

Сервис предназначен для удаленной регистрации (фискализации) чеков на арендованных клиентом у Эвотор кассах (ККТ) посредством разработанного клиентского API.

Версия сервиса v5 поддерживает регистрацию чеков формата фискальных данных версии 1.2 (ФФД 1.2) согласно вступившему в силу приказу ФНС России от 14.09.2020 № ЕД-7-20/662@.

Для начала регистрации чеков через API необходимо предварительно пройти процедуру регистрации компании (магазина) и получить учетные данные (логин, пароль, код группы) посредством Личного кабинета Эвотор

Общий алгоритм взаимодействия с сервисом через API

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

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

Результат регистрации чека на ККТ может быть получен двумя способами:

  • В случае, если в запросе на регистрацию был указан callback_url, сервис по результатам обработки чека вернет POST запрос на этот URL.

  • В случае, если callback_url не был указан или запрос не пришел, клиент самостоятельно может запросить результат обработки чека GET-запросом к сервису, описанному в разделе

Описание методов

Авторизация пользователя

Описание

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

Авторизационный токен, дает право доступа к системе посредством интеграционного API в течение 24 часов с момента его формирования. Токен должен передаваться в качестве параметра во все методы API сервиса. Максимальная длина токена – 1000 символов.

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

Например, вы запросили повторно токен спустя 10 часов с момента первого запроса. Вы получите новый токен и он будет действовать еще 24 часа, либо ранее выданный токен и он будет действовать 14 часов с момента этого запроса (24 часа с момента его первой выдачи клиенту).

Запрос

Метод POST

https://fiscalization.evotor.ru/possystem/v5/getToken

Заголовок запроса должен содержать параметр:

Content-type: application/json; charset=utf-8

Тело запроса должно содержать документ в формате JSON, соответствующий схеме.

Пример запроса
{
  "login": "neletest",
  "pass": "v2AfscRjr"
}

Параметры запроса:

  • login: логин из файла настроек интеграции в личном кабинете клиента.

  • pass: пароль из файла настроек интеграции в личном кабинете клиента.

Метод GET

https://fiscalization.evotor.ru/possystem/v5/getToken?login=<login>&pass=<pass>

Параметры строки запроса:

  • login: логин из файла настроек интеграции в личном кабинете клиента.

  • pass: пароль из файла настроек интеграции в личном кабинете клиента.

Ответ на запрос

Пример ответа
{
    "error": null,
    "token": "fj45u923j59ju42395iu9423i59243u0",
    "timestamp": "30.11.22 17:58:53"
}
Пример ответа с ошибкой
{
    "error": {
        "error_id": "20003",
        "code": 12,
        "text": "Неверный логин или пароль",
        "type": "system"
    },
    "timestamp": null
}

Параметры ответа на запрос:

  • error: ошибка.

    • error_id: уникальный идентификатор ошибки;

    • code: код ошибки;

    • text: текст ошибки;

    • type: тип ошибки.

  • token: авторизационный токен. Максимальная длина строки – 1000 символов. Возвращается только при отсутствии ошибки.

  • timestamp: дата и время ответа.

Регистрация документа

Описание

Метод позволяет отправить запрос на формирование чека и отправку его на регистрацию в ККТ.

Запрос

Метод: POST

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

https://fiscalization.evotor.ru/possystem/v5/<group_code>/<operation>

Заголовок запроса должен содержать параметры:

  • Content-type: application/json; charset=utf-8

  • Token: <token>

При технической невозможности передать token в заголовке запроса можно передать параметр в строке запроса:

https://fiscalization.evotor.ru/possystem/v5/<group_code>/<operation>?token=<token>

Параметры заголовка и строки запроса:

  • group_code: идентификатор группы ККТ;

  • operation: тип операции на регистрацию чека, которая должна быть выполнена. Возможные типы операции:

    • sell: чек «Приход»;

    • buy: чек «Расход»;

    • sell_refund: чек «Возврат прихода»;

    • buy_refund: чек «Возврат расхода»;

    • sell_correction: чек «Коррекция прихода»;

    • buy_correction: чек «Коррекция расхода»;

    • sell_refund_correction: чек «Коррекция возврата прихода»;

    • buy_refund_correction: чек «Коррекция возврата расхода»;

  • token: авторизационный токен.

Пример регистрации чека с операцией «Приход»:

https://fiscalization.evotor.ru/possystem/v5/group1/sell?token=<token>

Тело запроса должно содержать документ в формате JSON, соответствующий схеме.

Тело запроса для чеков прихода и возврат прихода

Описание полей запроса регистрации документа с типом операции «Приход», «Возврат прихода», «Расход», «Возврат расхода» представлено ниже.

Описание полей для тела запроса на регистрацию чека прихода и возврата прихода

Описание объекта service

Описание объекта receipt

Описание объекта client

Описание объекта company

Описание объекта items

Описание объекта vat

Описание объекта mark_quantity

Описание объекта mark_code

Описание объекта agent_info

Описание объекта paying_agent

Описание объекта receive_payments_operator

Описание объекта money_transfer_operator

Описание объекта supplier_info

Описание объекта payments

Описание объекта vats

Описание объекта additional_user_props

Описание элемента массива объектов sectoral_check_props и sectoral_item_props

Тело запроса для чеков коррекции прихода и коррекции возврата прихода

Описание полей для чеков коррекции совпадает с описанием полей для типов операций «Приход», «Возврат прихода», представленными выше. Отличие — объект reciept заменяется на correction. Так же добавляется объект correction_info (описание ниже) и поле cashier — обязательное.

Описание объекта correction_info

Ответ на запрос

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

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

Пример ответа
{
    "uuid": "2ea26f17–0884–4f08–b120–306fc096a58f",
    "timestamp": "12.04.22 06:15:06",
    "error": null,
    "status": "wait",
}
Пример ответа с ошибкой
{
    "timestamp": null,
    "status": "fail",
    "error": {
        "error_id": "20010",
        "code": 30,
        "text": " Передан некорректный UUID : \"{0}\". Необходимо повторить запрос с корректными
        данными ",
        "type": "system"
    }
}

Тело ответа на запрос регистрации чека

Описание объекта error

Получение результата обработки документа

Описание

Результат регистрации чека на ККТ может быть получен двумя способами:

  • В случае, если в запросе на регистрацию был указан callback_url, сервис по

    результатам обработки чека вернет POST запрос на этот URL.

  • В случае, если callback_url не был указан или запрос не пришел в течение 300 секунд с момента отправки чека, клиент самостоятельно может запросить

    результат обработки чека GET-запросом к сервису.

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

Запрос

Метод GET

https://fiscalization.evotor.ru/possystem/v5/<group_code>/report/<uuid>

Заголовок запроса должен содержать параметр:

Token: <token>

При технической невозможности передать token в заголовке запроса можно передать параметр в строке запроса.

https://fiscalization.evotor.ru/possystem/v5/<group_code>/report/<uuid>?token=<token>

Параметры заголовка и строки запроса:

  • group_code: идентификатор группы ККТ;

  • uuid: уникальный идентификатор, присвоенный документу после выполнения запроса на регистрацию;

  • token: авторизационный токен.

Пример запроса результата обработки документа
https://fiscalization.evotor.ru/possystem/v5/01-000000002602720/report/0459d6f9-afb6-41ab-860b-11c0544175ea

Ответ на запрос

В ответ возвращается пакет со статусом и реквизитами фискализации или ошибкой.

Пример ответа при успешной фискализации
{
    "uuid": "0459d6f9-afb6-41ab-860b-11c0544175ea",
    "timestamp": "10.08.22 10:00:00",
    "status": "done",
    "error": null,
    "payload": {
        "total": 47500,
        "fiscal_receipt_number": 1,
        "shift_number": 139,
        "receipt_datetime": "08.12.2022 12:20:00",
        "fn_number": "9999078902013061",
        "ecr_registration_number": "0000000000026332",
        "fiscal_document_number": 3763,
        "fiscal_document_attribute": 995410884,
        "fns_site": "www.nalog.ru",
        "ofd_receipt_url": "https://lk.platformaofd.ru/web/noauth/cheque/search?fn=9999078902013061&fp=995410884&i=3763"
    },
    "group_code": "01-000000002602720",
    "daemon_code": "prod–agent–1",
    "device_code": "356645110070952",
    "external_id": "fe743fbc-2ddf-4fba-8681-1eb730af5b59",
    "callback_url": ""
}
Пример ответа с ошибкой
{
    "uuid": "0459d6f9-afb6-41ab-860b-011c0544175e",
    "timestamp": null,
    "status": "fail",
    "error": {
        "text": "Передан некорректный UUID : '0459d6f9-afb6-41ab-860b-011c0544175e'. Необходимо повторить запрос с корректными данными",
        "type": "system",
        "code": 30,
        "error_id": "20010"
    },
    "payload": null,
    "group_code": null,
    "daemon_code": null,
    "device_code": null,
    "external_id": null,
    "callback_url": null
}

Тело ответа с результатами обработки чека

Описание объекта error

Описание объекта payload

Last updated