Регистрация документа
Метод регистрации чека в АТОЛ Онлайн v5 - типы операций, структура запроса (receipt, client, company, payments, vats) и ответ.
Метод позволяет отправить запрос на формирование чека и отправку его на регистрацию в ККТ.
Запрос
POST https://online.atol.ru/possystem/v5/<group_code>/<operation>
Content-Type: application/json; charset=utf-8
Token: <token>При технической невозможности передать токен в заголовке можно передать его в
строке запроса: ...?token=<token>.
| Параметр | Описание |
|---|---|
group_code | Идентификатор группы ККТ |
operation | Тип операции регистрации чека (см. ниже) |
token | Авторизационный токен |
Типы операций
operation | Чек |
|---|---|
sell | Приход |
sell_refund | Возврат прихода |
buy | Расход |
buy_refund | Возврат расхода |
sell_correction | Коррекция прихода - см. Чеки коррекции |
buy_correction | Коррекция расхода |
sell_refund_correction | Коррекция возврата прихода |
buy_refund_correction | Коррекция возврата расхода |
Пример: https://online.atol.ru/possystem/v5/group1/sell?token=<token>
Тело запроса (sell, sell_refund, buy, buy_refund)
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
timestamp | string | Да | Дата и время документа внешней системы в формате dd.mm.yyyy HH:MM:SS |
external_id | string | Да | Идентификатор документа внешней системы (до 128 символов). Уникален в рамках группы ККТ |
service | object | Нет | Служебный раздел: callback_url (до 256 символов) - URL, на который сервис отправит результат обработки |
ism_optional | boolean | Нет | Регистрировать ли чек, если не удалось проверить код маркировки из-за недоступности ИСМ: true - чек регистрируется, в теге 2106 указывается 0; false (по умолчанию) - чек не регистрируется с ошибкой 421 «Истек таймаут проверки КМ» |
use_tspiot | boolean | Нет | Регистрировать ли чек на кассе с ТС ПИоТ (техническое средство получения информации о товаре) для проверки кодов маркировки по разрешительному режиму. true - чек уходит только на кассы с ТС ПИоТ, при их отсутствии ошибка 42 TSPIOTRequired; false (по умолчанию) - на кассы без ТС ПИоТ, а если таких нет - на кассы с ТС ПИоТ без проверки по разрешительному режиму |
permissive_mode | boolean | Нет | Проверять ли коды маркировки (mark_code.gs1m / mark_code.short) в ГИС МТ по разрешительному режиму перед фискализацией. Работает только при use_tspiot: true. Результат успешной проверки записывается в sectoral_item_props (теги 1260/1265); если хоть одна марка не прошла, чек не фискализируется, причина - в error.permissive_mode_result ответа report |
tspiot_user_id | string | Нет | Идентификатор ПО клиента в ГИС МТ - если ваше ПО сертифицировано в ЦРПТ |
receipt | object | Да | Чек (см. ниже) |
Параметры use_tspiot, permissive_mode и tspiot_user_id есть только у чеков
sell / sell_refund / buy / buy_refund; в чеках коррекции их нет.
Объект receipt
| Поле | Тип | Обяз. | Тег ФФД | Описание |
|---|---|---|---|---|
client | object | Да | - | Сведения о покупателе (см. ниже) |
company | object | Да | - | Сведения о компании (см. ниже) |
items | array | Да | - | Позиции чека, минимум 1 - см. Объект items |
payments | array | Да | - | Оплаты, от 1 до 10 (см. ниже) |
vats | array | Нет | - | Налоги на чек, от 1 до 6. Передается либо налог на позицию, либо на чек; если переданы оба - сервис учтет только налог на чек |
cashier | string | Нет | 1021 | ФИО кассира (до 64 символов) |
cashier_inn | string | Нет | 1203 | ИНН кассира (ровно 12 цифр) |
additional_check_props | string | Нет | 1192 | Дополнительный реквизит чека (до 16 символов) |
total | number | Да | 1020 | Итоговая сумма чека в рублях (целая часть до 11 знаков, дробная до 2; максимум 10 000 000 000). Равна сумме sum всех позиций (тег 1043) |
additional_user_props | object | Нет | 1084 | Дополнительный реквизит пользователя: name (до 64) и value (до 256) |
operating_check_props | object | Нет | 1270 | Операционный реквизит чека (условия применения определяет ФНС): name (значение «0»), value (до 64), timestamp (dd.mm.yyyy HH:MM:SS) |
sectoral_check_props | array | Нет | 1261 | Отраслевой реквизит чека (см. ниже) |
device_number | string | Нет | 1036 | Заводской номер автоматического устройства (1–20 символов). Если не передан - внутренний номер кассы АТОЛ Онлайн |
internet | boolean | Нет | 1125 | Признак расчета в безналичном порядке в сети «Интернет» |
cashless_payments | array | Нет | 1235 | Сведения об оплате безналичными (см. ниже) |
timezone | number | Нет | 1011 | Номер часовой зоны места расчетов (целое от 1 до 11) |
Объект client
Хотя бы одно из полей email / phone обязательно. Если заполнены оба, ОФД
отправит электронный чек только на email.
| Поле | Тип | Обяз. | Тег ФФД | Описание |
|---|---|---|---|---|
email | string | Да* | 1008 | Email покупателя (до 64 символов, маска {С}@{С} или none) |
phone | string | Да* | 1008 | Телефон с кодом страны без пробелов, кроме + (+37121234567), до 19 символов |
name | string | Нет | 1227 | Наименование покупателя / ФИО (до 256 символов) |
inn | string | Нет | 1228 | ИНН покупателя (10 или 12 цифр) |
birthdate | string | Нет | 1243 | Дата рождения ДД.ММ.ГГГГ (ровно 10 символов) |
citizenship | string | Нет | 1244 | Числовой код страны по ОКСМ (ровно 3 цифры) |
document_code | string | Нет | 1245 | Код вида документа, удостоверяющего личность (2 цифры) - см. Приложение 2 |
document_data | string | Нет | 1246 | Реквизиты документа, удостоверяющего личность (до 64 символов) |
address | string | Нет | 1254 | Адрес покупателя/грузополучателя (до 256 символов) |
Объект company
| Поле | Тип | Обяз. | Тег ФФД | Описание |
|---|---|---|---|---|
email | string | Да | 1117 | Email отправителя чека (до 64 символов) |
sno | string | Да | 1055 | Система налогообложения: osn, usn_income, usn_income_outcome, envd, esn, patent |
inn | string | Да | 1018 | ИНН организации - сравнивается со значением в ФН для предотвращения ошибочных регистраций (10 или 12 символов) |
payment_address | string | Да | 1187 | Место расчетов (до 256 символов), например URL магазина |
location | string | Нет | 1009 | Адрес расчетов (1–256 символов). Если не передан - адрес ЦОД, где расположена касса |
Объект payments
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
type | number | Да | Вид оплаты: 0 - наличные (тег 1031); 1 - безналичный (тег 1081); 2 - предварительная оплата, зачет аванса (тег 1215); 3 - постоплата, кредит (тег 1216); 4 - иная форма оплаты (тег 1217); 5–9 - расширенные виды оплаты |
sum | number | Да | Сумма к оплате в рублях (целая часть до 11 знаков, дробная до 2) |
Объекты vats / vat
Ставка налога (type): none, vat0, vat10, vat110, vat20, vat120,
vat5, vat7, vat105, vat107, vat22, vat122. Поле sum - сумма
налога в рублях (для чека - теги 1102–1107, для позиции - теги 1199/1200).
Для налога на чек (vats[]) sum обязателен, для налога на позицию (vat) -
необязателен: касса рассчитает его сама.
Массив sectoral_check_props / sectoral_item_props
Отраслевой реквизит чека (тег 1261) / предмета расчета (тег 1260):
| Поле | Тип | Обяз. | Тег | Описание |
|---|---|---|---|---|
federal_id | string | Да | 1262 | Идентификатор ФОИВ - см. Приложение 1 |
date | string | Да | 1263 | Дата нормативного акта, ДД.ММ.ГГГГ |
number | string | Да | 1264 | Номер нормативного акта (до 32 символов) |
value | string | Да* | 1265 | Состав значений (до 256 символов). При wholesale = true должно включать crpt=mrk |
* В sectoral_item_props при permissive_mode: true поля можно не заполнять:
сервис подставит federal_id: "030", date: "21.11.2023", number: "1944", а
value заполнит результатом проверки кода маркировки.
Массив cashless_payments
Сведения об оплате безналичными (тег 1235):
| Поле | Тип | Обяз. | Тег | Описание |
|---|---|---|---|---|
sum | number | Да | 1082 | Сумма оплаты безналичными |
method | number | Да | 1236 | Признак способа оплаты безналичными (определяется ФНС) |
id | string | Да | 1237 | Идентификаторы безналичной оплаты (до 256 символов) |
additional_info | string | Нет | 1238 | Дополнительные сведения о безналичной оплате (до 256 символов) |
Пример запроса
{
"timestamp": "03.06.2020 12:05:31",
"external_id": "892924433234522512289444",
"service": { "callback_url": "https://shop.ru" },
"receipt": {
"client": {
"email": "client@client.ru",
"phone": "+70002410085",
"name": "Иванов Иван Иванович",
"inn": "516974792202"
},
"company": {
"email": "email@ofd.ru",
"sno": "osn",
"inn": "5010051677",
"payment_address": "shop-url.ru"
},
"items": [
{
"name": "Ваш любимый товар",
"price": 120,
"quantity": 1.0,
"measure": 0,
"sum": 120,
"payment_method": "full_payment",
"payment_object": 1,
"vat": { "type": "vat20", "sum": 20.0 }
}
],
"payments": [ { "type": 1, "sum": 120.0 } ],
"vats": [ { "type": "vat20", "sum": 20.0 } ],
"cashier": "кассир",
"total": 120.0
}
}Ответ на запрос
При отсутствии ошибок сервис вернет уникальный идентификатор чека и статус обработки. Результат обработки получайте методом report.
{
"uuid": "2ea26f17-0884-4f08-b120-306fc096a58f",
"timestamp": "12.04.2017 06:15:06",
"error": null,
"status": "wait"
}{
"timestamp": "12.04.2017 06:15:06",
"status": "fail",
"error": {
"error_id": "475d6d8d-844d-4d05-aa8b-e3dbdf4defd6",
"code": 30,
"text": "Передан некорректный UUID",
"type": "system"
}
}| Поле | Тип | Описание |
|---|---|---|
uuid | string | Уникальный идентификатор документа (до 128 символов). Не присваивается, если документ не удалось зарегистрировать |
timestamp | string | Дата и время получения запроса |
status | string | wait - в обработке, fail - ошибка |
error | object | error_id, code, text, type (system / unknown) - см. Ошибки |