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

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

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

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

Для обращения к веб сервису необходимо отправить запрос методом POST/SOAP на сервер ASSIST по адресу: https://<SERVER_NAME>/fiscal/fiscalize.cfm.

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

Параметр

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

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

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

Описание

Merchant_ID

Да

Число


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

Login

Да

20 символов


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

Password

Да

30 символов


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

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

Payment_ID

Нет1

255 символов


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

Email

Да/Нет3

128 символов


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

Phone

Да/Нет3

Число


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

Type

Да

Строка


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

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

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

PaymentType

Да/Нет4

Число


Вид оплаты

ReceiptType

Да/Нет5

Строка


Тип чека:

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

CorrectionType

Да/Нет5

Строка


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

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

CorrectionDocDate

Да/Нет5

DD.MM.YYYY


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

CorrectionDocID

Да/Нет5

Строка


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

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

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

Сумма значений 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Нет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числоПустоПризнак агента
DocumentRequisiteНет16 символовПустоДополнительный реквизит чека
UserRequisitesНетструктура {"name": <string(64)>, "value": <string(256)>}ПустоДополнительные реквизиты пользователя


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


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, то новый чек будет создан только в том случае, если присланный состав чека (позиции чека, суммы, параметры фискализации) отличается от первоначального (исправленный чек). Если чек совпадает с ранее созданным чеком, то выдается ошибка – «Фискальный чек создан или находится в обработке».

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


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


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


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


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


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

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

при этом:

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

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

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

2. Если в запросе не передана структура ChequeItems, то формируется чек с одной позицией, в которой:

    • название позиции подставляется из параметра ReceiptLine, если он передан в запросе; если параметр ReceiptLine не передан в запросе, то название позиции подставляется из настроек предприятия; если настройки предприятия для этих параметров отсутствуют, то в качестве названия подставляется строка "Оплата заказа";
    • стоимость единицы товара/услуги подставляется из параметра запроса Amount;
    • количество всегда равно 1;

если параметры Tax или FPmode не переданы в параметрах запроса, то их значения подставляются из настроек предприятия;

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



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


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



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


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



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

Название

Значение

fiscalreceipt_ID

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

Payment_ID

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

Type

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

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

receipttype

Тип чека:

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

Receipt_status

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

или

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

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

Если запрос на фискализацию не может быть обработан, в результате запроса вернутся ненулевые значения параметров 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 (см. табл. ниже).


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

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

Параметр

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

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

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

Описание

chequeid

Да

Число


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

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

Type

Да

Строка


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

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

·          sell_refund – возврат.

PaymentType




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




UserRequisites




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

Название

Значение

billnumber

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

cheques

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






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

Название

Значение

chequeid

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

fiscalreceipt_ID

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

status

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

или


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

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

{ 
    "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 чека, на котором она произошла.

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

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

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

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


Наверх