Каса Dotykacka: продажі офлайн-точки в Elbuz

Dotykacka — касова система (POS) для магазинів, кав'ярень і закладів; поширена в Чехії, Словаччині та Польщі. Якщо у вас є офлайн-точка на цій касі, продажі там живуть окремо від інтернет-каталогу: каса знає, що продано, а облік — ні. Elbuz закриває цей розрив у два боки: забирає з каси оплачені чеки й покупців, а назад вивантажує категорії й товари, щоб на касі був той самий асортимент, що й у каталозі.

Це не маркетплейс, тому загальний огляд імпорту замовлень через API тут допоможе лише частково — механіка каси відчутно своя, і саме про неї ця стаття.

Де це у програмі

У вікні завантаження створіть шаблон і оберіть тип «dotykacka.pl (POS)». Файл не потрібен. У картці «Підключення» заповнюються два поля:

1

Поле «Токен»

2

Поле «ID інстанса (api_instance_id)»

1. Токен — refresh-токен каси, який видає Dotykacka.
2. ID інстанса (api_instance_id) — номер хмари каси.

Які чеки забираються

Elbuz бере з каси тільки оплачені продажні чеки. Усе інше — чернетки, службові документи, неоплачені рахунки — пропускається: у облік має потрапляти факт продажу, а не проміжні стани касової зміни.

При регулярних запусках забираються чеки, створені після минулого завантаження, з запасом у дванадцять годин назад — на випадок розбіжності годинників і затримок синхронізації каси з хмарою. Уже завантажені документи при цьому не дублюються.

Один чек — три документи

Це головна відмінність каси від маркетплейсу, і зрозуміти її варто до першого запуску. Продаж на касі — подія, у якої три різні наслідки для обліку: товар пішов зі складу, гроші прийшли в касу, продаж треба порахувати у виторзі. Тому з кожного чека Elbuz створює три документи:

Усі три посилаються на один і той самий чек, тож зв'язок між ними видно завжди. Не лякайтеся, побачивши після першого завантаження втричі більше документів, ніж було чеків, — так і має бути.

Зв'язує трійку номер чека: у всіх трьох він стоїть у колонці «№ документа (сайт)» списку документів. Внутрішній ідентифікатор («ID документа зовнішній») у кожного свій — інакше програма вважала б їх одним документом і завела тільки перший.

Створюються всі три непроведеними: ознака проведення (колонка «Статус проводки (підписи)» у списку документів) у них не стоїть. Саме завантаження жодних складських рухів не робить — воно лише фіксує в обліку те, що вже сталося на касі. Списання зі складу й решта наслідків з'являються тоді, коли документ проводять.

Позиції й товари

З кожного рядка чека беруться назва, кількість, ціна з ПДВ, сума рядка, відсоток знижки, одиниця виміру, номер товару в касі й номер його категорії в касі.

Далі Elbuz вирішує, до якої картки каталогу прив'язати рядок. Порядок пошуку такий: спершу за номером товару в касі — він лишається записаним у картці після першого ж завантаження, тож знайома позиція знаходиться одразу; якщо не знайшлося — за точним збігом назви з назвою картки в каталозі. Знайдена картка при цьому не змінюється: ні ціна, ні залишок, ні назва в ній від завантаження чека не зрушать.

Якщо ні за номером, ні за назвою нічого не знайшлося, заводиться нова картка. У неї потрапляють назва з чека, ціна з чека (та сама ціна з ПДВ, за якою продали), кількість із рядка чека як залишок і одиниця виміру. Картка створюється активною, зі станом «В наявності», але без прапорця «Вивантажувати у файл (на сайт)»: на вітрину й на майданчики така позиція сама не поїде, доки ви цього не дозволите.

У рядку документа при цьому назавжди лишається те, що було пробито на касі: назва, кількість і ціна з чека. Навіть якщо потім ви зміните ціну в каталозі, у вже завантаженому чеку вона буде касова — і це правильно, бо документ фіксує факт продажу.

