Интеграция в режиме ФР

Редактировать

Вы можете создать собственную интеграцию с Эвотор Power. На терминале работает сервер для обработки запросов по бинарному и http протоколам.

Эта статья подходит для Power в режиме ФР с ФФД 1.05. Чтобы получить информацию об интеграции в ФФД 1.2, напишите на developer@evotor.ru.

Доступно 13 функций. Какую функцию вызвать, Эвотор определяет по переданному id функции. В протоколе http id указывается в заголовке x-method-id. В бинарном протоколе id указывается в байтах 5 и 6. В теле запроса передайте информацию в формате XML. Тело запроса для каждой операции описано в разделе Описание функций.

Список id операций:

id в http	Бинарный id	Операция	Описание
1	00 01	CashIn	Операция внесения
2	00 02	CashOut	Операция изъятия
3	00 03	XReport	X-отчёт
4	00 04	ZReport	Z-отчёт
5	00 05	GetInfo	Информация о состоянии
6	00 06	OpenSession	Открыть смену
7	00 07	OpenCashDrawer	Открыть денежный ящик
8	00 08	ReceiptCopy	Копия чека
9	00 09	PrintStrings	Печать строк
10	00 0A	PrintFiscalCheque	Напечатать чек
11	00 0B	CorrectionReceipt	Чек коррекции
12	00 0C	Registration	Регистрация кассы
13	00 0D	CloseFiscalStorage	Закрыть фискальный накопитель

Описание функций

Операция внесения

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<cashin -- операция внесения
	partner="partner" -- строка на чеке "От кого", nullable, если отсутствует - не печатеатся
	reason="reason" -- строка на чеке "Основание", nullable, если отсутствует - не печатеатся
	sum="12.34"> -- сумма внесения
	<cashier
		inn="inn" -- инн кассира (nullable)
		name="name"/> -- имя кассира
	<header -- секция может отсутствовать, тогда на печать в заголовке чека будут выведены номер смены и номер чека из ККТ
		receipt="5" -- номер чека из внешней интеграции
		session="2"/> -- номер смены из внешней интеграции
</cashin>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Операция изъятия

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<cashout -- операция изъятия
	partner="partner" -- строка на чеке "Получатель", nullable, если отсутствует - не печатеатся
	reason="reason" -- строка на чеке "Основание", nullable, если отсутствует - не печатеатся
	sum="12.34" -- сумма изъятия
	category="category"> -- строка на чеке "Категория платежа", nullable, если отсутствует - не печатеатся
	<cashier
		inn="inn" -- инн кассира (nullable)
		name="name"/> -- имя кассира
	<header -- секция может отсутствовать, тогда на печать в заголовке чека будут выведены номер смены и номер чека из ККТ
		receipt="5" -- номер чека из внешней интеграции
		session="2"/> -- номер смены из внешней интеграции
</cashout>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

X-отчёт

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<cashier
	inn="inn" -- инн кассира (nullable)
	name="name"/> -- имя кассира

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message="" -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует
	factoryNumber="00300100000161" -- заводской номер ККТ (в редких случаях может быть пустой строкой, что свидетельствует об ошибках настройки и/или инициализации ККТ)
	fiscalStorageNumber="9999078902003114" -- серийный номер фискального накопителя (если отсутствует ФН - пустая строка)
	inn="112233445573" -- инн органицации (nullable)
	receiptsBySession="4" -- чеков за текущую/закрытую смену
	registrationNumber="0000000001000073" -- регистрационный номер ККТ (nullable)
	session="5" -- номер смены (*)
	sessionState="1"> -- состояние смены (0- закрыта, 1- открыта, 2- смена превысила 24 часа) (*)
	<counters
		cashInCount="0" -- количество внесений
		cashInSum="0.00" -- сумма внесений
		cashOutCount="0" -- количество изъятий
		cashOutSum="0.00" -- сумма изъятий
		cashSum="2.00" -- количество наличности в кассе
		proceeds="4.00" -- выручка (сумма прихода + сумма возврата расхода - сумма расхода - сумма возврата прихода), может быть отрицательной
		sessionTotal="8.00"> -- сменный итог (то же самое, что сумма прихода за смену)
		<income -- данные по приходу
			advance="0.00" -- приход авансом, сумма
			cash="6.00" -- приход наличными, сумма
			count="2" -- количество операций
			counteroffer="0.00" -- приход встречным предоставлением, сумма
			credit="0.00" -- приход кредитом, сумма
			electron="2.00" -- приход электронными, сумма
			sum="8.00"/> -- общая сумма прихода
		<outcome -- данные по расходу
			advance="0.00" cash="1.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="1.00"/>
		<returnOfIncome -- данные по возврату прихода
			advance="0.00" cash="3.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="3.00"/>
		<returnOfOutcome -- данные по возврату расхода
			advance="0.00" cash="0.00" count="0" counteroffer="0.00" credit="0.00" electron="0.00" sum="0.00"/>
	</counters>
	<ofd -- секция может отсутствовать (nullable), если нет ФН или ошибка связи с ФН
		firstUnsentDocumentNumber="1" -- номер первого неотправленного документа
		notSentDocuments="47" -- количество неотправленных документов
		notSentFrom="2021-02-19T16:52:00"/> -- время последней отправки документов в ОФД
