Page History

Веб-сервис фискализации

...

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

Note
Фискализация осуществляется для платежей только в  российских рублях (RUB).

Веб-сервис позволяет предприятию получить уникальный идентификатор сгенерированного в АПК Ассист фискального чека (или чека коррекции) на основе данных, переданных в запросе.

По идентификатору можно в свою очередь запросить фискальные данные чека из АПК Ассист через отдельный веб-сервис fiscalreceipt. Эти данные используются, например, в тех случаях, когда предприятие самостоятельно отправляет электронные копии чеков своим покупателям.

...

^{Веб-сервис для проведения фискализации}PaymentTypes^{Веб-сервис для проведения фискализацииВеб-сервис для проведения фискализацииВеб-сервис для проведения фискализацииВеб-сервис для проведения фискализацииВеб-сервис для проведения фискализацииВеб-сервис для проведения фискализацииВеб-сервис для проведения фискализации}24 ^{Веб-сервис для проведения фискализации}НетчислоDocumentRequisite16

Параметр	Обязательное поле	Принимаемые значения	Значение по умолчанию	Описание
Merchant_ID	Да	Число		Идентификатор предприятия в системе АПК Ассист
Login	Да	20 символов		Логин пользователя сервиса от предприятия
Password	Да	30 символов		Пароль пользователя сервиса от предприятия
Billnumber	Нет	1	16 цифр расширенный формат		Расширенный номер платежа, соответствующий выполненному ранее платежу или выполненной ранее отмене в системе АПК Ассист
Payment_ID	НетВеб-сервис для проведения фискализации1	255 символов		Уникальный идентификатор чека в системе предприятияВеб-сервис для проведения фискализации2
Email	Да/НетВеб-сервис для проведения фискализации3	128 символов		E-mail адрес для отправки фискального чека
Phone	Да/НетВеб-сервис для проведения фискализации3	Число		Номер телефона для отправки фискального чека чека  - стандартный номер с кодом страны (без +7), минимум 11 цифр.12
Type	Да	Строка		Тип фискализируемого платежа: sell – оказание услуг; sell_refund – возврат. Если в запросе передается параметр Billnumber, то для фискализации платежа должен передаваться тип sell, а для фискализации отмены тип sell_refund.
PaymentType	Да/НетВеб-сервис для проведения фискализации4	Число		Вид оплаты
ReceiptType	Да/Нет	5	Строка	Набор/массив пар значений видов оплаты и соответствующих им сумм: {"Amount":<value>, "PaymentType":<PaymentType>} Warning Сумма значений Amount по всем использованным видам оплаты должна быть равна сумме чека.
TaxationSystem	НетВеб-сервис для проведения фискализации	Число	Из настроек предприятия или ККТ	Система налогообложения
Chequeitems	Да/НетВеб-сервис для проведения фискализации	Строка в формате JSON	Позиции чека, см. «Работа с чеком».
	Тип чека: normal – чек при фискализации оплаты или отмены; correct – чек коррекции.
