www.assist.ru

Versions Compared

Old Version 37

changes.mady.by.user Oksana Chizhikova

Saved on

compared with

New Version Current

changes.mady.by.user Oksana Chizhikova

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

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

...

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

Note

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

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

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

...

Параметр

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

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

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

Описание

Merchant_ID

Да

Число


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

Login

Да

20 символов


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

Password

Да

30 символов


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

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

Payment_ID

Нет1

255 символов


Идентификатор операции Уникальный идентификатор чека в системе предприятия2

Email

Да/Нет13

128 символов


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

Phone

Да/Нет13

Число


Номер телефона для отправки фискального чека чека  - стандартный номер с кодом страны (без +7), минимум 11 цифр.12

Type

Да

Строка


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

  • sell – оказание услуг;
  • sell_refund – возврат.

Если в запросе передается параметр Billnumber, то для фискализации платежа должен передаваться тип sell, а для фискализации отмены тип sell_refund.

PaymenttypePaymentType

Да/Нет4

Число


Вид оплаты

ReceiptType

Да/Нет5

Строка


Тип чека:

  • normal – чек при фискализации оплаты или отмены;
  • correct – чек коррекции.

CorrectionType

Да/Нет5

Строка


Тип коррекции:

  • self – самостоятельное решение о коррекции;
  • instruction – коррекция по предписанию надзорного органа.

CorrectionDocDate

Да/Нет5

DD.MM.YYYY


Дата корректируемого расчета

CorrectionDocID

Да/Нет5

Строка


Номер документа, на основании которого производится коррекция (для коррекции по предписанию)

PaymentTypesДа/Нет4Строка

Набор/массив пар значений видов оплаты и соответствующих им сумм:
{"Amount":<value>, "PaymentType":<PaymentType>}

Warning

Сумма значений Amount по всем использованным видам оплаты должна быть равна сумме чека.

TaxationSystem

Нет6

TaxationSystem

Нет4

Число

Из настроек предприятия или ККТ

Система налогообложения

Chequeitems

Да/Нет27

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


Позиции чека, см. «Работа с чеком».

Amount

Да

