API та інтеграції

«Налаштування → API та інтеграції» має три вкладки: «API-ключі», «Вебхуки» та «Інтеграції».
API та API-ключі безкоштовні на кожному тарифі, зокрема на Free Forever; доповнення для API немає. Відмітки, поставлені через API, є Card Operations, як і будь-які інші, тож вони зупиняються, коли Card Operations тарифу закінчуються. Платна частина — вебхуки, див. нижче.
Чи коштує API додатково?
Ні. API та API-ключі безкоштовні на кожному тарифі, зокрема на Free Forever. Відмітки, поставлені через нього, є Card Operations, як і будь-які інші.
Чи можна користуватися API на Free Forever?
Так. Коли Card Operations тарифу закінчуються, відмітки через API зупиняються, як і будь-які інші.
Де налаштування API?
У «Налаштування → API та інтеграції», з трьома вкладками — «API-ключі», «Вебхуки» та «Інтеграції».
API-ключі

API-ключ створюють у «API-ключі → Додати API-ключ» для одного логіна персоналу. Логін персоналу має щонайбільше один API-ключ, а вимкнений логін персоналу вибрати не можна. Якщо вибрати немає кого, вікно «Генерація API-ключа» пропонує створити логін персоналу просто там; новому логіну персоналу потрібен вільний Staff Seat, а на заповненому тарифі вікно натомість пропонує додати місце або обрати тариф.
Кожен виклик з API-ключем діє від імені його логіна персоналу: він має доступ лише до бізнесу цього логіна персоналу, ставить відмітки на картку з відмітками, вибрану для нього в «Автоматичних відмітках», а його відмітки враховуються як Card Operations цього логіна персоналу.
Ключ можна будь-коли знову переглянути й скопіювати зі списку API-ключів. Його також можна показати як QR-код, щоб відсканувати в термінал, і надрукувати з назвою логіна персоналу.
Як створити API-ключ?
У «Налаштування → API та інтеграції → API-ключі» оберіть «Додати API-ключ» і виберіть логін персоналу. Кожен логін персоналу має щонайбільше один API-ключ.
Я загубив свій API-ключ. Чи потрібен новий?
Ні. Ключ можна будь-коли знову переглянути й скопіювати зі списку API-ключів або показати як QR-код.
На яку картку з відмітками ставлять відмітки виклики API?
На ту, яку вибрано для логіна персоналу ключа в «Автоматичних відмітках». Її відмітки враховуються як Card Operations цього логіна персоналу.
Чому я не можу вибрати логін персоналу для нового ключа?
Вимкнений логін персоналу вибрати не можна, а логін персоналу, який уже має ключ, не може отримати другий. Якщо вибрати нікого, вікно пропонує створити логін персоналу.
Коли API-ключ перестає працювати
API-ключ не має терміну дії. Він перестає працювати, лише коли його перегенерують чи видаляють або коли його логін персоналу вимикають чи видаляють. Новий пароль чи логін для логіна персоналу на нього не впливає.
- Перегенерувати дає логіну персоналу новий API-ключ; старий одразу перестає працювати.
- Видалити одразу зупиняє ключ. Сам логін персоналу й далі працює в 7Stamp Scanner і пізніше може отримати новий ключ.
- Вимкнення логіна персоналу зберігає його ключ: коли логін персоналу знову ввімкнуть, той самий ключ знову працює.
Чи має API-ключ термін дії?
Ні. Він перестає працювати, лише коли його перегенерують чи видаляють або коли його логін персоналу вимикають чи видаляють.
Я змінив пароль логіна персоналу. Чи потрібен новий API-ключ?
Ні. Новий пароль чи логін не впливає на API-ключ.
Я знову ввімкнув логін персоналу. Чи працює його старий API-ключ?
Так. Вимкнення логіна персоналу зберігає його ключ, і той самий ключ знову працює, щойно логін увімкнено.
Що робить API
Через API система може:
- видати картку з відмітками як посилання чи QR;
- додати відмітки;
- прочитати картку з її відмітками, цілями й ваучерами;
- видати ваучер прямо на картку;
- погасити ваучер за його номером ваучера;
- надіслати повідомлення покупцеві.
API знаходить картку покупця за власним ідентифікатором бізнесу, як-от ID у CRM, телефон чи email, надісланим як external_id. Ідентифікатор зберігається на картці й повертається в кожному вебхуку про неї. В API немає виклику, який повертає список покупців бізнесу: усю базу покупців вивантажують лише через експорт в адмін-панелі.
Замість API-ключа застосунок може входити з логіном і паролем логіна персоналу — для пристрою, у який входить касир. API-ключ підходить для пристрою, що працює без нагляду. Вебхуки додають лише в адмін-панелі; в API немає виклику, щоб підписатися на події чи отримати їх список.
API не встановлює обмеження частоти запитів: виклики не обмежуються ні кількістю, ні частотою, і ту саму картку можна одразу сканувати знову. Відмітки через нього обмежують Card Operations тарифу.
Чи можна додавати відмітки з нашої власної CRM або POS?
Так, через API. Він видає картки з відмітками, додає відмітки, читає картки й погашає ваучери. Щоб ваша система дізнавалася про події, додайте вебхук — для цього потрібне доповнення Webhooks & Events.
Чи можна експортувати дані?
Через API ви читаєте картки за вашим власним ідентифікатором, а вебхуки надсилають події, щойно вони стаються. В API немає списку всіх покупців — усю базу покупців вивантажують через експорт в адмін-панелі.
Як API знаходить картку покупця?
За вашим власним ідентифікатором — ID у CRM, телефоном чи email, — надісланим як external_id. Він зберігається на картці й повертається в кожному вебхуку про неї.
Чи можна підписатися на вебхуки через API?
Ні. Вебхуки додають лише в адмін-панелі.
Чи має API обмеження частоти запитів?
Ні. Виклики не обмежуються ні кількістю, ні частотою, і ту саму картку можна одразу сканувати знову. Відмітки обмежують лише Card Operations тарифу.
Довідник API
Довідник API публічний і не потребує входу: Swagger за адресою https://api.7loc.com/cards-api/docs, файл OpenAPI — за адресою https://api.7loc.com/cards-api/openapi.json. Виклики йдуть на https://api.7loc.com/cards-api і потребують API-ключа або логіна персоналу.
Бізнес з White Label не бачить в адмін-панелі посилання на довідник API. Його API-ключі й вебхуки працюють так само.
Де документація API?
Swagger за адресою https://api.7loc.com/cards-api/docs, публічний, без входу. Файл OpenAPI — за адресою https://api.7loc.com/cards-api/openapi.json.
Яка базова адреса для викликів API?
https://api.7loc.com/cards-api. Для викликів потрібен API-ключ або логін персоналу.
У нашій адмін-панелі White Label немає посилання на документацію API. Чи працює API для нас?
Так. Бізнес з White Label не бачить посилання на довідник, але його API-ключі й вебхуки працюють так само.
Вебхуки

