Параметры для формирования чека

Attention. Это старая версия API. Переходите на API Яндекс.Кассы.

Параметры для передачи фискальных данных добавляются в стандартную платежную форму. Они обязательно передаются, если вы настраиваете взаимодействие со своей онлайн-кассой через Яндекс.Кассу (для этого необходимо подключить онлайн-кассу одного из наших партнеров и выставить соответствующие настройки в личном кабинете, см. Изменения в протоколе для работы по 54-ФЗ).

В форму добавляется один дополнительный параметр, в котором передаются все нужные данные — ym_merchant_receipt.

Изменения в чеках с 1 июля 2019 года

1 июля 2019 года вступили в силу новые поправки к 54-ФЗ. Теперь в некоторых случаях понадобится передавать Яндекс.Кассе дополнительные данные о пользователе и товаре.

Данные о пользователе

Появилась возможность передать дополнительные данные о пользователе (customer):

  • наименование пользователя (тег 1227) — fullName;
  • ИНН пользователя (тег 1228) — inn.

Онлайн-кассы, которые поддерживают новые параметры: Orange Data, АТОЛ Онлайн.

Attention. Параметр customerContact устарел — его всё еще можно использовать, но передавать номер телефона и электронную почту рекомендуется в объекте customer.
Дополнительные данные о товаре

Для каждого товара (items) можно передать:

  • код товара (тег 1162) — productCode;
  • код страны происхождения товара (тег 1230) — countryOfOriginCode;
  • номер таможенной декларации (тег 1231) — customsDeclarationNumber;
  • акциз товара (тег 1229) — excise.

Онлайн-кассы, которые поддерживают новые параметры: Orange Data, АТОЛ Онлайн (только код товара).

Переход на ФФД 1.05

С 1 января 2019 года вступает в силу новый формат фискальных документов (ФФД 1.05). Добавляются дополнительные параметры:
  • признак предмета расчета (paymentSubjectType);
  • признак способа расчета (paymentMethodType).

В протоколе эти параметры необязательные. В 2019 году они становятся обязательными для налоговой, но пока что онлайн-кассы обрабатывают их по-разному.

АТОЛ Онлайн

Чтобы передавать новые параметры, нужно поменять настройки на стороне АТОЛ. Как это сделать:

  1. Сначала настройте отправку дополнительных параметров по нашему протоколу.
  2. Потом зайдите в личный кабинет АТОЛ и перейдите на новый формат фискальных документов.

Обязательно в таком порядке: если вы выберете на стороне АТОЛ новый формат, а новые данные отправлять не будете, сломаются платежи или отправка чеков.

Orange Data, МодульКасса и Бизнес.Ру Онлайн-Чеки

Новые параметры можно передавать. Пока вы их не передаете, ваша онлайн-касса будет подставлять значения по умолчанию на своей стороне.

Дополнительный параметр для чека

Параметр Тип Описание

ym_merchant_receipt

string

Данные для формирования чека в формате JSON.

Формат данных для чека

Данные для чека передаются в JSON. Параметры customer и taxSystem (необязательный) передаются в формате «ключ»—«значение». Вместе с ними передается массив товаров, в который входят товары с характеристиками. Характеристики товара отправляются в одном объекте, для каждого товара формируется свой объект.

Пример данных в JSON

{
    "customer": {
        "email": "johndoe@yandex.ru"
    },
    "taxSystem": 1,
    "items": [{
        "quantity": 1.154,
        "price": {
            "amount": 300.23
        },
        "tax": 3,
        "text": "Зеленый чай \"Юн Ву\", кг",
        "paymentMethodType": "full_prepayment ",
        "paymentSubjectType": "commodity"
    }, 
    {
        "quantity": 2,
        "price": {
            "amount": 200.00
        },
        "tax": 3,
        "text": "Кружка для чая, шт., скидка 10%",
        "paymentMethodType": "full_prepayment",
        "paymentSubjectType": "commodity"
    }]
}

Параметры для чека

Параметр Тип Обязательность Описание

customerContact

string, 64 символа

Необязательный
Attention. Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в параметре customer.

Телефон или эл. почта покупателя.

Ограничения:

  • номер телефона в формате +79210000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.

taxSystem

int

Необязательный

Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.

Возможные значения — число от 1 до 6:

1 — общая СН;

2 — упрощенная СН (доходы);

3 — упрощенная СН (доходы минус расходы);

4 — единый налог на вмененный доход;

5 — единый сельскохозяйственный налог;

6 — патентная СН.

Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.

customer

Объект

Необязательный

Информация о пользователе.

См. Параметры вложенных объектов — customer

items Объект Обязательный

Товары

См. Параметры вложенных объектов — items

Параметры вложенных объектов

Параметр Тип Обязательность Описание
Пользователь (customer)

fullName

string, не более 256 символов

Необязательный

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.

inn

string

Необязательный

ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.

email

string

Обязательный, если не передан phone или customerContact.

Электронная почта пользователя для отправки чека.

phone

string

Обязательный, если не передан email или customerContact.

Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.

Товар (items)

quantity

Десятичное число с точностью 3 символа после запятой. Максимально возможное значение зависит от модели вашей онлайн-кассы

