Примеры и кейсы АТОЛ Онлайн
Готовые кейсы фискализации через АТОЛ Онлайн v5 - чек прихода, возврат, коррекция, маркировка - с кодом на Node.js и Python.
Кейс 1. Чек прихода для интернет-магазина
Полный цикл: токен -> чек -> результат.
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
}import os
from datetime import datetime
import requests
BASE = "https://online.atol.ru/possystem/v5"
GROUP = os.environ["ATOL_GROUP_CODE"]
_token: str | None = None
def get_token() -> str:
global _token
if _token:
return _token
res = requests.post(
f"{BASE}/getToken",
json={"login": os.environ["ATOL_LOGIN"], "pass": os.environ["ATOL_PASS"]},
timeout=30,
)
data = res.json()
if data.get("error"):
raise RuntimeError(f"{data['error']['code']}: {data['error']['text']}")
_token = data["token"]
return _token
def register_receipt(order: dict) -> str:
body = {
"timestamp": datetime.now().strftime("%d.%m.%Y %H:%M:%S"),
"external_id": f"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": [
{
"name": i["title"],
"price": i["price"],
"quantity": i["qty"],
"measure": 0,
"sum": round(i["price"] * i["qty"], 2),
"payment_method": "full_payment",
"payment_object": 1,
"vat": {"type": "vat20"},
}
for i in order["items"]
],
"payments": [{"type": 1, "sum": order["total"]}],
"total": order["total"],
},
}
res = requests.post(
f"{BASE}/{GROUP}/sell",
json=body,
headers={"Token": get_token()},
timeout=30,
)
data = res.json()
if data["status"] == "fail":
raise RuntimeError(f"{data['error']['code']}: {data['error']['text']}")
return data["uuid"]Идемпотентность через external_id
external_id уникален среди всех документов группы ККТ. Повторная отправка
чека с тем же external_id вернет ошибку 33
(IncomingExternalIdAlreadyExists) со статусом Wait - это защита от
дублирования чеков при ретраях. Используйте детерминированный external_id
(например, order-{id}-sell) и не меняйте его при повторных попытках после
сетевой ошибки. После ответа fail с ошибкой данных чека берите новый
external_id (например, с суффиксом попытки) - см.
ошибки.
Кейс 2. Возврат прихода
// Тот же чек, но операция sell_refund и позиции возврата
await fetch(`${BASE}/${GROUP}/sell_refund`, { /* ... */ });Правила те же: total равен сумме возвращаемых позиций, payments - тем же
видом оплаты, которым платил покупатель.
Кейс 3. Чек коррекции по предписанию ФНС
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
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 секунд.