CorrectionType	Да/Нет5	Строка		Тип коррекции: self – самостоятельное решение о коррекции; instruction – коррекция по предписанию надзорного органа.
CorrectionDocDate	Да/Нет5	DD.MM.YYYY		Дата корректируемого расчета
CorrectionDocID	Да/Нет5	Строка		Номер документа, на основании которого производится коррекция (для коррекции по предписанию)
PaymentTypes	Да/Нет4	Строка		Набор/массив пар значений видов оплаты и соответствующих им сумм: {"Amount":<value>, "PaymentType":<PaymentType>} Warning Сумма значений Amount по всем использованным видам оплаты должна быть равна сумме чека.
TaxationSystem	Нет6	Число	Из настроек предприятия или ККТ	Система налогообложения
Chequeitems	Да/Нет7	Строка в формате JSON		Позиции чека, см. «Работа с чеком».
Amount	Да	Число, 15 знаков, два знака после разделителя (допустимые разделители «.», «,»)		Сумма чека Если в запросе передается параметр Billnumber, то сумма чека должна равняться сумме платежа (или отмены).
Format	Нет	1 – CSV 3 – XML 4 - SOAP 5 - JSON	1	Формат возвращаемого ответа.
Language	Нет	RU - русский, EN - английский	Язык предприятия	Язык отправляемого письма (RU/EN)
ReceiptLine	Да/Нет7	128 символов		Позиция чека (для чеков с единственной позицией)
Tax	Да/Нет7	10 символов		Идентификатор ставки налога
FPMode	Да/Нет7	Число		Способ расчета
LastName	Нет	70 символов	Пусто	Фамилия покупателя
FirstName	Нет	70 символов	Пусто	Имя покупателя
MiddleName	Нет	70 символов	Пусто	Отчество покупателя
CustomerDocID	Нет	11 символов	Пусто	Серия/номер паспорта покупателя
TaxpayerID	Нет	12 символов	Пусто	ИНН покупателя
CompanyName	Нет
Amount	Да	Число, 15 цифр (разделители «.», «,»)	Сумма чека Если в запросе передается параметр Billnumber, то сумма чека должна равняться сумме платежа (или отмены).
Format	Нет	Число	1	Формат возвращаемого ответа (1-CSV, 2-WDDX, 3-XML, 4-SOAP, 5-JSON)
Language	Нет	RU - русский, EN - английский	Язык предприятия	Язык отправляемого письма (RU/EN)
ReceiptLine	Да/НетВеб-сервис для проведения фискализации	128 символов	Позиция чека (для чеков с единственной позицией)	Tax	Да/НетВеб-сервис для проведения фискализации	10 символов	Идентификатор ставки налога	FPMode	Да/НетВеб-сервис для проведения фискализации	Число	Способ расчета
LastName	Нет	70 символов	Пусто	Фамилия покупателя
FirstName	Нет	70 символов	Пусто	Имя покупателя
MiddleName	Нет	70 символов	Пусто	Отчество покупателя
CustomerDocID	Нет	11 символов	Пусто	Серия/номер паспорта покупателя
TaxpayerID	Нет	12 символов	Пусто	ИНН покупателя
CompanyName	Нет	256 символов	Пусто	Наименование компании (если покупатель – юридическое лицо)
PaymentAddress	Нет	256 символов	Пусто	Адрес расчетов
PaymentPlace	Да/Нет	8	256 символов	Пусто	Место расчетов
Cashier	Да/Нет	8	64 символа	Пусто	Кассир
CashierINN10	Да/Нет	8	12 цифровых символов	Пусто	ИНН кассира
PaymentTerminal	Да/Нет	9	20 символов	Пусто	Номер автоматического устройства
TransferOperatorPhone	10	Нет11	19 символов	Пусто	Телефон оператора перевода - формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
TransferOperatorName	Нет11	64 символа	Пусто	Наименование оператора перевода
TransferOperatorAddress	Нет11	256 символов	Пусто	Адрес оператора перевода
TransferOperatorINN10	Нет11	10 цифровых символов	Пусто	ИНН оператора перевода
PaymentReceiverOperatorPhone	10	Нет11	19 символов	Пусто	Телефон оператора по приёму платежей	- формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
PaymentAgentOperation	Нет11	24	PaymentAgentOperation	Нет	символа	Пусто	Операция платёжного агента
PaymentAgentPhone	10	Нет11	19 символов	Пусто	Телефон платёжного агента	SupplierPhoneВеб-сервис для проведения фискализации	- формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
SupplierPhone10	Нет11		19 символов	Пусто	Телефон поставщика	PaymentAgentMode	Нет	- формат передачи телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
PaymentAgentMode	Нет11	Число		Пусто	Признак агента
Productmarkinguuid	Да/Нет12	255 символов	Пусто	Дополнительный реквизит чека
UserRequisites	Нет	структура {"name": <string(64)>, "value": <string(256)>}	Пусто	Дополнительные реквизиты пользователя

...

¹Обязательным является один из двух параметров Payment_ID (если осуществляется фискализация внешнего платежа) и Billnumber (если осуществляется фискализация платежа в АПК Ассист, выполненного ранее). Если передается параметр Billnumber и фискальный чек по данной операции уже существует в любом статусе, то выдается ошибка «Фискальный чек уже создан».

...

²Уникальность Payment_ID контролируется в рамках конкретного предприятия для типа чеков sell и sell_refund и статусов фискального чека:

...

	Идентификатор запроса, полученный предприятием от системы маркировки «Честный знак» во время проверки товара.
Productmarkingtimestamp	Да/Нет12	Число		Время запроса, полученное предприятием от системы маркировки «Честный знак».
Productmarkingfoiv	Да/Нет12	3 символа		Идентификатор ФОИВ
Productmarkingdocdate	Да/Нет12	DD.MM.YYYY		Дата документа основания
Productmarkingdocid	Да/Нет12	32 символа		Номер документа основания
DocumentRequisite	Нет	16 символов	Пусто	Дополнительный реквизит чека
UserRequisites	Нет	структура {"name": <string(64)>, "value": <string(256)>}	Пусто	Дополнительные реквизиты пользователя