Куди лягають нові товари з каси

Категорію каса передає номером, а не назвою. Elbuz порівнює цей номер з полем зовнішнього UUID ваших категорій і лише при збігу кладе товар у вашу гілку. Зворотне вивантаження це поле не заповнює — воно веде власний, окремий рядок зв'язку з касою. Тому в звичайному житті збігу немає, і всі нерозпізнані позиції з чеків складаються в одну службову категорію з назвою виду «Товари - ‹код джерела› - ‹назва вашого шаблону›».

Створюється вона вимкненою і без участі у вивантаженнях. Так вона налаштовується лише в момент створення: наступні завантаження чеків складають нові позиції в ту саму категорію й її прапорці не чіпають — якщо ви вручну ввімкнете їй вивантаження, воно так і лишиться.

Переносити картки звідти у свої категорії можна вільно, і саме заради цього категорія й потрібна. Повторне завантаження чеків місце товару в дереві не змінює, а рядок уже завантаженого документа зберігає власну копію назви, ціни й кількості й на категорію не посилається — від переносу в документах не зміниться нічого.

Види оплати

Каса передає спосіб оплати кодом, і Elbuz розкладає основні в свої види оплат:

Крім них Dotykacka знає ще з пів сотні способів — талони на харчування, подарункові сертифікати, QR-код, а також оплати від служб доставки їжі (Glovo, Bolt Food, Wolt, Foodora та інших). Їхні назви Elbuz зберігає в документі як є, тож у звітах видно, звідки прийшли гроші, навіть якщо окремого виду оплати під це у вас немає. Статус оплати в усіх випадках — «Оплачено»: чек оплачений за визначенням.

Покупці з каси

Перед чеками Elbuz забирає картотеку покупців каси — тих, кого на касі заводять для знижок і програм лояльності. Приходять ім'я та прізвище, телефон, пошта, адреса, індекс, країна, місто, дата народження, накопичені бали й примітка.

Заводяться при цьому тільки нові покупці. Elbuz звіряє картотеку каси зі своєю базою контрагентів за трьома ознаками: за ідентифікатором покупця в касі, за телефоном і за поштою — причому пошта порівнюється в канонічному вигляді, тож адреси на кшталт ivan.petrov+shop@gmail.com і ivanpetrov@gmail.com впізнаються як одна. Це важливо для точки, де один і той самий клієнт купує і в залі, і на сайті: дубль контрагента не з'явиться.

Покупця, який у базі вже є, прогін не оновлює: нові дані з каси в його картку не дописуються, навіть якщо там змінився телефон чи адреса. Такі правки переносять у Elbuz руками.

А от у самі документи покупець не потрапляє. Покупця з чека Elbuz у документ не переносить, тому всі три документи заводяться на службового контрагента «Кінцевий споживач» — він створюється один раз, при першому завантаженні, якщо його ще немає в базі. Тобто картотека каси й документи продажів живуть у Elbuz поруч, але не зшиті між собою: щоб побачити покупки конкретного покупця, контрагента в документі проставляють вручну.

Нових покупців прогін кладе в групу клієнтів. Поле «Група контрагентів» у розділі «Розширене» картки шаблону на них не впливає — воно задає групу для «Кінцевого споживача» в момент його створення.

Зворотний бік: товари з Elbuz у касу

Окремим шаблоном вивантаження типу «dotykacka.pl» Elbuz заводить на касі категорії й товари з вашого каталогу. Працює це так: спершу їдуть категорії, потім товари; нове створюється, наявне оновлюється. Зв'язок Elbuz запам'ятовує, тож повторне вивантаження не плодить дублікатів на касі.

Кілька особливостей, які варто знати:

• Ціна рахується у двох варіантах. Каса зберігає ціну з ПДВ і без ПДВ окремо, тому Elbuz за ставкою податку товару обчислює ціну без ПДВ сам.
• Одиниці виміру приводяться до переліку каси. Dotykacka приймає лише свій закритий список одиниць (штука, кілограм, літр, метр і так далі); ваші позначення зіставляються з ним, а все нерозпізнане стає штукою.
• Пачками по сто. І категорії, і товари відправляються блоками, тож великий каталог іде передбачувано, без перевантаження каси.

