Чеки (фискализация)
Фискализация платежей АТОЛ Pay - блок receipt, справочники значений, агенты и поставщики.
Для проведения оплат с чеком передавайте поле receipt в
методе регистрации платежа
или в методах подписок. Чек будет автоматически
отправлен в провайдер фискализации (АТОЛ Онлайн) после успешной оплаты.
Важно
Транзакция не отменяется, если чек отправился неуспешно. Если при успешном
статусе оплаты получена ошибка фискализации, транзакция будет проведена
независимо от того, удалось ли отправить чек. Отслеживайте
callback типа fiscal.
Блок receipt
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
buyer | Данные покупателя для чека | Нет | object |
buyer.email | Email покупателя, куда отправляется чек. Обязателен, если передан объект buyer; иначе используется email с платежной формы | Да, внутри buyer | string(64) |
positions | Блок с данными о покупках | Да | array |
providerId | Внутренний ID провайдера фискализации: 100 - АТОЛ Онлайн | Да | number |
sno | Система налогообложения (см. ниже) | Да | number |
Поле type передавать не нужно
Тип чека определяется самой операцией: регистрация платежа дает чек «Приход»,
отмена/возврат - «Возврат прихода». Поля type в блоке receipt
OpenAPI-спецификации нет, лишние поля игнорируются.
Системы налогообложения (sno)
Значения соответствуют порядку реквизита «Системы налогообложения»
(тег 1055) и совпадают со строковыми значениями company.sno
АТОЛ Онлайн v5.
| Код | Значение | sno в АТОЛ Онлайн v5 |
|---|---|---|
| 0 | Общая СН | osn |
| 1 | Упрощенная СН, доходы | usn_income |
| 2 | Упрощенная СН, доходы минус расходы | usn_income_outcome |
| 3 | ЕНВД - режим упразднен с 01.01.2021 и в словаре АТОЛ Pay отсутствует | envd |
| 4 | Единый сельскохозяйственный налог (ЕСХН) | esn |
| 5 | Патентная СН (ПСН) | patent |
Расхождение в источниках
В таблице параметров блока receipt документа «Интеграция c API АТОЛ Pay Ecom»
(с. 28) перечислены только значения 0–4, причем 3 указан как ЕСХН, а 4 - как
патент. Это расхождение с ответом самого сервиса: метод
словарей в том же документе возвращает
4 - «ЕСН» и 5 - «Патент» (без 3), а OpenAPI-спецификация задает диапазон
0…5. Ориентируйтесь на словарь - он совпадает и с порядком тега 1055,
и с перечнем sno АТОЛ Онлайн v5.
Актуальный перечень значений всегда отдает метод словарей.
Блок positions
| Параметр | Описание | Обяз. | Формат |
|---|---|---|---|
name | Наименование позиции | Да | string |
price | Цена за единицу в копейках, 0…2000000000 (1000 = 10.00 ₽) | Да | number |
quantity | Количество предмета расчета × 1000, 1…2000000000 (999000 = 999.000) | Да | number |
measure | Единица измерения (см. ниже) | Да | number |
paymentMethod | Признак способа расчета (см. ниже) | Да | number |
paymentSubject | Признак предмета расчета - значения в методе словарей | Да | number |
tax | Ставка НДС (см. ниже) | Да | number |
isAgent | Флаг агентского предмета расчета | Нет | boolean |
agentId | ID агента из ЛК (Настройки > Настройки заказов > Агент); содержит все обязательные данные агента согласно 54-ФЗ | Да, если isAgent: true | string |
supplierId | ID поставщика из ЛК (Настройки > Настройки заказов > Поставщики) | Да, если isAgent: true | string |
Единицы измерения (measure)
| Код | Значение | Код | Значение | |
|---|---|---|---|---|
| 0 | Поштучно или единицами | 12 | Кубический метр | |
| 1 | Грамм | 13 | Киловатт-час | |
| 2 | Килограмм | 14 | Гигакалория | |
| 3 | Тонна | 15 | Сутки (день) | |
| 4 | Сантиметр | 16 | Час | |
| 5 | Дециметр | 17 | Минута | |
| 6 | Метр | 18 | Секунда | |
| 7 | Квадратный сантиметр | 19 | Килобайт | |
| 8 | Квадратный дециметр | 20 | Мегабайт | |
| 9 | Квадратный метр | 21 | Гигабайт | |
| 10 | Миллилитр | 22 | Терабайт | |
| 11 | Литр | 100 | Иные единицы измерения |
Признак способа расчета (paymentMethod)
| Код | Значение |
|---|---|
| 0 | Предоплата 100% |
| 1 | Частичная предоплата |
| 2 | Предварительная оплата (аванс) |
| 3 | Полный расчет |
| 4 | Частичный расчет и кредит |
| 5 | Передача в кредит |
| 6 | Оплата кредита |
Ставка НДС (tax)
| Код | Значение | Код | Значение | |
|---|---|---|---|---|
| 0 | НДС 20% | 6 | НДС 5% | |
| 1 | НДС 10% | 7 | НДС 7% | |
| 2 | НДС расч. 20/120 | 8 | НДС расч. 5/105 | |
| 3 | НДС расч. 10/110 | 9 | НДС расч. 7/107 | |
| 4 | НДС 0% | 10 | НДС 22% | |
| 5 | НДС не облагается | 11 | НДС расч. 22/122 |
Ставка 22% подтверждена
Коды 10 и 11 соответствуют ставкам НДС 22% и НДС расч. 22/122 -
так их возвращает словарь vatTaxes в документе «Интеграция c API АТОЛ Pay
Ecom». В АТОЛ Онлайн v5 тем же ставкам соответствуют строковые значения
vat22 и vat122 (добавлены в версии 3.12 описания протокола от 09.12.2025).
Получение словарей для чеков
GET /v1/ecom/receipts/dictionariesВозвращает актуальные справочники значений: vatTaxes (ставки НДС),
paymentSubjects (предметы расчета), paymentMethods (способы расчета),
agentTypes (типы агентов: another, commission_agent, attorney,
bank_paying_agent, bank_paying_subagent, paying_agent,
paying_subagent), measures (единицы измерения), sno
(системы налогообложения). Каждый элемент содержит id, name и, где
применимо, shortName (он есть у vatTaxes и measures).
Состав справочника paymentSubjects шире привычного минимума и включает
свежие предметы расчета - например, 17 «Туристический налог», 25 «Платеж
казино», 20–24 для взносов на ОПС и ОМС. Не зашивайте список в код:
берите его из этой ручки.
{
"paymentSubjects": [
{ "id": 0, "name": "Товар" },
{ "id": 9, "name": "Платеж" },
{ "id": 17, "name": "Туристический налог" },
{ "id": 25, "name": "Платеж казино" }
]
}Состав справочников подтвержден реальным запросом к тестовому контуру:
приходят шесть наборов - vatTaxes (12 значений), paymentSubjects (26),
paymentMethods (7), agentTypes (7), measures (24), sno (5).
В sno действительно отсутствует ЕНВД (3), а vatTaxes содержит
коды 10 и 11 для ставок 22 % и 22/122.
{
"status": "success",
"data": {
"vatTaxes": [
{ "id": 0, "name": "НДС 20%", "shortName": "20%" },
{ "id": 5, "name": "Без НДС", "shortName": "Без НДС" }
],
"sno": [
{ "id": 0, "name": "Общая СН" },
{ "id": 1, "name": "УСН Доход" }
]
}
}Получение списка агентов
GET /v1/ecom/receipts/agentsВозвращает агентов, добавленных ранее в личном кабинете: id, наименование,
флаг по умолчанию (isDefault) и активность (isActive).
{
"status": "success",
"data": {
"agents": [
{
"id": "c0ec97c0-7003-467b-be53-5da2312b7eb0",
"name": "ООО Агент",
"isDefault": true,
"isActive": true
}
]
}
}Получение списка поставщиков
GET /v1/ecom/receipts/suppliersАналогично агентам - возвращает поставщиков из личного кабинета.
{
"status": "success",
"data": {
"suppliers": [
{
"id": "c0ec97c0-7003-467b-be53-5da2312b7eb0",
"name": "ООО Поставщик",
"isDefault": true,
"isActive": true
}
]
}
}Callback фискализации
После отправки чека придет callback с type: "fiscal" - подробности в разделе
Callback-уведомления.