</result>

Z-отчёт

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<cashier
	inn="inn" -- инн кассира (nullable)
	name="name"/> -- имя кассира

Ответ

пример z-отчета
<?xml version="1.0" encoding="UTF-8"?>
<result code="0" factoryNumber="00300100000161" fiscalStorageNumber="9999078902003114" inn="112233445573" receiptsBySession="4" registrationNumber="0000000001000073" session="5" sessionState="0">
	<counters cashInCount="0" cashInSum="0.00" cashOutCount="0" cashOutSum="0.00" cashSum="0.00" proceeds="4.00" sessionTotal="8.00">
		<income advance="0.00" cash="6.00" count="2" counteroffer="0.00" credit="0.00" electron="2.00" sum="8.00"/>
		<outcome advance="0.00" cash="1.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="1.00"/>
		<returnOfIncome advance="0.00" cash="3.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="3.00"/>
		<returnOfOutcome advance="0.00" cash="0.00" count="0" counteroffer="0.00" credit="0.00" electron="0.00" sum="0.00"/>
	</counters>
	<ofd firstUnsentDocumentNumber="1" notSentDocuments="48" notSentFrom="2021-02-19T16:52:00"/>
</result>

Информация о состоянии

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<getInfo
	state="true" -- расширенная информация о состоянии
	counters="true" -- информация о счётчиках
	ofd="true" -- информация об ОФД
	fiscalStorage="true"/> -- информация о фискальном накопителе

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
   charsInReceiptLine="48" -- количество символов в строке принтера
	code="0" -- код результата, 0 - ОК, иначе - код ошибки
	factoryNumber="00300100000161" -- заводской номер ККМ
	fiscalStorageNumber="9999078902003114" -- серийный номер фискального накопителя
   message="текст ошибки" -- в случае ошибки - текст ошибки, иначе поле отсутствует
	receiptsBySession="1" -- количество чеков в текущей смене
	session="6" -- номер текущей смены
	sessionState="1"> -- состояние текущей смены (0-закрыта, 1-открыта, 2-смена превысила 24 часа)
   	<counters -- секция присутствует только при указании параметра запроса "counters" == true
		cashInCount="0" -- количество внесений
		cashInSum="0.00" -- сумма внесений
		cashOutCount="0" -- количество изъятий
		cashOutSum="0.00" -- сумма изъятий
		cashSum="2.00" -- количество наличности в кассе
		proceeds="4.00" -- выручка (сумма прихода + сумма возврата расхода - сумма расхода - сумма возврата прихода), может быть отрицательной
		sessionTotal="8.00"> -- сменный итог (то же самое, что сумма прихода за смену)
		<income -- данные по приходу
			advance="0.00" -- приход авансом, сумма
			cash="6.00" -- приход наличными, сумма
			count="2" -- количество операций
			counteroffer="0.00" -- приход встречным предоставлением, сумма
			credit="0.00" -- приход кредитом, сумма
			electron="2.00" -- приход электронными, сумма
			sum="8.00"/> -- общая сумма прихода
		<outcome -- данные по расходу
			advance="0.00" cash="1.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="1.00"/>
		<returnOfIncome -- данные по возврату прихода
			advance="0.00" cash="3.00" count="1" counteroffer="0.00" credit="0.00" electron="0.00" sum="3.00"/>
		<returnOfOutcome -- данные по возврату расхода
			advance="0.00" cash="0.00" count="0" counteroffer="0.00" credit="0.00" electron="0.00" sum="0.00"/>
	</counters>
   	<fiscalStorage -- секция присутствует только при указании одного из параметров запроса "state" == true или "fiscalStorage" == true
   		completeRegistrations="1" -- выполнено регистраций/перерегистраций на текущем фискальном накопителе
   		expireOn="2022-06-04T03:00:00" -- фискальный накопитель действителен до
   		expiredRegistrations="1582" -- осталось перерегистраций до отказа
   		archiveDocumentsRemainedCount="249764" (**) -- приблизительное возможное количество документов длительного хранения (5 лет), штук
   		documentsRemainedKB="19434" /> (**) -- приблизительное возможное количество документов кратковременного хранения (30 дней), килобайт
   	<lastRegistration -- секция присутствует только при указании параметра запроса "state" == true
   		date="2021-02-19T16:52:00" -- время последней регистрации/перерегистрации
   		fiscalDocumentNumber="1" -- номер фискального документа последней регистрации/перерегистрации
   		fiscalDocumentSign="3963725703" -- фискальный признак документа последней регистрации/перерегистрации
   		inn="112233445573" -- инн, указанный в последней регистрации/перерегистрации
   		registrationNumber="0000000001000073" -- регистрационный номер ККМ, указанный в последней регистрации/перерегистрации
   		reRegistrationCode="0" /> (*) -- код перерегистрации (фискальный тег 1101)
   	<ofd -- секция присутствует только при указании параметра запроса "ofd" == true
   		firstUnsentDocumentNumber="1" -- номер первого неотправленного фискального документа
   		notSentDocuments="50" -- количество неотправленных фискальных документов
   		notSentFrom="2021-02-19T16:52:00" -- дата отправки последнего фискального документа
   		command="" (*) -- команда ФН, вызвавшая ошибку
   		fiscalDocument="1" (*) -- номер фискального документа, при отправке которого возникла ошибка
   		fnErrorCode="" (*) -- код ошибки фискального накопителя
   		host="ofdp.platformaofd.ru" -- адрес офд
   		inn="9715260691" -- инн офд
   		name="Платформа ОФД" -- название офд
   		networkErrorCode="Документ доставлен, после чего оборвалась связь и ответ не получен" -- описание ошибки сети
   		ofdErrorCode="" (*) -- описание ошибки офд
   		port="21101" -- порт офд
   		senderAddress="noreply@platformaofd.ru" /> -- адрес отправителя
