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

PreviousПеререгистрация ККТ в связи с заменой ФН NextСписок ошибок

Last updated 2 months ago

Сервис предназначен для удаленной регистрации (фискализации) чеков на арендованных клиентом у Эвотор кассах (ККТ) посредством разработанного клиентского 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

{
   "timestamp":" 03.06.2020 12:05:31",
   "external_id": "892924433234522512289444",
   "service": {
      "callback_url": "https://shop.ru"
   },
   "receipt": {
      "client": {
         "email": "client@client.ru",
         "phone": "+70002410085",
         "name": "Иванов Иван Иванович",
         "inn": "112233445573"
      },
      "company": {
         "email": "email@evotor.ru",
         "sno": "osn",
         "inn": "0923341225",
         "payment_address": "shop-url.ru"
      },
      "cashier_inn": "112233445573",
      "cashier": "Антон Чеков",
      "items": [
         {
            "name": "Ваш любимый товар1",
            "price": 120,
            "quantity": 1.0,
            "measure": 0,
            "sum": 120,
            "payment_method": "full_payment",
            "payment_object": 1,
            "vat": {
               "type": "vat20",
               "sum": 20.0
            },
            "user_data": "Дополнительный реквизит предмета расчета",
            "excise": 10.0,
            "mark_quantity": {
               "numerator": 1,
               "denominator": 3
            },
            "mark_processing_mode": "0",
            "mark_code": {
               "gs1m": "010463003407001221CMK45BrhN0WLf"
            },
            "agent_info":  {
               "type": "another",
               "paying_agent": {
                  "operation": "Операция 1",
                  "phones": ["+79999999999"]
               },
               "receive_payments_operator": {
                  "phones": ["+79999999999"]
               },
               "money_transfer_operator": {
                  "phones": ["+79999999999"],
                  "name": "Оператор перевода",
                  "address": "г. Москва, ул. Сказочная д.3",
                  "inn": "112233445573"
               }
            },
            "supplier_info": {
               "phones": [
                  "+79999999999"
               ],
               "name": "Название поставщика",
               "inn": "112233445573"
            },
            "sectoral_item_props":[
               {
                  "date": "18.01.2023",
                  "value": "tm=mdlp&sid=00000000405195&",
                  "number": "123/43",
                  "federal_id": "001"
               }
            ]
         }
      ],
      "payments":[
         {
            "type": 1,
            "sum": 120.0
         }
      ],
      "vats":[
         {
            "type": "vat20",
            "sum": 20.0
         }
      ],
      "sectoral_check_props":[
         {
            "date": "18.02.2023",
            "value": "tm=mdlp&sid=00752852194630&",
            "number": "123/89",
            "federal_id": "002"
         }
      ],
      "": "445334544",
      "total": 120.0,
      "": {
         "name": "название доп реквизита",
         "value": "значение доп реквизита"
      }
   }
}

{
   "timestamp":" 03.06.2020 12:05:31",
   "external_id": "892924433234522512289444",
   "service": {
      "callback_url": "https://shop.ru"
   },
   "correction": {
      "client": {
         "email": "client@client.ru",
         "phone": "+70002410085",
         "name": "Иванов Иван Иванович",
         "inn": "516974792202"
      },
      "company": {
         "email": "email@evotor.ru",
         "sno": "osn",
         "inn": "5010051677",
         "payment_address": "shop-url.ru"
      },
      "cashier_inn": "887405485310",
      "cashier": "Антон Чеков",
      "correction_info": {
         "type": "self",
         "base_date": "02.02.2022",
         "base_number": "735/01505"
      },
      "items": [
         {
            "name": "Ваш любимый товар1",
            "price": 120,
            "quantity": 1.0,
            "measure": 0,
            "sum": 120,
            "payment_method": "full_payment",
            "payment_object": 1,
            "vat": {
               "type": "vat20",
               "sum": 20.0
            },
            "excise": 10.0,
            "mark_processing_mode": "0",
            "mark_code": {
               "gs1m": "010463003407001221CMK45BrhN0WLf"
            },
            "agent_info": {
               "type": "another"
            },
            "supplier_info": {
               "phones": [
                  "+79998887766"
               ],
               "name": "Название поставщика",
               "inn": "287381373424"
            },
            "sectoral_item_props":[
               {
                  "date": "18.01.2023",
                  "value": "tm=mdlp&sid=00000000405195&",
                  "number": "123/43",
                  "federal_id": "001"
               }
            ]
         }
      ],
      "payments":[
         {
            "type": 1,
            "sum": 120.0
         }
      ],
      "vats":[
         {
            "type": "vat20",
            "sum": 20.0
         }
      ],
      "sectoral_check_props":[
         {
            "date": "18.02.2023",
            "value": "tm=mdlp&sid=00752852194630&",
            "number": "123/89",
            "federal_id": "002"
         }
      ],
      "": "445334544",
      "total": 120.0,
      "": {
         "name": "название доп реквизита",
         "value": "значение доп реквизита"
      }
   }
}