Вебхук додають у «API та інтеграції → Вебхуки → Додати вебхук», з URL, який отримує події. У 7Stamp вебхук створюється для подій карток з відмітками. Бізнес може додати кілька вебхуків, кожен зі своїм URL.
Для вебхуків потрібне доповнення Webhooks & Events, 899 ₴ на місяць, доступне лише на платних тарифах. Додавання першого вебхука пропонує його купити; без нього вебхук не можна створити чи знову ввімкнути. Одне доповнення тримає ввімкненим один вебхук: додати можна більше, але кожне оновлення оплати підписки вимикає всі, крім найстарішого.
Вебхуки надсилають події, щойно вони стаються, з моменту, коли вебхук додано. Попередні події не надсилаються.
Чи безкоштовні вебхуки?
Ні. Для них потрібне доповнення Webhooks & Events, 899 ₴ на місяць, доступне лише на платних тарифах. Сам API безкоштовний.
Я додав другий вебхук, і його вимкнуло. Чому?
Одне доповнення Webhooks & Events тримає ввімкненим один вебхук. Кожне оновлення оплати підписки вимикає всі, крім найстарішого.
Чи надішле новий вебхук минулі події?
Ні. Події надсилаються з моменту, коли вебхук додано.
Події вебхуків
Вебхук отримує п’ятнадцять подій карток з відмітками, названих у event_type: SCAN, DELIVERY_INSERT, RECEIPT_SCAN, CARD_JOINED, REWARD_EARNED, VOUCHER_ISSUED, VOUCHER_PACK, ADMIN_VOUCHER_ISSUE, VOUCHER_REDEEMED, LOTTERY_WIN, CARD_CAMPAIGN, BIRTHDAY_GREETING, AUTO_MESSAGE_VOUCHER, CARD_ADDED_TO_WALLET і CARD_REMOVED_FROM_WALLET. Дві останні надходять, коли картку додають у гаманець або видаляють з нього, із зазначенням гаманця, Apple чи Google.
Скан, який не додає відмітки, наприклад покупка на суму, меншу за ціну відмітки, однаково надсилає SCAN з нулем доданих відміток. Про приз, виграний на колесі, повідомляє одна подія LOTTERY_WIN, коли колесо крутнули, а не REWARD_EARNED чи VOUCHER_ISSUED; колесо, яке чекає, щоб його крутнули, ще нічого не надсилає.
Відгуки покупців — не події карток з відмітками. Кожен новий відгук надсилає подію з entity review і action created на вебхуки, у яких на сторінці вебхука серед об’єктів позначено «Відгуки». Вебхук, доданий тут, налаштовано лише на події карток з відмітками, тож відгуки він отримує, щойно позначено «Відгуки».
Чи надсилається вебхук, коли скан не додає відмітки?
Так. Скан, який не додає відмітки, наприклад покупка на суму, меншу за ціну відмітки, однаково надсилає SCAN з нулем доданих відміток.
Яка подія повідомляє, що покупець виграв на колесі?
LOTTERY_WIN, яку надсилають один раз, коли колесо крутнули. Колесо, яке чекає, щоб його крутнули, ще нічого не надсилає.
Чи можна дізнатися, коли покупець видаляє картку зі свого гаманця?
Так. Додавання картки в гаманець і її видалення надсилають CARD_ADDED_TO_WALLET і CARD_REMOVED_FROM_WALLET із зазначенням гаманця, Apple чи Google.
Як отримувати нові відгуки покупців через вебхук?
Відкрийте сторінку вебхука й позначте «Відгуки» серед його об’єктів. Тоді кожен новий відгук надходитиме з entity review і action created; вебхук, доданий у «API та інтеграції», доти отримує лише події карток з відмітками.
Коли надсилається кожна подія
| Подія | Коли надсилається |
|---|---|
SCAN | Логін персоналу сканує картку: у 7Stamp Scanner, через API або з POS, як-от Toast. Відмітки, зняті в 7Stamp Scanner, — це SCAN з від’ємним stamps_added |
DELIVERY_INSERT | Покупець відкриває код відміток, який дає відмітки, — QR, посилання, сам код або запрошення, створене через API |
RECEIPT_SCAN | Покупець сканує фіскальний чек у чат-боті бізнесу, і на картку ставиться відмітка; amount — сума чека |
CARD_JOINED | Покупець отримує нову картку з відмітками, хоч би яким способом, з переданим вами external_id |
REWARD_EARNED | Скан досягає цілі Award |
VOUCHER_ISSUED | Скан досягає цілі з ваучером |
LOTTERY_WIN | Колесо Lottery крутнули, і воно дає приз |
VOUCHER_PACK | Нова картка отримує набір ваучерів картки з відмітками, усі його ваучери в одній події |
ADMIN_VOUCHER_ISSUE | Ваучер видано прямо на картку, в адмін-панелі або через API |
VOUCHER_REDEEMED | Ваучер на картці погашено: у 7Stamp Scanner, через API, на POS Toast або покупцем |
CARD_CAMPAIGN | Кампанія доходить до картки, один раз на картку, з ваучером кампанії, якщо він є |
BIRTHDAY_GREETING | Привітання з днем народження надсилається для картки, з ваучером на день народження, якщо його видано |
AUTO_MESSAGE_VOUCHER | Тригер автоповідомлення додає ваучер на картку, незалежно від того, чи дійде потім до покупця якийсь канал |
CARD_ADDED_TO_WALLET | Картку додано в Apple Wallet або Google Wallet |
CARD_REMOVED_FROM_WALLET | Картку видалено з гаманця |
Кожна ціль, якої досягає скан, надсилає власну подію після події скану, а ціль, досягнута двічі одним сканом за два кола картки, надсилає дві. Заповнена картка, що починає нове коло, — та сама картка й не надсилає CARD_JOINED; картка, видана знову після того, як адміністратор видалив стару, — надсилає. Коли приєднання приносить набір ваучерів і відмітки, спершу надходить CARD_JOINED, потім VOUCHER_PACK, потім DELIVERY_INSERT.
Код відміток без відміток не надсилає DELIVERY_INSERT, ваучер, згенерований в адмін-панелі без картки, не надсилає ADMIN_VOUCHER_ISSUE, а повторний виклик API для ваучера, який він уже погасив, не надсилає другої VOUCHER_REDEEMED.
Яка подія повідомляє, що покупець досяг цілі?
REWARD_EARNED для цілі Award, VOUCHER_ISSUED для цілі з ваучером і LOTTERY_WIN для Lottery — кожна надсилається після власної події скану.
Чи надсилається вебхук, коли відмітки знімають?
Так. Відмітки, зняті в 7Stamp Scanner, надходять як SCAN з від’ємним stamps_added.
Чим відрізняються VOUCHER_ISSUED і ADMIN_VOUCHER_ISSUE?
VOUCHER_ISSUED надходить, коли скан досягає цілі з ваучером. ADMIN_VOUCHER_ISSUE надходить, коли ваучер видають прямо на картку — вручну в адмін-панелі або через API.
Покупець, який приєднується з кодом відміток, надсилає одну подію чи кілька?
Кілька. Спершу надходить CARD_JOINED, потім VOUCHER_PACK, якщо картка з відмітками має набір ваучерів, потім DELIVERY_INSERT з відмітками.
Чи отримую я подію на кожне повідомлення кампанії?
CARD_CAMPAIGN надсилається один раз на кожну картку, до якої доходить кампанія, разом із ваучером кампанії, якщо він є.
Що отримує вебхук
Кожна подія має однакове тіло JSON: ID події, бізнес і подію з її типом, карткою з відмітками, відмітками до й після, сумою покупки, ID замовлення та external_id, які надіслала інтеграція, логіном персоналу, який її обслужив, ваучерами й нагородами, які вона дала, та ім’ям, email, Telegram, телефоном WhatsApp і датою народження покупця.
amount — сума покупки в мінорних одиницях (центах): сума 12.50, надіслана зі сканом, надходить як 1250. Поле порожнє, коли в події не було суми.
ID події є в тілі й у заголовку X-Webhook-Event-Id. Повторна спроба тієї самої події зберігає її ID, тож отримувач може відкидати повтори. Для URL Make чи Zapier подія лежить під ключем card_event замість data.
Які дані про покупця несе вебхук?
Ім’я, email, Telegram, телефон WhatsApp і дату народження, разом із карткою з відмітками, відмітками до й після та виданими ваучерами й нагородами.
У яких одиницях amount?
У мінорних одиницях (центах). Сума 12.50, надіслана зі сканом, надходить як 1250; поле порожнє, коли в події не було суми.
Як не обробити ту саму подію двічі?
Використовуйте ID події — у тілі й у заголовку X-Webhook-Event-Id. Повторна спроба зберігає той самий ID.
Чому в Make подія лежить під card_event?
Для URL Make чи Zapier подія лежить під ключем card_event замість data, щоб їхні застосунки могли її розпізнати.
Підпис
Кожна доставка підписана. Заголовок X-Webhook-Signature містить позначку часу й HMAC-SHA256 від цієї позначки часу та сирого тіла з секретним ключем вебхука. Секретний ключ показують і перегенерують на сторінці вебхука. Можна також додати логін і пароль Basic auth.
Як перевірити, що вебхук справді надходить від 7Stamp?
Обчисліть HMAC-SHA256 від позначки часу й сирого тіла із секретним ключем вебхука й порівняйте із заголовком X-Webhook-Signature.
Де знайти секретний ключ вебхука?
На сторінці вебхука, де його також можна перегенерувати.
Чи можна захистити свій endpoint паролем?
Так. До вебхука можна додати логін і пароль Basic auth, на додачу до підпису.
Невдалі доставки
Доставку, яка не отримала відповіді 2xx протягом тридцяти секунд, повторюють до десяти разів, щоразу чекаючи на чотири секунди довше, ніж попереднього разу, тож повтори закінчуються приблизно за чотири хвилини. Відповідь 429 з Retry-After повторюють після вказаного часу. Перша невдача події додає сповіщення в адмін-панелі.
Після ста невдалих доставок поспіль система блокує вебхук, і він більше не отримує подій. Його сторінка попереджає про це заздалегідь і має кнопку «Розблокувати»; одна успішна доставка обнуляє лічильник.
Сторінка кожного вебхука має журнал його доставок із надісланим запитом і отриманою відповіддю. «Надіслати повторно» надсилає ту саму подію ще раз, лише на цей вебхук.
Мій сервер не працював. Чи втрачено події?
Кожну доставку повторюють до десяти разів приблизно за чотири хвилини. Після цього відкрийте журнал вебхука й використайте «Надіслати повторно» для потрібних подій.
Чому мій вебхук перестав отримувати події?
Після ста невдалих доставок поспіль система його блокує. Виправте endpoint і натисніть «Розблокувати» на сторінці вебхука.
Чи можна побачити, що надіслано на мій вебхук?
Так. Сторінка кожного вебхука має журнал доставок із надісланим запитом і отриманою відповіддю.
Вкладка «Інтеграції»