</result>

Открыть смену

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<cashier
	inn="inn" -- инн кассира (nullable)
	name="name"/> -- имя кассира

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Открыть денежный ящик

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<request/>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иначе - код ошибки
   message="текст ошибки"/> -- в случае ошибки - текст ошибки, иначе поле отсутствует

Копия чека

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<request
	receiptNumber="2"> -- id чека
	<cashier
		inn="inn" -- инн кассира (nullable)
		name="name"/> -- имя кассира
</request>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Печать строк

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<request>
	<strings>
		<string -- печать строки
			text="test1"/> -- текст для печати
		<string
			text="test2" -- текст для печати
			type="0"/> -- формат текста (0 - строка, 1 - штрихкод EAN8/EAN13, 2 - QR-код)
		<string
			text="test3" -- будет напечатан QR-код с зашифрованным текстом test3
			type="2"/>
		<string
			text="90311017" -- будет напечатан EAN8 код
			type="1"/>
		<string
			text="9780201379624" -- будет напечатан EAN13 код
			type="1"/>
	</strings>
</request>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Напечатать чек

Запрос

<request
    settlementType="1" -- признак расчета (тэг 1054, 1-приход, 2-расход, 3-возврат прихода, 4-возврат расхода)
    taxationSystem="1" -- СНО (номер бита в тэге 1055, таблица 9 Приложение N 2 к приказу ФНС России от 21.03.2017 г. N ММВ-7-20/229@)
    sessionNumber="1" -- nullable, номер смены в заголовке чека, если не передаётся - номер фискальной смены
    receiptNumber="1" -- nullable, номер чека в заголовке чека, если не передаётся - номер фискального чека
    clientPhone="+71234567890" -- nullable, номер телефона клиента
    clientEmail="a@b.c"> -- nullable, электронная почта клиента

    <cashier -- реквизиты кассира
        inn="inn" -- ИНН кассира
        name="name"/> -- имя кассира
    <fiscalRequisites> -- дополнительные фискальные реквизиты, добавляемые в чек, список
        <requisite -- фискальный реквизит
            tag="1008" -- номер тэга фискального реквизита
            value="+71234567890" -- значение тэга фискального реквизита
            type="1"/> -- тип значения фискального реквизита (1-строка, 2-дата, 3-байт, 4-массив байт, 5-список вложенных фискальных реквизитов)
    </fiscalRequisites>
    <positions> -- позиции в чеке, список
        <position -- позиция в чеке
            name="test" -- наименование товара
            quantity="1" -- количество товара, в единицах. для весового товара - в килограммах
            price="10.00" -- цена товара за единицу
            priceWithDiscount="10.00" -- цена товара за единицу со скидкой, может быть равна price
            sum="10.00" -- стоимость товара в данной позиции, должна совпадать с priceWithDiscount*quantity с точностью до 1 копейки
            tax="1" -- ставка НДС на позицию (1-базовая, 2-льготная, 3-без НДС, 4-базовая расчётная, 5-льготная расчётная, 6-НДС 0%)
            settlementMethod="7" -- признак способа расчёта (тэг 1214)
            partialSettlementSum="1.00" -- сумма частичной предоплаты, если признак способа расчёта равен 5, может быть null
            additionalInfoForPosition="additionalInfoForPosition" -- дополнительный текст на чеке, относящийся к позиции
            productType="1"> -- признак предмета расчёта (тэг 1212)
            <fiscalRequisites>
                <requisite -- фискальный реквизит
                    tag="1008" -- номер тэга фискального реквизита
                    value="+71234567890" -- значение тэга фискального реквизита
                    type="1"/> -- тип значения фискального реквизита (1-строка, 2-дата, 3-байт, 4-массив байт, 5-список вложенных фискальных реквизитов)
            </fiscalRequisites>
        </position>
    </positions>
    <payments> -- список платежей по чеку
        <payment -- платёж
            type="2" -- тип оплаты
            sum="10.00"/> -- сумма оплаты
    </payments>