Число, 15 цифр ( знаков, два знака после разделителя (допустимые разделители «.», «,»)


Сумма операциичека
Если в запросе передается параметр Billnumber, то сумма чека должна равняться сумме платежа (или отмены).

Format

НетЧисло

1 – CSV
3 – XML
4 - SOAP
5 - JSON

1

Формат возвращаемого ответа.Формат возвращаемого ответа (1-CSV, 2-WDDX, 3-XML, 4-SOAP)

Language

Нет

RU - русский,

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

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

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

ReceiptLine

Да/Нет27

128 символов


Позиция чека (для чеков с единственной позицией)

Tax

Да/Нет27

10 символов


Идентификатор ставки налога

FPMode

Да/Нет27

Число


Способ расчета

LastNameНет70 символовПустоФамилия покупателя
FirstNameНет70 символовПустоИмя покупателя
MiddleNameНет70 символовПустоОтчество покупателя
CustomerDocIDНет11 символовПустоСерия/номер паспорта покупателя
TaxpayerIDНет12 символовПустоИНН покупателя
CompanyNameНет256 символовПустоНаименование компании (если покупатель – юридическое лицо)
PaymentAddressНет256 символовПустоАдрес расчетов
PaymentPlaceДа/Нет8256 символовПустоМесто расчетов
CashierДа/Нет864 символаПустоКассир
CashierINN10Да/Нет812 цифровых символовПустоИНН кассира
PaymentTerminalДа/Нет920 символовПустоНомер автоматического устройства
TransferOperatorPhone10Нет1119 символовПустоТелефон оператора перевода - формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
TransferOperatorNameНет1164 символаПустоНаименование оператора перевода
TransferOperatorAddressНет11256 символовПустоАдрес оператора перевода
TransferOperatorINN10Нет1110 цифровых символовПустоИНН оператора перевода
PaymentReceiverOperatorPhone10Нет1119 символовПустоТелефон оператора по приёму платежей - формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
PaymentAgentOperationНет1124 символаПустоОперация платёжного агента
PaymentAgentPhone10Нет1119 символовПустоТелефон платёжного агента - формат телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
SupplierPhone10Нет1119 символовПустоТелефон поставщика - формат передачи телефонного номера ХХХХХХХХХХХ (без +, без разделителей), начиная с кода страны, минимум 11 цифр.
PaymentAgentModeНет11ЧислоПустоПризнак агента
ProductmarkinguuidДа/Нет12255 символов
Идентификатор запроса, полученный предприятием от системы маркировки «Честный знак» во время проверки товара.
ProductmarkingtimestampДа/Нет12Число
Время запроса, полученное предприятием от системы маркировки «Честный знак».
ProductmarkingfoivДа/Нет123 символа
Идентификатор ФОИВ
ProductmarkingdocdateДа/Нет12DD.MM.YYYY
Дата документа основания
ProductmarkingdocidДа/Нет1232 символа
Номер документа основания
DocumentRequisiteНет16 символовПустоДополнительный реквизит чека
UserRequisitesНетструктура {"name": <string(64)>, "value": <string(256)>}ПустоДополнительные реквизиты пользователя

Anchor
1
1


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

Anchor
2
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, то создается новый чек.

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

Warning

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

Anchor
3
3


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

Anchor
4
4


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

Anchor
5
5


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

Anchor
6
6


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

Anchor
7
7


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

  1. Если в запросе передана структура ChequeItems (см.  «Работа с чеком»), то формируется чек с количеством позиций по числу переданных в ChequeItems строк, в каждой позиции должны быть обязательно указаны параметры:
    • product и/или name;
    • price;
    • quantity;
    • amount;

при этом:

название каждой из позиций формируется как объединение параметров product и name через пробел (если переданы оба) или как один из параметров product или name соответственно (если передан только один);если параметры Tax или FPmode не переданы в позициях, то они могут быть переданы в параметрах запроса (в этом случае значения этих параметров будут одинаковыми для всех позиций чека, переданных в ChequeItems);

...

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

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

...

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


Anchor
8
8


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

Anchor
9
9


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


Anchor
10
10


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

Anchor
11
11


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

Anchor
12
12


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

Warning

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

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


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

Название

Значение

fiscalreceipt_ID

Идентификатор созданного фискального чека

Payment_ID

Идентификатор операции чека в системе предприятия (если есть)

Type

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

  • sell – оказание услуг;
  • sell_refund – возврат.

receipttype

Тип чека:

  • normal – чек при фискализации оплаты или отмены;
  • correct – чек коррекции.

Receipt_status

Статус созданного фискального чека

или

Сообщение об ошибке (если переданы некорректные параметры или не все обязательные параметры)

(чека коррекции):

  • New – чек подготовлен к формированию;
  • CreateError - при создании чека возникла ошибка.

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

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

Warning
titleВнимание!

Если в ответе на запрос данных фискального чека через веб-сервис fiscalreceipt в течение длительного времени (несколько часов) по-прежнему приходит статус New (особенно в том случае, когда поле errortext ответа не пустое), следует обратиться в службу технической поддержки support@assist.ru.

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

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

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

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

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

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

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

Параметр

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

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

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

Описание

Merchant_ID

Да

Число


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

Login

Да

20 символов


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

Password

Да

30 символов


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

Billnumber

Да

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


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

Email

Да/Нет1

128 символов


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

Phone

Да/Нет1

Число


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

Language

Нет

RU - русский,

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

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

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

Cheques

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

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


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

Anchor
10
10


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

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

Параметр

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

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

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

Описание

chequeid

Да

Число


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

Note

Осуществляется проверка на уникальность идентификатора чека.

Type

Да

Строка


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

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

·          sell_refund – возврат.

PaymentType




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

…




UserRequisites




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

Название

Значение

billnumber

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

cheques

Набор/массив данных чеков






Параметры элемента массива чеков

Название

Значение

chequeid

Идентификатор чека в массиве

fiscalreceipt_ID

Идентификатор созданного фискального чека

status

Статус созданного фискального чека (чека коррекции):

  • New – чек подготовлен к формированию;
  • CreateError - при создании чека возникла ошибка.

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

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

Code Block
languagexml
{ 
    "merchant":{
        "merchant_ID":12345677,
        "login":"user",
        "password":"password"
    }, 
    "billnumber":"123445678899012.1",
    "customer":{
        "email":"customer@e.mail",
        "phone":"1376124761"
    },
    "cheques":[
        {
            "chequeid":1,
            "type":"sell",
            "paymenttype":1,
            "chequeitems":[
                {
                    "id":1,
                    "name":"товар",
                    "price":3.20,
                    "quantity":13,
                    "amount":41.6,
                    "tax":"vat20",
                    "fpmode":4
                },
                {
                    "id":2,
                    "name":"услуга",
                    "price":3.20,
                    "quantity":13,
                    "amount":41.6,
                    "tax":"vat20",
                    "fpmode":4
                }
            ],
            "amount":83.2
        },
        {
            "chequeid":2,
            "type":"sell",
            "paymenttypes":[
            {
                 "paymenttype":1,
                 "amount":20
            },
            {
                "paymenttype":21,
                "amount":21.6
            }
        ],
        "chequeitems":[
            {
                "id":1,
                "name":"товар",
                "price":3.20,
                "quantity":13,
                "amount":41.6,
                "tax":"vat20",
                "fpmode":4
            }
        ],
        "amount":41.6
        }
    ]
}

Ответ в формате JSON содержит либо массив сформированных чеков (включая их статусы и идентификаторы), либо сообщение об ошибке с указанием ID чека, на котором она произошла.

Пример ответа:

Code Block
languagexml
{
    "billnumber":"123445678899012.1",
    "cheques":[
        {
            "chequeid":1,
            "fiscalreceiptid":"12123123",
            "status":"New"
        },
        {
            "chequeid":2,
            "fiscalreceiptid":"12123124",
            "status":"New"
        }
    ]
}


Наверх