У касу їдуть не всі товари каталогу, а лише ті, у яких стоїть прапорець «Вивантажувати у файл (на сайт)» і чия категорія теж увімкнена й позначена до вивантаження. Тому картки, заведені з чеків, у зворотне вивантаження не потрапляють: ні прапорця, ні «вивантажуваної» категорії в них немає.

Що саме перезаписується в касі при оновленні позиції: назва, категорія, одиниця виміру, штрихкод, видимість, ставка ПДВ, ціна з ПДВ і без ПДВ, колір. Знижку товару каса щоразу отримує нульову, а ознаку «списувати зі складу» — знятою: залишки лишаються за Elbuz, і каса продасть позицію навіть тоді, коли кількість у ній нульова.

Категорії їдуть першими не для порядку: товар відправляється з номером своєї категорії в касі, а цей номер з'являється лише після того, як категорію вивантажили. Тому в шаблоні вмикайте обидві позначки. Якщо каса відмовиться прийняти нові записи, її текст відмови лягає в журнал прогону; а от відповідь каси на оновлення вже наявних позицій програма не перевіряє й у журнал не пише — невдале оновлення лишиться непоміченим. Перед оновленням Elbuz запитує в каси поточну версію пачки записів; якщо каса її не повернула, пачка не оновлюється, а в журналі з'являється помаранчевий рядок «Dotykačka: каса не повернула версію записів (ETag) — пачку оновлення пропущено, повтор при наступному прогоні.».

Повторний прогін і чиє значення перемагає

Обмін іде в обидва боки, тож «хто кого перепише» тут не риторичне питання. Правило просте, але несиметричне.

Чек, який уже завантажений, повторний прогін не чіпає взагалі. Документ шукається за ідентифікатором чека в касі, і якщо він знайшовся, жодне поле цього документа не переписується: ні статус, ні сума, ні рядки, ні контрагент. Усе, що менеджер виправив у трьох документах, лишається як було. Новими стають тільки ті чеки, яких у базі ще немає.

Картки товарів завантаження чеків теж не переписує. Ваша ціна, назва, залишок і місце в дереві від нього не змінюються — з чеків беруться лише нові картки. Єдине, що прогін оновлює в наявних товарах, — підсумок продажів: кількість проданого перераховується за всіма замовленнями покупця.

Зате в касу вивантаження щоразу пише поверх. Ціну, назву, категорію, ПДВ і видимість, змінені на касі, наступне вивантаження поверне до значень Elbuz, і попередження про це не буде. Якщо якісь позиції ви ведете саме на касі, не пускайте їх у вивантаження — зніміть у картці «Вивантажувати у файл (на сайт)». Іншого захисту тут немає: перемикачі «Не оновлювати» і «Фіксована ціна» в картці товару стосуються завантажень у Elbuz, а це вивантаження з Elbuz, і воно на них не дивиться.

Коли чек скасували або товар зник

Чека не стало на касі. Три документи в Elbuz лишаються такими, як були. Завантаження вміє тільки створювати документи: воно не видаляє й не змінює жодного з уже заведених, і рядка про зниклий чек у журналі не з'явиться. Прибирають такі документи руками — як саме, нижче.

На касі оформили повернення. З каси Elbuz бере тільки записи типу «чек» з ознакою «оплачено», усе інше відсіюється мовчки. Тому чи приїде повернення в облік, залежить від того, яким записом його оформила каса: якщо звичайним оплаченим чеком — воно приїде такою самою трійкою документів; якщо іншим типом документа — не приїде зовсім, і зворотний рух доведеться зробити в Elbuz самостійно. Уже завантажену трійку початкового продажу повернення в будь-якому разі не змінює.

