API для выдачи чека 54-ФЗ с перечнем товаров
Корзина товаров
При покупках в интернет магазинах клиенты, чаще всего, приобретают более одного товара. В такой ситуации, для соответствия 54-ФЗ в налоговую необходимо передавать чек покупки со сведениями обо всех приобретённых товарах и услугах. Обычно, сформировать список покупок в конкретном заказе не составляет труда, поскольку при оформлении заказа, в большинстве современных решений для интернет-магазина, используется так называемая корзина товаров (по аналогии с корзинкой для товаров в супермаркетах), которую покупатель наполняет, просматривая витрину интернет магазина.
Для формирования чека нужно при инициализации оплаты передать содержимое этой корзины. Чтобы это сделать, нужно сформировать JSON-массив объектов товарных позиций и передать в параметре cart POST-запроса на создание платежа, вместе с остальными параметрами платежа.
Формат одного объекта товарной позиции следующий:
| Поле | Назначение | Обязательное |
| name | Наименование экземпляра товара. Строка, не более 128 символов длиной. | Да |
| price | Стоимость единичного экземпляра товара | Да |
| quantity | Количество экземпляров товара в данной позиции | Да |
| sum | Полная сумма к уплате по данной товарной позиции, включая НДС | Да |
| tax | Код налога, применяющегося к данной позиции | Да |
| item_type | Код признака предмета расчёта (категория товара/услуги). Значение по умолчанию – «ТОВАР» | Нет |
| payment_type | Код признака способа расчёта. Значение по умолчанию – «Оплата в момент передачи». До версии 2.6.0 – «Предоплата 100%» | Нет |
| Следующие поля требуются только в отдельных случаях | ||
| item_code | Код товарной номенклатуры, строка в base64 | Нет |
| item_country | Страна происхождения товара, трёхциферный код по ОКСМ | Нет |
| customs_declaration | Номер грузовой таможенной декларации | Нет |
| excise | Сумма акциза | Нет |
| Следующие два поля нужны при работе по агентской схеме | ||
| agent | Объект с информацией об агенте | Нет |
| supplier | Объект с информацией о поставщике | Нет |
| Таблица 1. Поля объекта товарной позиции | ||
Параметры item_type и payment_type обязательные, но платёжная система подставит значения по умолчанию, если они не переданы. Параметры item_code , item_country , customs_declaration , excise могут быть обязательны в особых случаях.
Если применяется агентская схема работы, а все элементы корзины имеют одинакового поставщика или агента, то информацию о них достаточно указать в общих свойствах чека. Иначе, если в каждой товарной позиции свой агент или поставщик, то по каждому из них должны быть заполнены свойства agent и supplier .
Типы НДС товарной позиции
Для поля tax предусмотрены следующие возможные коды:
| Код | Значение |
| none | НДС не облагается |
| vat0 | НДС 0% |
| vat10 | НДС 10% |
| vat20 | НДС 20% |
| vat110 | НДС 10/110 |
| vat120 | НДС 20/120 |
| Таблица 2. Типы налогов | |
Все поля данного объекта должны быть в кодировке UTF-8.
Также, необходимо обратить внимание – ставки “НДС 0%” и “НДС не облагается” применяются в разных случаях. Для предприятий работающих по упрощённой схеме налогообложения нужно указывать none – “НДС не облагается”.
Сумма полных стоимостей товарных позиций должна быть равна полной стоимости заказа.
Атрибуты товара и платежа ФФД 1.05
Для соответствия ФФД 1.05 для каждой товарной позиции указывать код признака предмета расчёта и код признака расчёта. Для этих целей введены два необязательных поля: item_type и payment_type соответственно.
Для поля item_type (фискальный тег 1212) предусмотрены следующие возможные коды:
| Код | Значение |
| goods | Товар |
| service | Услуга |
| work | Работа |
| excise | Подакцизный товар |
| ip | Интеллектуальная деятельность, права на интеллектуальную собственность |
| payment | Аванс, задаток, предоплата, взнос или другой платёж |
| agent | Вознаграждение агента |
| property_right | Передача имущественного права |
| non_operating | Внереализационный доход |
| sales_tax | Торговый сбор |
| resort_fee | Курортный сбор |
| other | Иной предмет расчёта |
| Таблица 3. Признаки предметов расчёта | |
Для поля payment_type (фискальный тег 1214) предусмотрены следующие возможные коды:
| Код | Значение |
| prepay | Предоплата 100% |
| part_prepay | Частичная предоплата |
| advance | Аванс |
| full | Полная оплата в момент передачи предмета расчёта |
| part_credit | Передача товара с последующей частичной оплатой в кредит |
| credit | Передача товара без оплаты с последующей полной оплатой в кредит |
| credit_payment | Оплата кредита |
| Таблица 4. Признаки способа расчёта | |
Общие свойства чека
Формат фискальных документов 1.05 позволяет передавать дополнительную информацию о продаже и товарах в случаях, если платёж принимается агентом. Если в чеке все товарные позиции реализуются одним агентом от одного поставщика, при инициализации платежа можно передать POST-параметр receipt_properties , содержащий json-кодированный объект дополнительных свойств чека, чтобы не дублировать эти же значения в каждой товарной позиции. Кроме того, в некоторых отраслях требуется передача расширенной информации о плательщике. В настоящее время поддерживаются следующие поля объекта:
| Поле | Назначение | Обязательное |
| agent | Объект с параметрами агента | Да, если платёж принимает агент |
| supplier | Объект с параметрами поставщика | Да, если платёж принимает агент |
| client | Объект с информацией о плательщике | В отдельных отраслях |
| Таблица 5. Дополнительные атрибуты чека | ||
Передача объекта агента и поставщика не обязательна, если в настройках сервера с платёжной системы на стадии настройки 54-ФЗ уже были указаны атрибуты агента по умолчанию. Тогда они будут применяться для каждого чека и каждой товарной позиции.
Формат объекта агента
Объект с информацией об агенте может включаться в общие свойства чека или указываться для отдельной товарной позиции. Он имеет следующие свойства:
| Поле | Назначение | Обязательное |
| type | Тип агента | Да |
| phones | Массив строк номеров телефонов агента в формате +79101234567 | Для bank_(sub)agent и payment_(sub)agent |
| operation | Наименование операции платёжного агента или субагента | Для банковских платёжных агентов или субагентов bank_(sub)agent |
| inn | ИНН оператора перевода | |
| name | Наименование оператора перевода | |
| address | Адрес оператора перевода | |
| transfer_phones | Телефоны оператора перевода платежа | |
| receiver_phones | Телефоны оператора по приёму платежа | Для платёжных агентов или субагентов payment_(sub)agent |
| Таблица 6. Описание агента | ||
Сумма длин номеров телефонов в каждом из параметров не должна быть более 19 символов. Возможные значения поля типа агента:
| Поле | Назначение |
| bank_agent | Банковский платёжный агент |
| bank_subagent | Банковский платёжный субагент |
| payment_agent | Платёжный агент |
| payment_subagent | Платёжный субагент |
| attorney | Поверенный |
| commissionaire | Комиссионер |
| other | Другой агент |
| Таблица 7. Виды агентов | |
Формат объекта поставщика
Объект с информацией о поставщике товара может присутствовать в общих свойствах чека, а может добавляться к отдельным товарным позициям. Имеет следующие свойства:
| Поле | Назначение |
| phones | Массив номеров телефонов поставщика в формате +79101234567 |
| inn | ИНН поставщика. |
| name | Наименование поставщика |
| Таблица 8. Свойства объекта поставщика | |
Сумма длин номеров телефонов не должна превышать 19 символов.
Формат объекта плательщика
Объект с информацией о плательщике может присутствовать в общих свойствах чека. Его вид следующий:
| Поле | Назначение |
| identity | Название организации-плательщика, или ФИО плательщика и его данные |
| inn | ИНН плательщика |
| Таблица 9. Информация о плательщике | |
Наличие этой структуры требуется в отдельных областях.
Корзина в счёте
Указать список товарных позиций и дополнительные свойства чека можно и при выставлении счёта через наш JSON API. В этом случае на размер результирующего объекта cart накладываются некоторые ограничения – в данный момент максимальная длина текста в переменной service_name составляет 10240 символов. Передавать объект нужно в переменной service_name с особыми метками:
|
1 |
;PKC|JSON_массив_объектов_товарных_позиций|;PKRP|JSON_объект_дополнительных_свойств_чека_если_нужно|; |
Примеры кода
Формирование корзины на PHP:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
"cart" => json_encode( array ( array ( "name" => 'Стол обеденный 2x3', "price" => 10.01, "quantity" => 1, "sum" => 10.01, "tax" => 'vat20', "tax_sum" => 1.53, "item_type" => 'goods', "payment_type" => 'prepay' ), array ( "name" => 'Книга о вкусной и здоровой пище', "price" => 1.01, "quantity" => 3, "sum" => 3.03, "tax" => 'vat10', "tax_sum" => 0.28 ) ) ) |
Формирование корзины на PHP, с созданием счёта через JSON API:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 |
<?php # Логин и пароль любого пользователя личного кабинета $user = "user"; $password = "password"; # имя или IP-адрес вашего сервера с PayKeeper $server = "example.server.paykeeper.ru"; # параметры платежа. Обязательной является только сумма. $payment_data = array ( "pay_amount" => 7.50, "clientid" => "Иванов Иван Иванович", "orderid" => "Заказ № 10", "client_email" => "test@example.com", # передача корзины товаров для формирования чека по 54-ФЗ "service_name" => ";PKC|".json_encode( array ( array ( "name" => 'Стол обеденный 2x3', "price" => 1.50, "quantity" => 1, "sum" => 1.50, "tax" => 'none', ), array ( "name" => 'Книга о вкусной и здоровой пище', "price" => 2, "quantity" => 3, "sum" => 6, "tax" => 'none', ) ))."|", "client_phone" => "8 (910) 123-45-67" ); $auth_header = array ( 'Authorization: Basic '.base64_encode("$user:$password") ); $context = stream_context_create(array ( 'http' => array ( 'header' => $auth_header ) ) ); $result = json_decode(file_get_contents("http://$server/info/settings/token", FALSE, $context), TRUE); $token = $result['token']; $request = array_merge($payment_data, array ('token'=>$token)); $request_string = http_build_query($request); $request_headers = array_merge($auth_header, array("Content-type: application/x-www-form-urlencoded")); $context = stream_context_create(array ( 'http' => array ( 'method' => 'POST', 'header' => $request_headers, 'content' => $request_string ) ) ); $result = json_decode(file_get_contents("http://$server/change/invoice/preview", FALSE, $context), TRUE); $invoice_id = $result['invoice_id']; # в этой переменной прямая ссылка на оплату с заданными параметрами. $link = "http://$server/bill/$invoice_id/"; echo $link; ?> |
Рассмотренные выше примеры кода позволяют сформировать и передать товарную корзину для дальнейшего корректного формирования чека, в соответствии с 54-ФЗ, на стороне поддерживаемого платёжной системы кассового решения.