Anchor
1 1

¹Обязательным является один из двух параметров Payment_ID (если осуществляется фискализация внешнего платежа) и Billnumber (если осуществляется фискализация платежа в АПК Ассист, выполненного ранее). Если передается параметр Billnumber и фискальный чек по данной операции уже существует в любом статусе, то выдается ошибка «Фискальный чек уже создан».

Anchor
2 2

²Уникальность Payment_ID контролируется в рамках конкретного предприятия для типа чеков sell и sell_refund и статусов фискального чека:

Если для данного MerchantID, для данного Payment_ID и типов sell или sell_refund уже создан фискальный чек, то при статусах фискального чека New, InProgress, Requested, ErrorRe, Success выдается ошибка – «Фискальный чек создан или находится в обработке».

Если для данного MerchantID, данного Payment_ID и типов sell или sell_refund фискальный чек создан, но имеет статус Error

...

,

...

то создается новый чек.

Warning

При частичных отменах в рамках одного платежа параметр Payment_ID каждого отдельного возврата должен быть уникальным. Если предприятие не может обеспечить уникальность параметра Payment_ID для частичных отмен (например, передает в этом поле один и тот же номер заказа), то при фискализации возврата типа sell_refund можно не передавать этот параметр, что обеспечит фискализацию более одной частичной отмены для данного заказа. При этом нужно иметь в виду, что отсутствие параметра Payment_ID отменяет проверку на уникальность и может привести к повторной фискализации одной и той же отмены, если запрос на ее фискализацию был послан вторично.

...

Если для данного MerchantID, данного Payment_ID и типов sell или sell_refund фискальный чек создан, но имеет статус CreateError, то новый чек будет создан только в том случае, если присланный состав чека (позиции чека, суммы, параметры фискализации) отличается от первоначального (исправленный чек). Если чек совпадает с ранее созданным чеком, то выдается ошибка – «Фискальный чек создан или находится в обработке».

Warning

При частичных отменах в рамках одного платежа параметр Payment_ID каждого отдельного возврата должен быть уникальным. Если предприятие не может обеспечить уникальность параметра Payment_ID для частичных отмен (например, передает в этом поле один и тот же номер заказа), то при фискализации возврата типа sell_refund можно не передавать этот параметр, что обеспечит фискализацию более одной частичной отмены для данного заказа. При этом нужно иметь в виду, что отсутствие параметра Payment_ID отменяет проверку на уникальность и может привести к повторной фискализации одной и той же отмены, если запрос на ее фискализацию был послан вторично.

Anchor
3 3

³Должен быть передан хотя бы один из параметров Email и Phone. Если Email и Phone не указаны, то необходимые данные для контакта с плательщиком извлекаются из настроек предприятия. Если переданы оба параметра Email и Phone, то для контакта с плательщиком будет использоваться параметр Email.

Anchor
4 4

