Сквозные кейсы использования
Одна интеграция (АТОЛ Pay с чеками) или две (Pay + АТОЛ Онлайн отдельно) - сравнение, правило выбора и кейсы с кодом и диаграммами.
Это шаг 2 пути интеграции: нужно принять одно решение
Настраивать здесь ничего не нужно. Прочитайте сравнение ниже, выберите
вариант А или вариант Б. Дальше на
шаге 3 либо назовите
выбор ассистенту («делаем вариант А»), либо держите его в уме, когда будете
собирать запрос: с блоком receipt или без. Остальные разделы страницы -
примеры под каждый вариант; читать их целиком не обязательно.
Платформа АТОЛ закрывает три задачи: прием денег (АТОЛ Pay Ecom), фискализацию (АТОЛ Онлайн v5) и мониторинг касс (сервис ККТ и ФН). Ключевое архитектурное решение при проектировании - как связать первые две.
Если термины незнакомы
Фискализация - отправка чека в налоговую. Чек здесь не бумажка, а электронный документ: касса передает его оператору фискальных данных (ОФД), а тот - в ФНС. По 54-ФЗ это требуется при расчетах с покупателями, поэтому вопрос не в том, нужны ли чеки, а в том, кто их отправляет: АТОЛ Pay за вас или вы сами.
Одна интеграция или две?
Есть два способа пробивать чеки по онлайн-оплатам:
Вариант А - одна интеграция. АТОЛ Pay сам отправляет чек в АТОЛ Онлайн:
вы передаете блок receipt в методе регистрации
платежа, чек «Приход» уходит автоматически после успешной оплаты, чек
«Возврат прихода» - автоматически при возврате.
Вариант Б - две независимые интеграции. АТОЛ Pay принимает деньги
(регистрация платежа без блока receipt), а чеки вы пробиваете сами
напрямую через API АТОЛ Онлайн v5 - когда нужно, какие нужно
и сколько нужно.
| Критерий | А: Pay + receipt | Б: Pay и Online отдельно |
|---|---|---|
| Сложность | Один API, один callback | Два API, две учетки, свой код фискализации |
| Момент чека | Строго в момент оплаты | Любой: оплата, отгрузка, выдача |
| Кол-во чеков на заказ | Один (+ авточек возврата) | Сколько требует 54-ФЗ: предоплата, зачет аванса, частичные отгрузки |
| Признак способа расчета | Из блока receipt | Полный контроль (full_prepayment -> full_payment с зачетом) |
Маркировка (ФФД 1.2, mark_code) | Нет | Да |
| Агентские схемы | Базовые (agentId/supplierId из ЛК) | Полные реквизиты agent_info/supplier_info в каждом чеке |
| Чеки коррекции | Нет | Да |
| Чеки по расчетам вне эквайринга | Нет | Да |
Правило выбора
Продаете цифровой товар/услугу, которая оказывается сразу в момент оплаты - берите вариант А, это один запрос. Если между оплатой и передачей товара есть время (доставка, сборка заказа), есть маркировка, агентские схемы или частичные отгрузки - берите вариант Б.
Что нужно для варианта Б, кроме кода. Отдельные учетные данные АТОЛ Онлайн
- логин, пароль и код группы ККТ - и зарегистрированные на вас кассы. Доступ к АТОЛ Pay здесь не подходит: это разные сервисы с разными личными кабинетами. Как это получить - Общий алгоритм взаимодействия; если доступов пока нет, запросите их до шага 3, иначе проверить фискализацию на шаге 4 будет нечем.
Кейс 1. Интернет-магазин «под ключ» (вариант А)
Задача: принимать оплату картой и СБП, автоматически пробивать чеки. Товар/услуга передается сразу (цифровые товары, билеты, донаты).
- Регистрация платежа
с блоком
receipt(providerId: 100,paymentMethod: 3- полный расчет) -> редирект покупателя наdata.paymentUrls.main. - Callback
type=payment,paymentStatus: 1-> выдать товар. - Callback
type=fiscal-> сохранитьreceiptIdчека. - Возврат:
POST /cancel- чек «Возврат прихода» уйдет автоматически.
await api.post('/v1/ecom/payments', {
amount: 250000, // 2 500 ₽ в копейках
orderId,
sessionType: 'oneStep',
additionalProps: { returnUrl, notificationUrl },
receipt: {
buyer: { email },
positions: [{
name: 'Электронный билет', price: 250000, quantity: 1000,
measure: 0, paymentMethod: 3, paymentSubject: 4, tax: 0,
}],
providerId: 100,
sno: 1,
},
paymentMethods: [
{ paymentType: 'card', bankId: 100 },
{ paymentType: 'sbp', bankId: 100 },
],
});Что учесть: лимит orderId (36 символов у Альфа-Банка), сумма позиций должна
сходиться с amount (иначе INVALID_RECEIPT_AMOUNT), идемпотентный
обработчик callback, опрос статуса как fallback. Полные примеры на четырех
языках - в Примерах АТОЛ Pay.
Кейс 2. Магазин с доставкой: предоплата и зачет аванса (вариант Б)
Задача: покупатель платит онлайн сегодня, товар уезжает со склада завтра. По 54-ФЗ это два фискальных события: чек «предоплата 100%» в момент оплаты и чек «полный расчет» с зачетом аванса в момент передачи товара. Вариант А такое не умеет - нужна раздельная интеграция.
Схема: АТОЛ Pay регистрирует платеж без receipt; ваш бэкенд по
callback оплаты пробивает чек предоплаты через АТОЛ Онлайн, а при отгрузке -
чек полного расчета.
Шаг 1. Оплата (АТОЛ Pay, суммы в копейках):
const { data } = await pay.post('/v1/ecom/payments', {
amount: 550000, // 5 500 ₽
orderId: order.id,
sessionType: 'oneStep',
additionalProps: { returnUrl, notificationUrl },
// блока receipt НЕТ - фискализируем сами
});
const paymentUrl = data.paymentUrls.main;Шаг 2. Чек предоплаты по callback оплаты (АТОЛ Онлайн, суммы в рублях):
app.post('/webhooks/atolpay', async (req, res) => {
const e = req.body;
if (e.type === 'payment' && e.status === 'success' && e.paymentStatus === 1) {
await online.registerReceipt('sell', {
timestamp: nowAtol(), // "dd.mm.yyyy HH:MM:SS"
external_id: `${e.orderId}-prepay`, // детерминированный ID!
service: { callback_url: fiscalCallbackUrl },
receipt: {
client: { email: order.email },
company: { email: COMPANY_EMAIL, sno: 'usn_income', inn: INN, payment_address: 'shop.ru' },
items: order.items.map((i) => ({
name: i.title,
price: i.priceRub, // РУБЛИ, не копейки!
quantity: i.qty,
measure: 0,
sum: i.priceRub * i.qty,
payment_method: 'full_prepayment', // предоплата 100%
payment_object: 1,
vat: { type: 'vat20' },
})),
payments: [{ type: 1, sum: order.totalRub }], // безналичными
total: order.totalRub,
},
});
}
res.sendStatus(200);
});Шаг 3. Чек полного расчета при отгрузке (зачет аванса):
async function onShipment(order) {
await online.registerReceipt('sell', {
timestamp: nowAtol(),
external_id: `${order.id}-full`,
receipt: {
client: { email: order.email },
company: { email: COMPANY_EMAIL, sno: 'usn_income', inn: INN, payment_address: 'shop.ru' },
items: order.items.map((i) => ({
name: i.title, price: i.priceRub, quantity: i.qty, measure: 0,
sum: i.priceRub * i.qty,
payment_method: 'full_payment', // полный расчет
payment_object: 1,
vat: { type: 'vat20' },
})),
payments: [{ type: 2, sum: order.totalRub }], // тип 2 - зачет аванса!
total: order.totalRub,
},
});
}Правила связки двух интеграций:
- Корреляция.
orderId(Pay) кладите вexternal_id(Online) с суффиксом события:{orderId}-prepay,{orderId}-full,{orderId}-refund. Так по заказу всегда видно все его чеки. - Идемпотентность бесплатно.
external_idуникален в группе ККТ: повторная отправка того же чека вернет ошибку 33 (IncomingExternalIdAlreadyExists) - ретраи безопасны. - Единицы измерения. Pay считает в копейках, Online - в рублях с двумя знаками. Держите конвертацию в одном месте.
- Возвраты - в двух системах.
POST /cancelв Pay вернет деньги, но чек «Возврат прихода» теперь ваша забота:sell_refundв Online (а если аванс еще не зачтен - возврат на чек предоплаты). - Мониторинг очереди. Ошибка
timeout(превышено время ожидания чека в очереди) означает, что кассам не хватает мощности - следите за парком ККТ и количеством касс в группе.
Кейс 3. Маркетплейс: агентская схема и выплаты (вариант Б)
Задача: площадка принимает деньги за товары продавцов, удерживает комиссию, чеки должны содержать реквизиты поставщика (54-ФЗ, агентская схема).
- Деньги: АТОЛ Pay (одностадийный или двухстадийный платеж - холд до подтверждения заказа продавцом).
- Чеки: АТОЛ Онлайн с
agent_info+supplier_infoв каждой позиции - тип агента (commission_agent,paying_agent…), телефоны, наименование и ИНН поставщика (тег 1226). Позиция комиссии площадки идет сpayment_object: 11(вознаграждение агента). - Расчеты с продавцами вне эквайринга (взаимозачеты, выплаты) при
необходимости фискализируются отдельными чеками
payments: [{ type: 4 }](встречное предоставление).
items: [
{
name: 'Кроссовки (ООО Ромашка)', price: 4990, quantity: 1, measure: 0,
sum: 4990, payment_method: 'full_payment', payment_object: 1,
vat: { type: 'vat20' },
agent_info: { type: 'commission_agent' },
supplier_info: { name: 'ООО Ромашка', inn: '7701234567', phones: ['+79990000000'] },
},
]Кейс 4. Маркированные товары (вариант Б)
Задача: продажа обуви/одежды/парфюма с кодами маркировки «Честный знак».
Блок receipt АТОЛ Pay коды маркировки не передает - фискализация только
напрямую через АТОЛ Онлайн (ФФД 1.2).
Ключевые поля позиции: payment_object: 33, mark_processing_mode: "0",
planned_status: 1, mark_code.gs1m - код целиком в Base64. После
фискализации проверьте payload.marks_result[].result - значение 15
означает успешную проверку кода. Если ИСМ недоступна, а чек должен пробиться
в любом случае - ism_optional: true на верхнем уровне запроса.
Разбор всех полей: Объект items, пример -
Примеры АТОЛ Онлайн.
Для ОСУ (объемно-сортовой учет партиями) используйте wholesale: true.
Кейс 5. SaaS: подписки с пробным периодом (вариант А)
Задача: рекуррентные списания 990 ₽/мес с триалом 14 дней.
Подписки АТОЛ Pay: план -> подписка ->
автосписания. Чек на каждое продление уходит автоматически, если в плане
задан data.receipt + data.items. Callback type=subscription ведет
жизненный цикл: new/trial -> prolongation -> retry -> canceled
(статусы error и paused зарезервированы).
Право на триал контролируется по buyer.id. На sandbox периоды в
минутах/секундах позволяют проверить продления за минуты.
Кейс 6. Бронирование с гарантией (вариант А или Б)
Задача: заморозить деньги при бронировании, списать после подтверждения.
Двухстадийный платеж: sessionType: "twoStep"
-> callback paymentStatus: 11 (холд) -> подтверждение ->
/deposit
в течение 7 суток (или /cancel без комиссии). Чек уместно пробивать в момент
списания: с блоком receipt он уйдет по второй стадии автоматически
(вариант А); если нужен чек в другой момент - вариант Б.
Кейс 7. Мониторинг парка касс
Задача: не допустить остановки фискализации из-за переполненного ФН или потери связи кассы с ОФД. Актуально для варианта Б и высоких оборотов.
Сервис информации о ККТ и ФН: периодический опрос
GET /api/kkt/v1/cash-registers, алерты по порогам:
| Сигнал | Порог | Действие |
|---|---|---|
fiscalStoragePercentageUse | > 90% | Заказать замену ФН |
fiscalStorageExpiration | < 30 дней | Плановая замена ФН |
unsentDocs | растет | Проверить связь с ОФД (networkErrorCode) |
Ошибка timeout в АТОЛ Онлайн | любая | Добавить ККТ в группу или снизить поток чеков |
Готовый скрипт мониторинга ассистент напишет по промпту из
Примеров промптов, а MCP-инструмент
get_kkt_info покажет состояние касс прямо в диалоге.
Кейс 8. Интеграция силами ИИ
Задача: ускорить разработку и не ловить ошибки интеграции вручную.
Подключите MCP-сервер к Claude или Cursor: инструмент
start_integration выдаст план под ваш стек, get_recipe - рецепты по
каждой теме этой страницы (в т.ч. fiscal-direct для варианта Б),
validate_receipt проверит чеки до отправки, а create_payment создаст
тестовый платеж на sandbox прямо из диалога.
Пишете код сами - тот же контур без MCP: в быстром старте вкладка «Своими руками».