Вкладка «Інтеграції» перелічує готові способи за групами:
- Відмітки на вашій касі — Poster, Toast, «Ваша власна каса чи CRM» і «Не бачите своєї каси?»;
- Фіскальні чеки — SmartKasa;
- Автоматизація — Make, Zapier і Public Swagger.
Кожна картка показує, чи потрібен їй API-ключ. Вкладка пропонує ті самі картки в кожній країні; за країною обмежені лише фіскальні чеки.

Бізнес з White Label не бачить карток Make, Zapier і Public Swagger, і йому не пропонують Poster та інструкції з налаштування на 7stamp.com.
Які POS-системи готові до підключення?
Poster, а також Toast, щойно його ввімкнуть для платформи, — доти він показує «Незабаром». Інші системи підключаються через API, з «Ваша власна каса чи CRM».
Чи обмежені інтеграції за країною?
Ні. Вкладка пропонує ті самі картки в кожній країні. За країною обмежені лише фіскальні чеки.
Чому я не бачу Make і Zapier?
Їх не показують бізнесу з White Label. Його API-ключі й вебхуки працюють так само.
Poster
Poster — наш застосунок у маркетплейсі Poster. «Встановити в Poster» відкриває його сторінку, а застосунок налаштовують з API-ключем логіна персоналу. Його відмітки враховуються як Card Operations цього логіна персоналу.
Як підключити Poster?
Відкрийте «Інтеграції → Poster» і оберіть «Встановити в Poster». Застосунок налаштовують з API-ключем логіна персоналу.
Чиї Card Operations витрачають відмітки з Poster?
Того логіна персоналу, чий API-ключ використовує застосунок.
Чи потрібен API-ключ для Poster?
Так, API-ключ логіна персоналу.
Toast
Toast показує «Незабаром» для кожного бізнесу, доки доступ до Toast не налаштовано на платформі. Це один перемикач для всієї платформи, а не налаштування бізнесу; щойно його ввімкнуть, картка Toast сама міститиме налаштування.
Кожну локацію Toast підключають за її GUID до одного логіна персоналу, без API-ключа: бізнес, картка з відмітками й тариф цього логіна персоналу застосовуються до кожного запиту Toast з локації. Локацію можна підключити лише до одного логіна персоналу, і логін персоналу має одну локацію. Запити з локації відхиляються, щойно її відключено, або поки її логін персоналу вимкнено чи видалено.
Кожному ваучеру можна призначити товар з меню Toast: тоді на POS Toast він стає знижкою на цей товар. Ваучер без товару застосовується як нульова знижка на чек, а касир видає подарунок вручну. Ваучери погашаються на POS Toast, а колесо, до якого привів оплачений чек, крутиться одразу. Коли Toast скасовує транзакцію, її відмітки знімаються або її погашені ваучери відновлюються.
Гість може приєднатися на кіоску Toast або на екрані для гостей за номером телефона чи email. Картку з відмітками видають одразу; гість нічого не отримує від 7Stamp, доки не відкриє її з тим самим телефоном чи email.
Чому Toast показує «Незабаром»?
Доступ до Toast — один перемикач для всієї платформи, а не налаштування вашого бізнесу. Доки його не ввімкнено, підключати нічого.
Як підключається локація Toast?
За її GUID до одного логіна персоналу, без API-ключа. Картка з відмітками й тариф цього логіна персоналу застосовуються до кожного запиту з локації.
Що стається з відмітками, коли Toast анулює чек?
Коли Toast скасовує транзакцію, її відмітки знімаються або її погашені ваучери відновлюються.
SmartKasa

