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

Регистрация документа

Метод регистрации чека в АТОЛ Онлайн v5 - типы операций, структура запроса (receipt, client, company, payments, vats) и ответ.

Метод позволяет отправить запрос на формирование чека и отправку его на регистрацию в ККТ.

Запрос

http
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)

ПолеТипОбяз.Описание
timestampstringДаДата и время документа внешней системы в формате dd.mm.yyyy HH:MM:SS
external_idstringДаИдентификатор документа внешней системы (до 128 символов). Уникален в рамках группы ККТ
serviceobjectНетСлужебный раздел: callback_url (до 256 символов) - URL, на который сервис отправит результат обработки
ism_optionalbooleanНетРегистрировать ли чек, если не удалось проверить код маркировки из-за недоступности ИСМ: true - чек регистрируется, в теге 2106 указывается 0; false (по умолчанию) - чек не регистрируется с ошибкой 421 «Истек таймаут проверки КМ»
use_tspiotbooleanНетРегистрировать ли чек на кассе с ТС ПИоТ (техническое средство получения информации о товаре) для проверки кодов маркировки по разрешительному режиму. true - чек уходит только на кассы с ТС ПИоТ, при их отсутствии ошибка 42 TSPIOTRequired; false (по умолчанию) - на кассы без ТС ПИоТ, а если таких нет - на кассы с ТС ПИоТ без проверки по разрешительному режиму
permissive_modebooleanНетПроверять ли коды маркировки (mark_code.gs1m / mark_code.short) в ГИС МТ по разрешительному режиму перед фискализацией. Работает только при use_tspiot: true. Результат успешной проверки записывается в sectoral_item_props (теги 1260/1265); если хоть одна марка не прошла, чек не фискализируется, причина - в error.permissive_mode_result ответа report
tspiot_user_idstringНетИдентификатор ПО клиента в ГИС МТ - если ваше ПО сертифицировано в ЦРПТ
receiptobjectДаЧек (см. ниже)

Параметры use_tspiot, permissive_mode и tspiot_user_id есть только у чеков sell / sell_refund / buy / buy_refund; в чеках коррекции их нет.

Объект receipt

ПолеТипОбяз.Тег ФФДОписание
clientobjectДа-Сведения о покупателе (см. ниже)
companyobjectДа-Сведения о компании (см. ниже)
itemsarrayДа-Позиции чека, минимум 1 - см. Объект items
paymentsarrayДа-Оплаты, от 1 до 10 (см. ниже)
vatsarrayНет-Налоги на чек, от 1 до 6. Передается либо налог на позицию, либо на чек; если переданы оба - сервис учтет только налог на чек
cashierstringНет1021ФИО кассира (до 64 символов)
cashier_innstringНет1203ИНН кассира (ровно 12 цифр)
additional_check_propsstringНет1192Дополнительный реквизит чека (до 16 символов)
totalnumberДа1020Итоговая сумма чека в рублях (целая часть до 11 знаков, дробная до 2; максимум 10 000 000 000). Равна сумме sum всех позиций (тег 1043)
additional_user_propsobjectНет1084Дополнительный реквизит пользователя: name (до 64) и value (до 256)
operating_check_propsobjectНет1270Операционный реквизит чека (условия применения определяет ФНС): name (значение «0»), value (до 64), timestamp (dd.mm.yyyy HH:MM:SS)
sectoral_check_propsarrayНет1261Отраслевой реквизит чека (см. ниже)
device_numberstringНет1036Заводской номер автоматического устройства (1–20 символов). Если не передан - внутренний номер кассы АТОЛ Онлайн
internetbooleanНет1125Признак расчета в безналичном порядке в сети «Интернет»
cashless_paymentsarrayНет1235Сведения об оплате безналичными (см. ниже)
timezonenumberНет1011Номер часовой зоны места расчетов (целое от 1 до 11)

Объект client

Хотя бы одно из полей email / phone обязательно. Если заполнены оба, ОФД отправит электронный чек только на email.

ПолеТипОбяз.Тег ФФДОписание
emailstringДа*1008Email покупателя (до 64 символов, маска {С}@{С} или none)
phonestringДа*1008Телефон с кодом страны без пробелов, кроме + (+37121234567), до 19 символов
namestringНет1227Наименование покупателя / ФИО (до 256 символов)
innstringНет1228ИНН покупателя (10 или 12 цифр)
birthdatestringНет1243Дата рождения ДД.ММ.ГГГГ (ровно 10 символов)
citizenshipstringНет1244Числовой код страны по ОКСМ (ровно 3 цифры)
document_codestringНет1245Код вида документа, удостоверяющего личность (2 цифры) - см. Приложение 2
document_datastringНет1246Реквизиты документа, удостоверяющего личность (до 64 символов)
addressstringНет1254Адрес покупателя/грузополучателя (до 256 символов)

Объект company

ПолеТипОбяз.Тег ФФДОписание
emailstringДа1117Email отправителя чека (до 64 символов)
snostringДа1055Система налогообложения: osn, usn_income, usn_income_outcome, envd, esn, patent
innstringДа1018ИНН организации - сравнивается со значением в ФН для предотвращения ошибочных регистраций (10 или 12 символов)
payment_addressstringДа1187Место расчетов (до 256 символов), например URL магазина
locationstringНет1009Адрес расчетов (1–256 символов). Если не передан - адрес ЦОД, где расположена касса

Объект payments

ПолеТипОбяз.Описание
typenumberДаВид оплаты: 0 - наличные (тег 1031); 1 - безналичный (тег 1081); 2 - предварительная оплата, зачет аванса (тег 1215); 3 - постоплата, кредит (тег 1216); 4 - иная форма оплаты (тег 1217); 5–9 - расширенные виды оплаты
sumnumberДаСумма к оплате в рублях (целая часть до 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_idstringДа1262Идентификатор ФОИВ - см. Приложение 1
datestringДа1263Дата нормативного акта, ДД.ММ.ГГГГ
numberstringДа1264Номер нормативного акта (до 32 символов)
valuestringДа*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):

ПолеТипОбяз.ТегОписание
sumnumberДа1082Сумма оплаты безналичными
methodnumberДа1236Признак способа оплаты безналичными (определяется ФНС)
idstringДа1237Идентификаторы безналичной оплаты (до 256 символов)
additional_infostringНет1238Дополнительные сведения о безналичной оплате (до 256 символов)

Пример запроса

json
{
  "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.

json
{
  "uuid": "2ea26f17-0884-4f08-b120-306fc096a58f",
  "timestamp": "12.04.2017 06:15:06",
  "error": null,
  "status": "wait"
}
json
{
  "timestamp": "12.04.2017 06:15:06",
  "status": "fail",
  "error": {
    "error_id": "475d6d8d-844d-4d05-aa8b-e3dbdf4defd6",
    "code": 30,
    "text": "Передан некорректный UUID",
    "type": "system"
  }
}
ПолеТипОписание
uuidstringУникальный идентификатор документа (до 128 символов). Не присваивается, если документ не удалось зарегистрировать
timestampstringДата и время получения запроса
statusstringwait - в обработке, fail - ошибка
errorobjecterror_id, code, text, type (system / unknown) - см. Ошибки