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

Примеры и кейсы АТОЛ Онлайн

Готовые кейсы фискализации через АТОЛ Онлайн v5 - чек прихода, возврат, коррекция, маркировка - с кодом на Node.js и Python.

Кейс 1. Чек прихода для интернет-магазина

Полный цикл: токен -> чек -> результат.

js
const BASE = 'https://online.atol.ru/possystem/v5';
const GROUP = process.env.ATOL_GROUP_CODE;

let cachedToken = null;

async function getToken() {
  if (cachedToken) return cachedToken; // обновляем только по ExpiredToken
  const res = await fetch(`${BASE}/getToken`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
    body: JSON.stringify({
      login: process.env.ATOL_LOGIN,
      pass: process.env.ATOL_PASS,
    }),
  });
  const data = await res.json();
  if (data.error) throw new Error(`${data.error.code}: ${data.error.text}`);
  cachedToken = data.token;
  return cachedToken;
}

async function registerReceipt(order) {
  const token = await getToken();
  const res = await fetch(`${BASE}/${GROUP}/sell`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      Token: token,
    },
    body: JSON.stringify({
      timestamp: formatDate(new Date()), // "dd.mm.yyyy HH:MM:SS"
      external_id: `order-${order.id}`,   // уникален в группе ККТ!
      service: { callback_url: 'https://shop.example.com/atol/callback' },
      receipt: {
        client: { email: order.email },
        company: {
          email: 'receipts@shop.example.com',
          sno: 'usn_income',
          inn: '5010051677',
          payment_address: 'shop.example.com',
        },
        items: order.items.map((i) => ({
          name: i.title,
          price: i.price,          // в рублях
          quantity: i.qty,
          measure: 0,
          sum: Math.round(i.price * i.qty * 100) / 100, // копеечная точность
          payment_method: 'full_payment',
          payment_object: 1,
          vat: { type: 'vat20' },
        })),
        payments: [{ type: 1, sum: order.total }],
        total: order.total,
      },
    }),
  });
  const data = await res.json();
  if (data.status === 'fail') {
    throw new Error(`${data.error.code}: ${data.error.text}`);
  }
  return data.uuid; // сохраняем для получения результата
}

async function getReport(uuid) {
  const token = await getToken();
  const res = await fetch(`${BASE}/${GROUP}/report/${uuid}`, {
    headers: { Token: token },
  });
  return res.json(); // status: done | wait | fail
}

Идемпотентность через external_id

external_id уникален среди всех документов группы ККТ. Повторная отправка чека с тем же external_id вернет ошибку 33 (IncomingExternalIdAlreadyExists) со статусом Wait - это защита от дублирования чеков при ретраях. Используйте детерминированный external_id (например, order-{id}-sell) и не меняйте его при повторных попытках после сетевой ошибки. После ответа fail с ошибкой данных чека берите новый external_id (например, с суффиксом попытки) - см. ошибки.

Кейс 2. Возврат прихода

js
// Тот же чек, но операция sell_refund и позиции возврата
await fetch(`${BASE}/${GROUP}/sell_refund`, { /* ... */ });

Правила те же: total равен сумме возвращаемых позиций, payments - тем же видом оплаты, которым платил покупатель.

Кейс 3. Чек коррекции по предписанию ФНС

js
await fetch(`${BASE}/${GROUP}/sell_correction`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json; charset=utf-8', Token: token },
  body: JSON.stringify({
    timestamp: formatDate(new Date()),
    external_id: `corr-${prescription.number}`,
    correction: {
      company: { email, sno: 'osn', inn, payment_address },
      correction_info: {
        type: 'instruction',              // по предписанию налогового органа
        base_date: '23.11.2020',          // дата корректируемого расчета
        base_number: prescription.number, // номер предписания
      },
      items: [/* позиции */],
      payments: [{ type: 1, sum: total }],
      total,
    },
  }),
});

Кейс 4. Маркированный товар (ФФД 1.2)

Ключевые поля позиции: payment_object: 33, mark_processing_mode: "0", planned_status: 1, mark_code.gs1m (код в Base64). После фискализации проверьте payload.marks_result[].result - значение 15 означает успешную проверку кода маркировки (см. report).

Если ИСМ недоступна и чек должен пробиваться в любом случае - передайте ism_optional: true на верхнем уровне запроса (иначе при таймауте проверки КМ придет ошибка 421).

Кейс 5. Обработчик callback

js
app.post('/atol/callback', express.json(), (req, res) => {
  const result = req.body; // тот же пакет, что и в GET /report/{uuid}
  if (result.status === 'done') {
    saveFiscalData(result.external_id, {
      fd: result.payload.fiscal_document_number,
      fpd: result.payload.fiscal_document_attribute,
      fn: result.payload.fn_number,
      ofdUrl: result.payload.ofd_receipt_url,
    });
  } else if (result.status === 'fail') {
    alertAccounting(result.external_id, result.error);
  }
  res.sendStatus(200);
});

Не забудьте фоновый опрос GET /report/{uuid} для чеков, по которым callback не пришел за 300 секунд.