Обязательный

Количество товара. Описывает количество товаров в заказе или количество весового товара.

price

Объект

Обязательный

Цена товара.

amount

CurrencyAmount (десятичное число с точностью до 2 символов после точки)

Обязательный

Цена за единицу товара.

currency

CurrencyCode

Необязательный

Код валюты: RUB (рубль РФ).

tax

int

Обязательный

Ставка НДС. Возможные значения — число от 1 до 6:

1 — без НДС;

2 — ставка НДС 0%;

3 — ставка 10%;

4 — ставка 20%;

5 — расчетная ставка 10/110;

6 — расчетная ставка 20/120.

text

string, 128 символов

кириллица или латиница

Обязательный

Название товара.

Ограничения:

  • Специальные символы (например, кавычки) необходимо экранировать по правилам JSON. Пример: "text": "Зеленый чай \"Юн Ву\", кг"
paymentSubjectType string, 128 символов Необязательный Признак предмета расчета — категория этого товара для налоговой.
Возможные значения:
  • commodity — товар;

  • excise — подакцизный товар;

  • job — работа;

  • service — услуга;

  • gambling_bet — ставка в азартной игре;

  • gambling_prize — выигрыш в азартной игре;

  • lottery — лотерейный билет;

  • lottery_prize — выигрыш в лотерею;

  • intellectual_activity — результаты интеллектуальной деятельности;

  • payment — платеж;

  • agent_commission — агентское вознаграждение;

  • property_right — имущественные права;

  • non_operating_gain — внереализационный доход;

  • insurance_premium — страховой сбор;

  • sales_tax — торговый сбор;

  • resort_fee — курортный сбор;

  • composite — несколько вариантов;

  • another — другое.

paymentMethodType string, 128 символов Необязательный Признак способа расчета  — категория способа оплаты для налоговой.
Возможные значения:
  • full_prepayment — полная предоплата;

  • partial_prepayment — частичная предоплата;

  • advance — аванс;

  • full_payment— полный расчет;

  • partial_payment —  частичный расчет и кредит;

  • credit — кредит;

  • credit_payment — выплата по кредиту.

productCode string Обязательный параметр, если товар нужно маркировать

Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.

Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00.

countryOfOriginCode string Необязательный

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример: RU.

customsDeclarationNumber string, от 1 до 32 символов Необязательный

Номер таможенной декларации.

excise string, десятичное число с точностью до 2 символов после точки Необязательный

Сумма акциза товара с учетом копеек.

Пояснения

Контакты покупателя

  • Чтобы платеж прошел, необходимо передать контактные данные пользователя для отправки чека — синтаксически корректный номер телефона или адрес электронной почты. Эти данные нужно передать в объекте customer или в параметре customerContact.
    Attention. Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в объекте customer.
  • Чек покупателю доставляет ОФД (условия доставки зависят от вашего ОФД). Чеки приходят на мобильные номера российских операторов (они начинаются с +7). На иностранный мобильный номер чек может не дойти.

Количество товаров, вес, цена

  • В поле amount указывается цена за единицу товара, в поле quantity — количество. Если в amount указана цена за один товар, следует передавать количество штук (quantity=2, например, два одинаковых пирога). Если в amount указана цена за кг, следует передавать вес товара (quantity=1.253, например, пирог весом 1 кг 253 г).
  • Цена указывается без учета налогов.
  • Общая сумма, которую вы передаете в ym_merchant_receipt, должна совпадать с суммой в sum. Если они не совпадают, чек не сформируется, оплата может не пройти.
  • В ym_merchant_receipt можно передать не больше 100 товаров — то есть не больше 100 таких блоков: {"quantity": 1.154,"price": {"amount": 300.23},"tax": 3,"text": "Товар А"}
  • Информацию о скидке или предоплате можно добавить в название товара. Пример: "text": "Предоплата 30%, настольная игра \"Tea Time\""}

Пример платежной формы с параметрами для чека

<form action="https://money.yandex.ru/eshop.xml" method="post">
        <input name="shopId" value="1234" type="hidden"/>
        <input name="scid" value="4321" type="hidden"/>
        <input name="sum" value="746.47" type="hidden">
        <input name="customerNumber" value="abc000" type="hidden"/>
        <input name="paymentType" value="AC" type="hidden"/>
        <input name="orderNumber" value="abc1111111" type="hidden"/>
        <input name="cps_phone" value="+79123456543" type="hidden"/>
        <input name="cps_email" value="user@domain.com" type="hidden"/>
        <input name="ym_merchant_receipt" value='{"customerContact": "+79001231212","taxSystem": 1, "items":[{"quantity": 1.154, "price": {"amount": 300.23},  "tax": 3,"text": "Зеленый чай \"Юн Ву\", кг","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"},{"quantity": 2, "price": {"amount": 200.00},  "tax": 3,"text": "Кружка для чая, шт., скидка 10%","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"}]}'
        type="hidden"/>
        <input type="submit" value="Заплатить"/>
        </form>

Смотрите также

Изменения в протоколе для работы по 54-ФЗ

Отправка данных для чека