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

Сквозные кейсы использования

Одна интеграция (АТОЛ 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. Интернет-магазин «под ключ» (вариант А)

Задача: принимать оплату картой и СБП, автоматически пробивать чеки. Товар/услуга передается сразу (цифровые товары, билеты, донаты).

  1. Регистрация платежа с блоком receipt (providerId: 100, paymentMethod: 3 - полный расчет) -> редирект покупателя на data.paymentUrls.main.
  2. Callback type=payment, paymentStatus: 1 -> выдать товар.
  3. Callback type=fiscal -> сохранить receiptId чека.
  4. Возврат: POST /cancel - чек «Возврат прихода» уйдет автоматически.
js
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, суммы в копейках):

js
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 оплаты (АТОЛ Онлайн, суммы в рублях):

js
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. Чек полного расчета при отгрузке (зачет аванса):

js
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 }] (встречное предоставление).
js
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: в быстром старте вкладка «Своими руками».