Перейти к содержимому

Чеки (фискализация)

Фискализация платежей АТОЛ Pay - блок receipt, справочники значений, агенты и поставщики.

Для проведения оплат с чеком передавайте поле receipt в методе регистрации платежа или в методах подписок. Чек будет автоматически отправлен в провайдер фискализации (АТОЛ Онлайн) после успешной оплаты.

Важно

Транзакция не отменяется, если чек отправился неуспешно. Если при успешном статусе оплаты получена ошибка фискализации, транзакция будет проведена независимо от того, удалось ли отправить чек. Отслеживайте callback типа fiscal.

Блок receipt

ПараметрОписаниеОбяз.Формат
buyerДанные покупателя для чекаНетobject
buyer.emailEmail покупателя, куда отправляется чек. Обязателен, если передан объект buyer; иначе используется email с платежной формыДа, внутри buyerstring(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
agentIdID агента из ЛК (Настройки > Настройки заказов > Агент); содержит все обязательные данные агента согласно 54-ФЗДа, если isAgent: truestring
supplierIdID поставщика из ЛК (Настройки > Настройки заказов > Поставщики)Да, если isAgent: truestring

Единицы измерения (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/1208НДС расч. 5/105
3НДС расч. 10/1109НДС расч. 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).

Получение словарей для чеков

http
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 для взносов на ОПС и ОМС. Не зашивайте список в код: берите его из этой ручки.

json
{
  "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.

json
{
  "status": "success",
  "data": {
    "vatTaxes": [
      { "id": 0, "name": "НДС 20%", "shortName": "20%" },
      { "id": 5, "name": "Без НДС", "shortName": "Без НДС" }
    ],
    "sno": [
      { "id": 0, "name": "Общая СН" },
      { "id": 1, "name": "УСН Доход" }
    ]
  }
}

Получение списка агентов

http
GET /v1/ecom/receipts/agents

Возвращает агентов, добавленных ранее в личном кабинете: id, наименование, флаг по умолчанию (isDefault) и активность (isActive).

json
{
  "status": "success",
  "data": {
    "agents": [
      {
        "id": "c0ec97c0-7003-467b-be53-5da2312b7eb0",
        "name": "ООО Агент",
        "isDefault": true,
        "isActive": true
      }
    ]
  }
}

Получение списка поставщиков

http
GET /v1/ecom/receipts/suppliers

Аналогично агентам - возвращает поставщиков из личного кабинета.

json
{
  "status": "success",
  "data": {
    "suppliers": [
      {
        "id": "c0ec97c0-7003-467b-be53-5da2312b7eb0",
        "name": "ООО Поставщик",
        "isDefault": true,
        "isActive": true
      }
    ]
  }
}

Callback фискализации

После отправки чека придет callback с type: "fiscal" - подробности в разделе Callback-уведомления.