УСТАРЕЛО! ЗАПРЕЩЕНО с 01.01.2019 см. НОВЫЙ ПРОТОКОЛ
Сервис предназначен для обеспечения совместимости с протоколом регистации чеков онлайн Atol-Online v3, согласно стандартам форматам фискальных документов 1.0.
Перед использованием протокола необходимо выполнить настройки Шлюза Atol.
Необходимо создать хотя бы один шлюз, указать:
• произвольное имя группы,
• разрешённого кассира,
• организацию/ИП,
• источник чеков по протоколу Атол
• фискальную ККМ, на которой будет выполнятся регистрация чеков
Описание методов
Авторизация пользователя
Работа начинается с процедуры авторизации под лигином/паролем кассира, настроить которые можно в личном кабинете
Авторизация методом POST
https://umka365.ru/kkm-trade/atolpossystem/v3/getToken
Тело запроса должно содержать документ в формате JSON, соответствующий схеме.
{
«login»: «netletest»,
«pass»: «v2AfscRjr»
}
Авторизация методом GET
https://umka365.ru/kkm-trade/atolpossystem/v3/getToken?login=[login]&pass=[pass]
Ответ на запрос авторизации
{
«code»: 1,
«text»: null,
«token»: «8657456346547586»
}
Либо
{
«code»: 19,
«text»: «Неверный логин или пароль»,
«token»: «»
}
code: результат команды. «0» – выдан токен; «19»– ошибка авторизации.
text: текст ошибки.
token: авторизационный токен.
Регистрация документа
Запрос методом POST
https://umka365.ru/kkm-trade/atolpossystem/v3/[group_code]/[operation]?tokenid=[token]
Параметры строки запроса:
group_code: группа ККМ из настоек личного кабинета.
operation: тип операции, которая должна быть выполнена. Возможные типы операция:
• sell: чек «Приход»;
• sell_refund: чек «Возврат прихода»;
• sell_correction: чек «Коррекция прихода»;
• buy: чек «Расход»;
• buy_refund: чек «Возврат расхода»;
• buy_correction: чек «Коррекция расхода».
tokenid: токен, полученный при авторизации
Тело запроса должно содержать документ в формате JSON, соответствующий схеме.
{
«external_id»: «12345678909876654543231»,
«receipt»: {
«attributes»: {
«email»: «ivan@mail.ru»,
«phone»: «»,
«sno»: «osn»
},
«items»: [
{
«name»: «Товар 1»,
«price»: 500.0,
«quantity»: 1.0,
«sum»: 500.00,
«tax»: «vat10»,
«tax_sum»: 45.45
},
{
«name»: » Товар 2″,
«price»: 1.00,
«quantity»: 2.0,
«sum»: 4.00,
«tax»: «vat118»
}
],
«payments»: [
{
«sum»: 504,
«type»: 2
}
],
«total»: 7612
},
«service»: {
«callback_url»: «http://mygate.test.ru»,
«inn»: «4612345678»,
«payment_address»: «mycompany.ru»
},
«timestamp»: «29.06.2018 11:00:00»
}
Пример запроса чека коррекции
{
«external_id»:»12345678909876654543232″,
«correction»: {
«attributes»: {
«sno»:»osn»
},
«tax»:»vat10″,
«payments»: [
{
«type»:2,
«sum»:100.00
}
]
},
«service»:{
«callback_url»: «http://mygate.test.ru»,
«inn»: «4612345678»,
«payment_address»: «mycompany.ru»
},
«timestamp»: «29.06.2018 11:00:00»
}
Описание полей
• timestamp – string, required — дата и время документа внешней системы в формате: «dd.mm.yyyy HH:MM:SS»
• external_id – string, required — Идентификатор документа (транзакции) внешней системы, уникальный среди всех документов. Всегда можно подать повторно чек с таким же external_id – дублирования чеков не произойдёт.
• service.inn – string, required — ИНН организации
• service.payment_address – string, required — Место расчетов
• service.callback_url– string, not required — URL, на который необходимо ответить после обработки документа.
• attributes.sno – string. Поле необязательно, если у организации один тип налогообложения.
Возможные значения:
«osn» – общая СН;
«usn_income» – упрощенная СН (доходы);
«usn_income_outcome» – упрощенная СН (доходы минус расходы);
«envd» – единый налог на вмененный доход;
«esn» – единый сельскохозяйственный налог;
«patent» – патентная СН.
• attributes.email – string – почта покупателя
• attributes.phone – string – телефон покупателя в формате +7… без пробелов
В запросе обязательно должно быть заполнено хотя бы одно из полей: email или phone. Если заполнены оба поля, ОФД отправит электронный чек только на email.
• items.name – string — Наименование предмета расчета
• items.price – number, required – Цена за единицу предмета расчета в рублях с учётом скидок и наценок.
• items.quantity – number, required – Количество/вес
• items.sum – number, required – сумма позиции в рублях
• items.tax – string. Возможны значения:
«none» – без НДС;
«vat0» – НДС по ставке 0%;
«vat10» – НДС чека по ставке 10%;
«vat18» – НДС чека по ставке 18%;
«vat110» – НДС чека по расчетной ставке 10/110;
«vat118» – НДС чека по расчетной ставке 18/118.
• items.tax_sum – number, not required — cумма налога позиции в рублях
• total – number, required – итоговая сумма чека в рублях
• payments – Оплата. Ограничение по количеству — 1 элемент.
• payments.type – required, Вид оплаты. Возможные значения: «1» – электронный
• payments.sum – number, required — сумма к оплате в рублях:
Ответ на запрос
В ответ на POST запрос возвращается пакет, содержащий уникальный идентификатор, присвоенный данному документу и статус.
Если поле «callback_url» было заполнено, то после обработки документа (успешной или не успешной), ответ будет отправлен POST запросом по URI указанному в данном поле. Если в течение 300 секунд ответ не поступил, необходимо запросить статус обработки документа с помощью метода GET (Получение результата обработки документа).
Пример ответа
{
«uuid»: «9658732587357329572453785»,
«timestamp»: «30.11.2018 11:00:00»,
«error»: null,
«status»: » done»
}
Пример ответа с ошибкой
{
«uuid»: «87456893725683258358736583785»,
«timestamp»: «30.11.2018 11:00:11»,
«status»: «fail»,
«error»: {
«code»: 4,
«text»: «Не распознан tokenid запроса»,
«type»: «system»
}
}
uuid – string — Уникальный идентификатор документа в системе umka
status – string – Статус. Возможные значения: «fail» – ошибка; «done» – успех;
error.code – integer – Код ошибки.
error.text – string – Текст ошибки
Получение результата обработки документа
Запрос
Получение статуса документа GET запросом:
https://umka365.ru/kkm-trade/atolpossystem/v3/[group_code]/report/[uuid]?tokenid=[token]
Параметры строки запроса:
uuid – уникальный идентификатор, присвоенный документу после выполнения запроса на регистрацию.
Ответ на запрос
Возвращается пакет с фискальными реквизитами или ошибкой.
{
«uuid»: «87234687683658365838»,
«error»: null,
«status»: «done»,
«payload»:
{
«total»: 100, // Итоговая сумма документа в рублях
«fns_site»: «www.nalog.ru», // Адрес сайта ФНС
«fn_number»: «876235623462», // Номер ФН
«shift_number»: 2, // Номер смены
«receipt_datetime»: «22.12.2018 11:00:00», // Дата и время документа из ФН
«fiscal_receipt_number»: 6, // Номер чека в смене
«fiscal_document_number»: 133, // Фискальный номер документа
«ecr_registration_number»: «00002341242145234», // Регистрационный номер ККТ
«fiscal_document_attribute»: 21543253254 // Фискальный признак документа
},
«timestamp»: «22.12.2018 11:00:00»,
«group_code»: «1»,
«daemon_code»: «umka365.ru»,
«device_code»: «»,
«callback_url»: «»
}
Пример ответа с ошибкой
{
«uuid»: «87234687683658365838»,
«error»: {
«code»: 16,
«text»: «Неверная сумма»,
«type»: «system»
},
«status»: «fail»,
«payload»: null,
«timestamp»: «22.12.2018 11:00:00»,
«callback_url»: «»
}
Коды ошибок
Из-за разницы реализаций невозможно полное соответствие кодам ошибок Атол.
Поэтому ориентироваться следует на текстовое описание ошибки.
Комментарии