</request>

Ответ

<response
    code="0" -- код результата, 0 - ОК, иное - код ошибки
    message="message" -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует
    factoryNumber="00300100000161" -- заводской номер ККМ
    fiscalStorageNumber="9999078902003114" -- серийный номер фискального накопителя
    registrationNumber="0000000001000073"> -- регистрационный номер ККТ

    <fiscalDocument -- фискальная часть документа, если присутствует - все поля дольжны присутствовать. может отсутствовать
        fiscalSession="6" -- номер фискальной смены
        fiscalReceipt="4" -- номер фискального чека внутри смены
        fiscalDocument="1234" -- номер фискального документа (сквозной)
        fiscalSign="1295042050" -- фискальный признак документа
        fiscalDate="2021-04-20T14:17:01"/> -- дата формирования фискального документа

</response>

Чек коррекции

Запрос

<?xml version="1.0" encoding="UTF-8"?>
<request
    taxationSystem="0" -- система налогообложения (0 - ОСН, 1 - упрощенная (доход), 2 - упрощенная (доход - расход), 3 - ЕНВД, 4 - ЕСХН, 5 - ПСН)
    cause="0" -- причина коррекции (0 - самостоятельно, 1 - по предписанию ФНС)
    reason="reason" -- основание коррекции
    documentDate="2021-04-20T14:17:00" -- дата коррекции
    documentNumber="1234" -- номер документа коррекции
    correctionType="0" -- тип коррекции (0 - коррекция продажи, 1 - коррекция покупки)
    correctionTax="20" -- ставка налога в чеке коррекции (строка, одна из: 20, 18, 10, 20/120, 18/118, 10/110, 0, none)
    session="17" -- номер смены в заголовке чека, может быть null, тогда будет подставлен автоматически
    receipt="42" -- номер чека в заголовке чека, может быть null, тогда будет подставлен автоматически
    paymentAddress="address" -- адрес места расчета в чеке коррекции, может быть null
    paymentPlace="place"> -- место расчета в чеке коррекции, может быть null
    <cashier
        name="cashier name" -- имя кассира
        inn="000000000000"/> -- инн кассира
    <payment -- платёж
        type="1" -- тип оплаты
        sum="12.34"/> -- сумма оплаты
</request>

Ответ