SmartKasa не потребує API-ключа. Це джерело чеків у «Сканування чеків», яке додають за ID магазину SmartKasa або за кодом компанії, щоб охопити всі магазини. Покупці сканують чек SmartKasa в чат-боті бізнесу, а відмітки зараховуються логіну персоналу цього джерела чеків.
SmartKasa — українська система, а фіскальні чеки працюють лише в Україні, Словаччині, Казахстані та Узбекистані.
Чи потрібен API-ключ для SmartKasa?
Ні. SmartKasa — це джерело чеків у «Сканування чеків», яке додають за ID магазину або за кодом компанії.
Де покупці сканують чек SmartKasa?
У чат-боті вашого бізнесу. Відмітки зараховуються логіну персоналу цього джерела чеків.
У яких країнах працюють фіскальні чеки?
В Україні, Словаччині, Казахстані та Узбекистані.
Make і Zapier

Застосунок 7Stamp для Make є в публічному каталозі застосунків Make: знайдіть 7Stamp пошуком у будь-якому сценарії Make або скористайтеся «Відкрити в Make» на вкладці «Інтеграції». Нашого застосунку для Zapier немає в публічному каталозі Zapier: «Відкрити в Zapier» — це запрошення, яке додає застосунок у власний акаунт бізнесу в Zapier. Обидва застосунки працюють з API-ключем логіна персоналу.
Сценарії Make і Zap запускаються вебхуками 7Stamp, тож тригерам потрібне доповнення Webhooks & Events. Діям, як-от додавання відміток чи видача ваучера, потрібен лише API-ключ. Make і Zapier не пропонують бізнесу з White Label.
Де знайти застосунок 7Stamp у Make і Zapier?
У Make знайдіть 7Stamp пошуком у будь-якому сценарії — застосунок є в публічному каталозі застосунків Make. У Zapier він поки не публічний, тож скористайтеся «Відкрити в Zapier» на вкладці «Інтеграції» — запрошення додає застосунок у ваш власний акаунт.
Чи потрібне Make і Zapier доповнення Webhooks & Events?
Тригерам — так, бо сценарії й Zap запускаються вебхуками 7Stamp. Діям, як-от додавання відміток чи видача ваучера, потрібен лише API-ключ.
Чи потрібен API-ключ для Make чи Zapier?
Так. Застосунки працюють з API-ключем логіна персоналу.