Товару не стало в Elbuz. На касі він лишається таким, яким його відправили востаннє. Вивантаження вміє тільки створювати й оновлювати позиції — команди на видалення воно касі не шле взагалі. Так само буде, якщо ви просто зняли в картці «Вивантажувати у файл (на сайт)»: наступне вивантаження цей товар пропустить, а на касі він так і лишиться зі старою ціною. Прибирають позицію в самій касі.

Як побачити, що прогін відпрацював

Журнал прогону відкривається в Центрі операцій — правій панелі, яка не блокує роботу: картку шаблону можна закрити й стежити за прогоном звідки завгодно.

Рядки в ньому йдуть у такому порядку:

1. «Всього контрагентів завантажено: N» — скільки покупців з картотеки каси виявилися новими. Нових не було — рядка немає.
2. «Запитуємо список замовлень» — початок роботи з чеками.
3. «Отримано замовлень: N» — увага, це не кількість чеків, а кількість рядків, що приїхали з каси: по три на кожен чек, тобто утричі більше. І це ще не результат: серед них є й ті чеки, що вже в базі.
4. «Всього товарів завантажено: N» і слідом «Індексування товарів» — скільки нових карток заведено з позицій чеків. Нових не було — обох рядків немає.
5. «Всього замовлень завантажено: N» — скільки документів реально створено. Це головне число прогону.
6. «Оновлення значень на основі формул» і «Завантаження даних завершено!» з приписом «Витрачено часу».

Найважливіше в цьому списку — що буває, коли нового немає. Тоді рядка «Всього замовлень завантажено» не буде взагалі: «Отримано замовлень» покаже, скільки приїхало з каси, а прогін одразу перейде до формул і завершення. Це нормальний результат повторного запуску, а не збій.

Помилку доступу видно окремо. Якщо не заповнено токен або ID інстанса, у журналі буде «Не вказано API токен»; якщо каса не прийняла токен — туди ж лягає її власна відповідь, текстом, як прийшла. А от порожню відповідь каси (немає покупців, немає чеків за період) журнал не коментує ніяк.

Самі чеки шукайте у вікні «Документи»: колонка «Джерело: назва» — назва вашого шаблону, «Тип документа» розділить трійку, «№ документа (сайт)» — номер чека з каси, однаковий у всіх трьох, «Дата додавання (джерело)» — час чека на касі. Нові картки товарів видно у вікні «Товари» за тією ж колонкою «Джерело: назва», нових покупців — у «Контрагентах» за колонкою «Джерело - назва». За довшу історію відповідає кнопка «Історія запусків» у шапці картки шаблону.

Якщо завантажили не те

Спершу про те, чого зробити не вийде: зупинити прогін на середині не можна. Кнопка «Стоп» ставить позначку зупинки, а обмін із касою перевіряє її лише один раз, на самому початку. Натиснута посеред роботи, вона запише в журнал «Операція перервана користувачем!», але завантаження дійде до кінця. Сама позначка знімається на початку наступного запуску.

Далі — прибирання. Усе, що завів прогін, помічене джерелом, тож відбирається фільтром:

• Документи — вікно «Документи», колонка «Джерело: назва» дорівнює назві шаблону. Виділяєте потрібні рядки й видаляєте пачкою. Проведені документи пачка не видаляє: програма покаже, скільки їх пропущено.
• Товари — вікно «Товари», та сама колонка «Джерело: назва». У відбір потраплять лише картки, які створило це завантаження; ті, що у вас уже були, там не з'являться — та їх прогін і не змінював.
• Контрагенти — вікно «Контрагенти», колонка «Джерело - назва»: це покупці, заведені з картотеки каси.

Видалені документи не зникають назовсім: пачка потрапляє в «Кошик документів», звідки її можна повернути цілком. Кошик зберігає видалене 30 днів.

1

Дата початку завантаження замовлень

2

Група контрагентів

1. Завантаження замовлень починаючи з дати (РРРР-ММ-ДД) — з якої дати прогін забирає чеки.
2. Група контрагентів — група для «Кінцевого споживача».