<response
    code="0" -- код результата, 0 - ОК, иное - код ошибки
    message="message" -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует
    factoryNumber="00300100000161" -- заводской номер ККМ
    fiscalStorageNumber="9999078902003114" -- серийный номер фискального накопителя
    registrationNumber="0000000001000073"> -- регистрационный номер ККТ

    <fiscalDocument -- фискальная часть документа, если присутствует - все поля дольжны присутствовать. может отсутствовать
        fiscalSession="6" -- номер фискальной смены
        fiscalReceipt="4" -- номер фискального чека внутри смены
        fiscalDocument="1234" -- номер фискального документа (сквозной)
        fiscalSign="1295042050" -- фискальный признак документа
        fiscalDate="2021-04-20T14:17:01"/> -- дата формирования фискального документа
</response>

Регистрация кассы

Запрос

<request
    rnm="0000000001060000" -- Регистрационный номер, присвоенный налоговой
    taxationSystems="3" -- Доступные системы налогообложения (формат 0b00xxxxxx)
    fnsSite="www.nalog.ru" -- Сайт налоговой
    isCrypt="false" -- Шифрование
    isAutonomous="false" -- Автономный режим
    isAutomatic="false" -- Касса - автомат
    isService="false" -- Применение в сфере услуг
    isBSOMode="false" -- Режим чеков
    isInternetUsing="false" -- Применение в интернете
    isGambling="false" -- Признак проведения азартных игр
    isLottery="false" -- Признак проведения лотерей
    agentCode="17" -- Код платёжного агента
    changeRegistrationReason="1" -- Причина перерегистрации CHANGE_FN == 1, CHANGE_OFD == 2, CHANGE_USER_PROPERTIES == 3, CHANGE_KKT_SETTINGS == 4,
    registerWithoutFiscalStorage="false" -- для регистрации без ФН установить в true
    isExcise="false" -- Признак торговли подакцизными товарами (тег 1207)
    automaticNumber="10491" -- номер автомата (тег 1036)
    isMarkedProducts="false" -- Признак торговли товарами, подлежащими обязательной маркировке средствами идентификации
    isPawnshop="false" -- Признак осуществления ломбардами кредитования граждан
    isInsurance="false" -- Признак деятельности по страхованию
    ffdNumber="105" -- Желаемая версия ФФД для регистрации\перерегистрации 1.0 == 100, 1.05 == 105, 1.1 == 110, 1.2 == 120
    >
    <cashier
        name="cashier name" -- имя кассира
        inn="3211245502" -- инн кассира
        />
    <organization
        name="evotor" -- Название организации
        inn="935897614257" -- ИНН организации
        address="organization address" -- Адрес организации
        paymentPlace="payment place" -- Место оплаты
        email="wyiuoi@skvlb.wefji" -- Адрес отправки электронных чеков
        />
</request>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Закрыть фискальный накопитель

Запрос

<request>
<cashier
    name="cashier" -- имя кассира
    inn="000000000000" -- инн кассира
    />
</request>

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<result
	code="0" -- код результата, 0 - ОК, иное - код ошибки
	message=""/> -- в случае ошибки передаётся описание ошибки, в случае успешного результата отсутствует

Пример запроса через http

curl -i -X POST \
   -H "x-method-id:6" \
   -d \
'<cashier
	inn="inn"
	name="name"/>' \
 'http://1.2.3.4:54345'

Ответ приходит в формате XML:

<result
	code="0"
	message=""/>

Пример бинарного запроса

Пример запроса:

07 E2 01 48 xx xx 00 01 yy yy yy yy zz zz zz (...)

Где:

xx xx — код команды. Тип short или word;
yy yy yy yy — длина данных в байтах. Тип int;
zz zz zz (...) — данные длиной yy yy yy yy. Строка в формате UTF-16LE.

Пример успешного ответа:

00 01 00 01 yy yy yy yy zz zz zz (...)

Где:

yy yy yy yy — длина данных в байтах. Тип int;
zz zz zz (...) — данные длиной yy yy yy yy. Строка в формате UTF-16LE.

Пример ответа с ошибкой:

00 00 00 00 00 04 qq qq qq qq yy yy yy yy zz zz zz (...)

Где:

qq qq qq qq — код ошибки. Тип int;
yy yy yy yy — длина текста ошибки в байтах. Тип int;
zz zz zz (...) — текст ошибки. Строка в формате UTF-16LE.