⁴Обязательным является один из двух параметров PaymentType (если при

...

³Должен быть передан хотя бы один из параметров Email и Phone. Если Email и Phone не указаны, то необходимые данные для контакта с плательщиком извлекаются из настроек предприятия. Если переданы оба параметра Email и Phone, то для контакта с плательщиком будет использоваться параметр Email.

Anchor44⁴Обязательным является один из двух параметров PaymentType (если при платеже использовался единственный вид оплаты) и PaymentTypes (если для фискализируемого платежа использовались несколько видов оплаты). Если в запросе передается параметр Billnumber, то параметр PaymentType/PaymentTypes либо должен соответствовать операциям платежа (отмены) с этим номером, либо может вообще не передаваться, т.е. становится необязательным.

Anchor
5 5

⁵Параметр TaxationSystem задается является обязательным только для чека коррекции.

Anchor
6 6

⁶Параметр TaxationSystem задается для всего чека в целом ( всего чека в целом (не передается в позициях чека). Если параметр не передан, то его значение берется из настроек предприятия. Если у предприятия не настроено значение параметра TaxationSystem по умолчанию, то в ККТ этот параметр (тег 1055) не отправляется и ККТ будет проводить чек по собственным настройкам. Это возможно только в том случае, если в ККТ настроена только одна система налогообложения, в противном случае ККТ выдаст ошибку.

Anchor
676 7

⁶⁷Состав чека (поля с названием, стоимостью за единицу товара/услуги, ставкой налога и способом расчета по каждой позиции) определяется по следующим правилам.

...

если настройки предприятия для этих параметров отсутствуют, то обработка запроса завершается с ошибкой (недостаточно данных для выполнения операции).

Anchor
787 8

⁷⁸В зависимости от режима, в котором предприятие эксплуатирует ККТ, параметр может быть как обязательным, так и необязательным. Необходимость передачи этого параметра следует уточнить в отделе технической поддержки.

Anchor
898 9

⁸⁹Разрешается передавать либо параметр Cashier, либо параметр PaymentTerminal.  Одновременно эти параметры передаваться не могут, поскольку соответствуют разным типам касс.

Anchor
910 9

⁹Рекомендуется передавать телефонные номера в формате +7ХХХХХХХХХХ или 8ХХХХХХХХХХ.

Перечень возвращаемых параметров:

10

¹⁰ Если параметр будет передан в формате, не соответствующем указанному, то при фискализации его значение будет изменено на null.

Anchor
11 11

¹¹Параметр может заполняться только для ФФД 1.05 и 1.1. Для ФФД 1.2 параметр передается только в позициях чека.

Anchor
12 12

¹²Параметр обязателен для маркированных товаров, подлежащих обязательной проверке перед продажей. Для обсуждения возможности использования параметра следует обратиться в службу поддержки support@assist.ru.

Перечень возвращаемых параметров:

Значение

Название	Значение
fiscalreceipt_ID	Идентификатор созданного фискального чека
Payment_ID	Идентификатор чека в системе предприятия (если есть)
Type	Тип фискализируемого платежа:
Название
fiscalreceipt_ID	Идентификатор созданного фискального чека
Payment_ID	Идентификатор чека в системе предприятия (если есть)
Type	Тип фискализируемого платежа: sell – оказание услуг; sell_refund – возврат.
receipttype	Тип чека: normal – чек при фискализации оплаты или отмены; correct – чек коррекции.
ReceiptReceipt_status	Статус созданного фискального чека
или
Сообщение об ошибке (если переданы некорректные параметры или не все обязательные параметры)
(чека коррекции): New – чек подготовлен к формированию; CreateError - при создании чека возникла ошибка.

Процесс фискализации является асинхронным, поэтому в ответе веб-сервиса в большинстве случаев будет возращен статус чека New. Это означает, что чек создан и поставлен в очередь на кассу для фискализации. После получения данных о создании фискального чека в статусе New рекомендуется После получения данных о создании фискального чека в статусах New, InProgress, ErrorRe, Requested рекомендуется через несколько минут дополнительно запросить данные фискального чека с помощью веб-сервиса fiscalreceipt (о веб-сервисе fiscalreceipt подробнее см.  «Получение фискального чека») для того , чтобы убедиться , что создание в успешном завершении создания фискального чека успешно завершено. 

Если запрос на фискализацию не может быть обработан, в результате запроса вернутся ненулевые значения параметров firstcode, secondcode.

Сервис пакетной фискализации

Веб-сервис предназначен для одновременной фискализации нескольких операций (пакета операций). Пакетная фискалиация может использоваться, например, в следующих случаях:

• если осуществляется отмена заказа по инициативе покупателя с удерживанием определенной суммы штрафа (комиссии) за такую отмену, при этом необходимо сформировать два отдельных фискальных чека – на полную отмену платежа и на оплату штрафа;
• если необходима фискализация заказа с большим количеством позиций, при этом фискализацию можно разбить на несколько отдельных чеков, связанных с одним заказом.

Веб-сервис позволяет предприятию получить уникальные идентификаторы сгенерированных в АПК Ассист фискальных чеков на основе данных, переданных в запросе.

Для обращения к веб сервису необходимо отправить запрос методом JSON на сервер АПК Ассист по адресу: https://<SERVER_NAME>/fiscal/batchfiscalize.cfm.

Входные параметры сервиса:

...

Параметр

...

Обязательное поле

...

Принимаемые значения

...

Значение по умолчанию

...

Описание

Полученный в ответе на запрос статус CreateError означает, что чек не может быть сформирован и отправлен на фискализацию.  В этом случае следует убедиться в корректности отправляемых данных (состав позиций чека, наличие обязательных атрибутов фискализации, непротиворечивость параметров и т.д.), также рекомендуется  запросить данные с помощью веб-сервиса fiscalreceipt и проверить полученный в поле errortext текст ошибки, затем можно повторно направить скорректированный запрос на фискализацию. 
Если чек находится в статусе New, то отправлять его на фискализацию повторно нельзя.

Если запрос на фискализацию не может быть обработан, в результате запроса вернутся ненулевые значения параметров firstcode, secondcode.

Веб-сервис пакетной фискализации

Веб-сервис предназначен для одновременной фискализации нескольких операций (пакета операций). Пакетная фискалиация может использоваться, например, в следующих случаях:

• если осуществляется отмена заказа по инициативе покупателя с удерживанием определенной суммы штрафа (комиссии) за такую отмену, при этом необходимо сформировать два отдельных фискальных чека – на полную отмену платежа и на оплату штрафа;
• если необходима фискализация заказа с большим количеством позиций, при этом фискализацию можно разбить на несколько отдельных чеков, связанных с одним заказом.

Веб-сервис позволяет предприятию получить уникальные идентификаторы сгенерированных в АПК Ассист фискальных чеков на основе данных, переданных в запросе.

Для обращения к веб сервису необходимо отправить запрос методом JSON на сервер АПК Ассист по адресу: https://<SERVER_NAME>/fiscal/batchfiscalize.cfm.

Входные параметры сервиса:

¹Должен быть передан хотя бы один из параметров Email и Phone. Если Email и Phone не указаны, то необходимые данные для контакта с плательщиком извлекаются из настроек предприятия. Если переданы оба параметра Email и Phone, то для контакта с плательщиком будет использоваться параметр Email.

Параметры элемента массива Cheques[]

Перечень возвращаемых параметров:

Процесс фискализации является асинхронным, поэтому для большинства чеков в ответе будет возвращен статус New - чек подготовлен к формированию. Результат фискализации и подробности по каждому отдельному чеку могут быть получены с помощью веб-сервиса получения фискального чека fiscalreceipt.cfm или веб-сервиса получения нескольких фискальных чеков fiscalreceipts.cfm.

...

Merchant_ID

...

Да

...

Число

...

Идентификатор предприятия в системе АПК Ассист

...

Login

...

Да

...

20 символов

...

Логин пользователя сервиса от предприятия

...

Password

...

Да

...

30 символов

...

Пароль пользователя сервиса от предприятия

...

Billnumber

...

Да

...

16 цифр расширенный формат

...

Расширенный номер платежа, соответствующий выполненному ранее платежу или выполненной ранее отмене в системе АПК Ассист

...

Email

...

Да/Нет¹

...

128 символов

...

E-mail адрес для отправки фискального чека

...

Phone

...

Да/Нет¹

...

Число

...

Номер телефона для отправки фискального чека (без +7)

...

Language

...

Нет

...

RU - русский,

EN - английский

...

Язык предприятия

...

Язык отправляемого письма (RU/EN)

...

Cheques

...

Да, хотя бы один элемент

...

Строка в формате JSON

...

Набор/массив данных чеков. Каждый чек содержит параметры, используемые сервисом fiscalize.cfm (кроме параметров login / password / billnumber / Payment_ID /Email / Phone), а также дополнительный параметр chequeid (см. табл. ниже).

...

¹Должен быть передан хотя бы один из параметров Email и Phone. Если Email и Phone не указаны, то необходимые данные для контакта с плательщиком извлекаются из настроек предприятия. Если переданы оба параметра Email и Phone, то для контакта с плательщиком будет использоваться параметр Email.

Параметры элемента массива Cheques[]

...

Параметр

...

Обязательное поле

...

Принимаемые значения

...

Значение по умолчанию

...

Описание

...

chequeid

...

Да

...

Число

...

Идентификатор чека в массиве. Используется для указания на чек, при формировании которого произошла ошибка.

...

Type

...

Да

...

Строка

...

Тип фискализируемого платежа:

·          sell – оказание услуг;

·          sell_refund – возврат.

...

PaymentType

...

... все остальные параметры сервиса Fiscalize, начиная c PaymentType за исключением параметров Format и Language.

...

…

...

UserRequisites

Пример запроса с минимальным набором параметров:

...

{
    "billnumber":"123445678899012.1",
    "cheques":[
        {
            "chequeid":1,
            "fiscalreceiptid":"12123123",
            "status":"NEWNew"
        },
        {
            "chequeid":2,
            "fiscalreceiptid":"12123124",
            "status":"IN_PROGRESSNew"
        }
    ]
}

Подробности по каждому отдельному чеку могут быть получены с помощью

веб-сервиса получения фискального чека fiscalreceipt.cfm.

...

Наверх