Межі прогону

Скільки чеків можна забрати за раз. Стелі немає. Покупці й чеки приїжджають сторінками по 200 записів, рядки чека — разом із самим чеком, окремих запитів на них немає; сторінки добираються доти, доки каса каже, що є наступна.

За який період. Прогін бере чеки, створені пізніше за дату з поля «Завантаження замовлень починаючи з дати» мінус 12 годин, і після роботи сам пересуває цю дату на останній завантажений чек. Якщо поле порожнє, фільтра за датою немає взагалі — каса віддає всю свою історію. Саме тому перший прогін помітно більший за наступні, і робити його варто тоді, коли ви можете відразу подивитися на результат.

Зворотне вивантаження шле пачками по 100 записів: спершу створення, потім оновлення. Перед кожною пачкою оновлення Elbuz запитує ті самі 100 записів у каси — без цього вона правку не приймає.

У демонстраційному акаунті вивантаження обмежене першими 100 категоріями й 100 товарами; у робочому такої межі немає.

Навіщо зводити касу в Elbuz

Офлайн-точка й інтернет-магазин майже завжди торгують тим самим товаром з того самого складу. Поки каса живе окремо, залишок доводиться звіряти вручну, а виторг точки бачити тільки у звітах каси. Коли продажі приїжджають у Elbuz, картина складається: товар списується зі складу тим самим механізмом, що й інтернет-замовлення, гроші лягають у касові документи, а картотека покупців каси зводиться в ту саму базу контрагентів, що й покупці із сайту.

Сценарії

Продажі офлайн-точки в тих самих документах, що й замовлення сайту

Задача: бачити продажі каси в Elbuz поруч із замовленнями інтернет-магазину.

Що налаштувати: шаблон завантаження типу «dotykacka.pl (POS)», у картці «Підключення» — поля «Токен» і «ID інстанса (api_instance_id)»; запуск — кнопкою «Завантажити».

Що вийде: кожен оплачений чек стане трьома документами — «Витратна накладна», «Прибутковий ордер», «Замовлення покупця» — на контрагента «Кінцевий споживач». Чого не станеться: залишки наявних товарів не зміняться, доки документи не проведуть; покупець з картотеки каси в документ не потрапить; неоплачені чеки й документи інших типів не приїдуть.

Облік з певного дня, а не з усієї історії каси

Задача: каса працює давно, а в Elbuz потрібні продажі лише з дня переходу.

Що налаштувати: до першого запуску в картці шаблону, розділ «Розширене», впишіть дату в поле «Завантаження замовлень починаючи з дати (РРРР-ММ-ДД)».

Що вийде: приїдуть чеки, створені пізніше за цю дату мінус 12 годин. Якщо чеки приїхали, після прогону дата в полі сама пересунеться на найпізніший з них, тож наступний запуск продовжить звідти. Чого не станеться: чеки, раніші за дату мінус 12 годин, не завантажаться; якщо поле лишити порожнім, каса віддасть усю свою історію.

Постійні покупці каси — у базу контрагентів

Задача: покупці, заведені на касі для знижок і бонусів, мають бути в тій самій базі, що й покупці сайту.

Що налаштувати: окремо нічого — той самий шаблон «dotykacka.pl (POS)» забирає картотеку покупців на початку кожного прогону.

Що вийде: нові покупці заводяться в групу клієнтів; ті, кого Elbuz уже знає за ідентифікатором у касі, телефоном або поштою, дублем не стануть. Чого не станеться: покупець без телефону й без пошти не заведеться зовсім; картка наявного контрагента не оновиться; у документи з чеків покупець не підставиться.

Асортимент з Elbuz — на касу

Задача: ціни й назви ведуться в Elbuz, і каса має продавати за ними.

Що налаштувати: окремий шаблон вивантаження типу «dotykacka.pl», у картці «Що вивантажувати» — позначки «Категорії» і «Товари». У товарів має стояти прапорець «Вивантажувати у файл (на сайт)», а їхня категорія — бути увімкненою й позначеною до вивантаження.

Що вийде: спершу на касі з'являться категорії, потім товари; наступні вивантаження оновлюють ті самі записи, ціна без ПДВ рахується за ставкою податку товару. Чого не станеться: картки, заведені з чеків, на касу не поїдуть; товар, прибраний з вивантаження чи видалений в Elbuz, з каси не зникне; каса не списуватиме залишок при продажу.

Часті питання

Де взяти ID інстанса й токен Dotykacka?

ID інстанса — це номер вашої хмари, він видно в адресі кабінету після /cloud/. Токен створюється в кабінеті хмари, в розділі доступу до API: це refresh-токен, з якого Elbuz сам отримує робочий доступ перед кожною операцією.

Чому з одного чека створюються три документи?

Тому що продаж на касі має три наслідки для обліку: товар списується зі складу (витратна накладна), гроші надходять (прибутковий ордер) і продаж рахується у виторзі (замовлення покупця). Усі три документи посилаються на один чек — його номер стоїть у колонці «№ документа (сайт)» у кожного з них. Створюються вони непроведеними, тож саме завантаження складських рухів не робить.

Чому завантажилися не всі чеки?

Elbuz забирає тільки оплачені продажні чеки. Чернетки, службові документи й неоплачені рахунки пропускаються навмисно: в облік має потрапляти факт продажу. Також при регулярному запуску береться період від минулого завантаження з запасом у дванадцять годин, а не вся історія каси.

Чи створюються товари з каси в правильній категорії?

Ні. Категорію каса передає номером, а не назвою, і збігтися цей номер може лише з полем зовнішнього UUID вашої категорії — зворотне вивантаження його не заповнює. Тому нові позиції з чеків лягають у службову категорію «Товари - ‹код джерела› - ‹назва шаблону›»: вимкнену й поза вивантаженнями. Переносити картки звідти можна вільно, а от видаляти саму категорію разом з товарами не можна — з нею видаляться й товари, для яких вона основна.

Чи можна віддати товари з Elbuz на касу?

Так, для цього заводиться окремий шаблон вивантаження типу dotykacka.pl: спершу їдуть категорії, потім товари, наявне оновлюється, нове створюється. Ціну без ПДВ Elbuz рахує сам за ставкою податку, а одиниці виміру зіставляє з закритим переліком каси. Їдуть лише товари з прапорцем «Вивантажувати у файл (на сайт)», що лежать у ввімкненій і теж вивантажуваній категорії.

Чи затре повторне завантаження мої правки в документах?

Ні. Чек, який уже завантажений, прогін не чіпає взагалі: документ знаходиться за ідентифікатором чека в касі, і жодне його поле не переписується. Новими стають тільки ті чеки, яких у базі ще немає. Картки товарів завантаження чеків теж не переписує — з них беруться лише нові картки. А от зворотне вивантаження щоразу пише поверх каси: правку, зроблену на касі, воно поверне до значень Elbuz.

Що буде в Elbuz, якщо чек скасували на касі?

Три документи лишаться такими, як були: завантаження вміє тільки створювати документи й не змінює та не видаляє вже заведені. З каси беруться лише записи типу «чек» з ознакою «оплачено», тому повернення приїде в облік тільки тоді, коли каса оформила його таким самим оплаченим чеком; інакше зворотний рух роблять у Elbuz самостійно.

Як прибрати помилково завантажені чеки?

У вікні «Документи» відберіть рядки за колонкою «Джерело: назва» (назва вашого шаблону) і видаліть пачкою; проведені документи при цьому не видаляються. Видалене лягає в «Кошик документів» і повертається звідти цілою пачкою, кошик зберігає 30 днів. Товари й покупців прибирають так само у вікнах «Товари» і «Контрагенти» за колонкою джерела. Щоб завантажити той самий період заново, впишіть дату в поле «Завантаження замовлень починаючи з дати» в розділі «Розширене».